version: "1.0.1" name: higgsfield-stack description: "Use when the user mentions the Higgsfield CLI (binaries higgsfield / higgs / hf, higgsfield auth login, higgsfield generate create, the @higgsfield/cli npm package), the Higgsfield MCP custom connector (mcp.higgsfield.ai/mcp), Higgsfield's bundled skills (higgsfield-generate / higgsfield-soul / higgsfield-product-photoshoot invoked as /higgsfield:generate etc.), or asks how this skill coexists with those tools (do I need both, how does this work with the CLI/MCP/skills)." user-invocable: true metadata: tags: [higgsfield, stack, cli, mcp, official-skills, coexistence, handoff, environment] version: 1.2.1 updated: 2026-05-18 parent: higgsfield

Higgsfield Stack — Coexistence With Official Tooling

What this sub-skill is for

"The Higgsfield stack" means Higgsfield's own official execution tooling: their command-line interface (CLI), their custom MCP connector for claude.ai and the Claude desktop app, and their three bundled skills (higgsfield-generate, higgsfield-soul, higgsfield-product-photoshoot). Any one of those tools — or any combination — may be present in the user's environment alongside this prompt skill. This sub-skill documents how the two surfaces coexist, what each one owns, and how a clean handoff looks.

The core principle is a layer split. This skill is the prompt-construction + production-discipline layer: MCSLA structure, named platform vocabulary, model selection criteria, Seedance preflight, Cinema Studio depth, Soul Character Anchor Block, Two-Tool Refinement Pipeline guidance, anti-bombast register, shared negative constraints. Their stack is the execution layer: authentication, file uploads, job submission, polling, retries, returning a result URL. Different jobs, no overlap. Our skill never invokes their CLI; their stack never invents prompt logic. The user gets one prompt from us and one execution path from them.

The three official surfaces

Preflight discipline — check cost and balance before generating

Every Higgsfield generation costs credits, and production-grade AI cinema runs at roughly 1.0% image and 1.5% video acceptance rates (production-benchmarks.md). On Veo, Kling, Sora-2, and Seedance-class video, a single un-checked job can swallow hours of budget. The preflight pattern is part of the Tier 1 Lock-before-generate discipline (DISCIPLINE.md) — lock the cost estimate alongside the prompt, before submission, on whichever surface the user is on.

This skill never invokes the preflight itself; it names the pattern. The execution layer owns the calls. Both MCP and CLI expose dedicated preflight surfaces — same underlying API, different invocation shapes.

Two-step preflight

Preflight is two steps, not one. The v3.7.10 release named only the second step (cost estimate); dogfooding immediately surfaced why the first step matters.

Step 1 — Verify the model's param schema. Models have bounded, enumerated params: aspect ratios are not free-form, durations have ranges, mode tags are model-specific. The schema is the ground truth; training-data knowledge of "what CLI flags usually look like" is not. Skip this step and you can produce a syntactically-valid preflight command that targets an invalid parameter value — the kind of mistake that hard-fails on submission and burns iteration time you thought you were saving.

Step 2 — Estimate cost against the now-verified schema.

Failure mode this prevents — plausibility-over-verification. The model knows enough about Higgsfield (and about CLIs generally, and about MCP schemas generally) to produce a plausible preflight call. Plausibility is not validity. Plausibility says --aspect-ratio 2.35:1 because hyphenated flags and cinematic anamorphic ratios are both prevalent in training data. Verification says --aspect_ratio 16:9 because that is what higgsfield model get kling3_0 returns. The discipline is to run the verification command that is sitting right there, not to trust the plausible answer. This pattern recurs across surfaces — see DISCIPLINE.md Tier 1 § Plausibility-over-verification for the cross-cutting framing.

Verified preflight surfaces

CLI naming gotcha. The canonical subcommand for balance is account status (alias acc status). account balance and account credits both fall through to parent help — they are not valid subcommands. Tell the user status if they go looking for balance.

CLI scripting note. Append --json to any of the above for machine-readable output. Useful when Claude Code is parsing the response inside a longer workflow.

Bundled skills note. The bundled skills (higgsfield-generate, higgsfield-soul, higgsfield-product-photoshoot) wrap generate create under the hood; they don't expose a parallel preflight slash command. Same auth, same workspace, so a one-line CLI cost check before the slash invocation is the cleanest pattern: higgsfield generate cost <model> --prompt "..." [...flags], then /higgsfield:generate.

Marketing Studio caveat. Per Higgsfield MCP tool descriptions, get_cost is not supported for marketing studio models. For those, run the job and read cost from the result, or check balance before and after.

Adjustments block (MCP). When get_cost: true is set on generate_image / generate_video, the response includes an adjustments object that surfaces which unset optional params the server defaulted (e.g. mode=std, sound=on). Surface these to the user alongside the credit cost — they are part of the preflight contract. The CLI's generate cost --json response does not currently include adjustments; if symmetry matters to the user, recommend the MCP path or pass each optional param explicitly on the CLI.

Plan tier, not surface, controls queue priority

All four surfaces share one credit pool and one job queue. Queue priority is a function of the user's paid Higgsfield plan tier (Plus / Ultra / Business / Team), not the choice of MCP vs CLI vs bundled skills vs paste-into-website. Surface choice affects ergonomics and authentication shape, not queue position:

• CLI is preferred for headless / CI / long-running batches because it uses long-lived API tokens rather than interactive OAuth round-trips. Per Higgsfield's own guidance on higgsfield.ai/mcp: "If you are using Claude Code or Codex, it's better to use the CLI."
• MCP is preferred for conversational generation inside claude.ai web, the Claude desktop app, or Claude Code in interactive mode — single OAuth, no token management.
• Bundled skills sit on top of the CLI; they inherit its auth model and tier behavior.

When a free-tier user reports MCP timeouts or queue stalls, the answer is plan tier, not "switch surfaces." Recommend upgrading the plan if iteration volume justifies it; recommend the CLI only if the workload is headless or non-conversational.

When to surface preflight in this skill's output

Add a preflight line to the output block whenever:

• The user has signaled they are about to execute (CLI / MCP / bundled skills mentioned).
• The model is video-class (Veo, Kling, Sora-2, Seedance, Hailuo, DoP) OR a high-cost image model (Nano Banana Pro at higher resolutions, GPT Image 2 at 4K).
• The user has named a budget constraint or credit-optimization concern.
• The work is iteration-heavy by structure (Cinema Studio multi-shot, Two-Tool Refinement Pipeline, multi-character anchor template).

Skip preflight surfacing for one-off image generation on a cheap model, or when the user is clearly just exploring vocabulary without intent to execute.

Iteration-budget projection (production-benchmarks tie-in)

When surfacing preflight cost, contextualize it against the acceptance-rate anchors in production-benchmarks.md. A single Kling 3.0 8s generation at 16:9 std mode costs 16 credits; the 1.5% video-acceptance anchor implies roughly 67 attempts on average to land one keeper — at 16 credits per attempt, that's about 1,000 credits per finished shot. Multiply by shot count for multi-shot sequences. The discipline isn't to surface the multiplied number every time — it's to make sure the user is reading single-shot cost in the context of iteration cost, not as an absolute. This is the same anchor that justifies the preflight pattern in the first place: iteration burn is the work, not the failure, and preflight is how you keep the burn visible.

How our skill fits in

USER REQUEST
   ↓
[ our skill — higgsfield-ai-prompt-skill ]
   • routes to the right sub-skill (prompt / camera / soul / cinema /
     seedance / etc.)
   • applies MCSLA (Model · Camera · Subject · Look · Action)
   • uses named platform vocabulary from `../../vocab.md`
   • appends shared negative constraints
   • runs `../../scripts/seedance_lint.py` preflight (Seedance prompts only)
   • produces a production-grade prompt
   ↓
[ hand-off to whatever execution surface the user has ]
   ↓
EXECUTION SURFACE (one of):
   • Higgsfield CLI — `higgsfield generate create <model_id> --prompt "..." --wait`
   • Higgsfield MCP — Claude calls the connector's generation tool
   • Higgsfield's bundled skills — `higgsfield-generate` takes the prompt
     and formats the underlying call
   • None — user copies the prompt into higgsfield.ai directly
   ↓
RESULT

The prompt always comes from us. The execution always comes from one of the four surfaces above. Nothing crosses the boundary in either direction.

Coexistence rules

1. Our skill always produces the prompt. Regardless of which execution surface the user has installed, prompt construction is this skill's job. MCSLA structure, named-vocabulary discipline, anti-bombast register, and the negative-constraints appendage all stay in our lane. If their bundled skill or their MCP tool wants a --prompt string, that string is our output, not theirs.

1. Their skills, CLI, and MCP never produce the prompt logic. Do not let higgsfield-generate or any MCP tool invent prompts on its own. If it offers to generate prompt text from a brief, route the brief through our skill first, then pass the resulting prompt down.

1. Do not duplicate their model-list call. Their CLI exposes higgsfield model list --json. This skill maintains its own curated model-selection criteria in ../../model-guide.md and ../../image-models.md. Do not shell out to model list from this skill — the curation is the value. If the user needs ground-truth current model IDs (e.g., a new model just shipped), point them to their CLI; do not try to keep our files in sync at runtime.

1. Do not bypass their CLI by calling `api.higgsfield.ai` directly. This is a hard rule. Auth, uploads, retries, polling, and rate-limit handling are non-trivial and live inside their CLI. This skill never shell-curls the API or writes code that calls the API directly. If the user has the CLI, route through it; if not, the user pastes into higgsfield.ai by hand.

1. Defer to their skill on execution flags. If the user has higgsfield-generate loaded and asks for, say, a Marketing Studio ad, construct the prompt body here, then hand the prompt text off. Do not try to remember their --avatars, --product_ids, --hook_id, --mode, or --format-id syntax — that is their domain and their version-to-version churn. We do the prompt; they do the invocation.

Naming collision — higgsfield-soul (theirs) vs higgsfield-soul (ours)

Higgsfield's bundled-skills repo includes a skill named higgsfield-soul (renamed from higgsfield-soul-id in their v0.3.0). This sub-skill library also has a sub-skill named higgsfield-soul at ../higgsfield-soul/SKILL.md. Same name, different jobs. The collision is real and worth disambiguating up front because both will trigger on user phrases like "Soul" or "Soul ID".

The rule is sequential, not overlapping. Theirs trains the identity. Ours constructs the prompt that uses the trained identity.

• When the user says "create my Soul" or "train a Soul ID from these photos" — that is their higgsfield-soul's job. Hand off; do not try to do it here.
• When the user says "write me three Soul prompts for scenes A / B / C using my reference_id" — that is our ../higgsfield-soul/SKILL.md's job. Construct the prompts; do not try to run training.

If the user is ambiguous ("help me with Soul"), ask which step they're on: training the identity, or prompting with an already-trained identity. One short question; do not split across multiple rounds.

Detection guidance

Before deciding whether to attach a handoff line, look for these signals that the Higgsfield stack is present in the current environment:

• Direct user statement — "I have the CLI installed", "I'm using their MCP", "I ran npx skills add higgsfield-ai/skills".
• Available MCP tools — the current Claude session exposes tools whose names mention Higgsfield generation. Suggests the MCP connector is attached.
• Skill files on disk — a SKILL.md for higgsfield-generate, higgsfield-soul (theirs, not ours), or higgsfield-product-photoshoot visible in the agent's skill directory. Suggests their bundled skills are installed.
• Command output or slash invocations — user pastes output from higgsfield ... or uses /higgsfield:generate, /higgsfield:soul, /higgsfield:product-photoshoot.
• In Claude Code specifically — which higgsfield returning a path, or higgsfield --version returning a version string.

If none of these signals are present, the user is on the paste-into-higgsfield.ai path. That is the default behavior of this skill — deliver the prompt, no handoff line needed.

Handoff templates

When one or more surfaces are detected, append one short line after the prompt. Keep the register plain — these are pointers, not promotions.

• CLI present:

If you want, you can run this directly with: higgsfield generate create <model_id> --prompt "<prompt above>" --wait

• MCP present:

You can invoke this via the Higgsfield connector — pass the prompt above as the prompt argument.

• Bundled skills present:

If you want to run this, their higgsfield-generate skill can take this prompt as its --prompt argument.

If multiple surfaces are present, pick the one that fits the user's stated workflow. Do not list all three. If none are present, do not append a handoff line at all.

Seedance preflight integration

The one place where this skill's tooling earns its keep inside the integrated flow is ../../scripts/seedance_lint.py. Seedance 2.0's content filter rejects instant-fail prompts before they reach the GPU, and the user gets charged credits regardless of whether the rewrite was the issue. The linter catches the predictable rejection patterns at prompt-construction time, before submission.

When the CLI is present AND the prompt being constructed is for Seedance 2.0 or Seedance Pro, append a recommendation:

Run python3 scripts/seedance_lint.py "<prompt>" before submitting to catch content-filter rejections. The filter is voice-based, not a keyword blacklist — see ../higgsfield-seedance/SKILL.md for the full diagnostic.

This is a recommendation to the user. This skill does not run the linter on the user's behalf and does not require the linter to have run before delivering the prompt.

What this sub-skill does NOT do

• Does not install, configure, or troubleshoot the Higgsfield CLI, MCP connector, or bundled skills. Point users to the upstream repos linked above for any of that.
• Does not replicate their model catalog — no equivalent of higgsfield model list runs from this skill.
• Does not run their CLI commands on the user's behalf. No Bash calls into higgsfield generate create, higgsfield soul-id create, or any other binary invocation.
• Does not absorb their skills' logic. higgsfield-generate knows how to format Marketing Studio invocations; this skill does not.
• Does not create a dependency on their stack being present. The full prompt-skill library remains functional standalone — the four execution surfaces (CLI, MCP, bundled skills, paste-into-website) are all valid, including the last one.

Related sub-skills

• ../higgsfield-prompt/SKILL.md — produces the prompt text that gets handed off to any execution surface.
• ../higgsfield-workspaces/SKILL.md — handles the upstream "which Higgsfield workspace fits my task" question, which is settled before any execution surface comes into play.
• ../higgsfield-seedance/SKILL.md — pairs with the ../../scripts/seedance_lint.py preflight recommendation above; covers the full filter diagnostic and prompt-mode router.
• ../higgsfield-assist/SKILL.md — credit-optimization questions apply regardless of execution surface; route credit/plan questions there.
• ../higgsfield-soul/SKILL.md — our Soul prompt-construction sub-skill. Read the Naming collision section above before routing — theirs trains, ours prompts.