--- 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 | Surface | What it is | Detection signals | Best fit | |---|---|---|---| | **Higgsfield CLI** | Binary distributed at https://github.com/higgsfield-ai/cli. Binary names: `higgsfield`, `higgs`, `hf`. Install via `curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh \| sh` or `brew install higgsfield-ai/tap/higgsfield`. Auth via `higgsfield auth login` (device flow). | User types `higgsfield`, `higgs`, or `hf` in conversation; user says "I have the CLI installed"; user pastes output from `higgsfield ... --json` | Claude Code, Codex, Cursor, or any terminal-native agent. Per Higgsfield's own guidance: if the user is in Claude Code or Codex, prefer the CLI over the MCP. | | **Higgsfield MCP** | Custom connector at https://mcp.higgsfield.ai/mcp. Separate product from the CLI. Installed in claude.ai or the Claude desktop app via Settings → Connectors → Add custom connector. | User is in claude.ai web or the Claude desktop app (not a terminal); user mentions "the connector" or "MCP" or `mcp.higgsfield.ai`; the current Claude session has tools whose names mention Higgsfield generation. | claude.ai web, Claude desktop app, environments without a terminal. | | **Higgsfield bundled skills** | Skill repo at https://github.com/higgsfield-ai/skills (v0.3.0). Three skills: `higgsfield-generate`, `higgsfield-soul`, `higgsfield-product-photoshoot`. Install via `npx skills add higgsfield-ai/skills`. Invoke as `/higgsfield:generate`, `/higgsfield:soul`, `/higgsfield:product-photoshoot`. | Skill files matching those names visible in the agent's skill directory; user invokes one of those slash commands; user mentions installing `higgsfield-ai/skills`. | Agents that consume Cowork-style skill bundles. All three skills drive the CLI under the hood — they are workflow/transport guidance, not prompt engineering. | --- ## 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. | Step | MCP | CLI | |---|---|---| | 1. Schema verify | `models_explore(action="get", model_id="")` | `higgsfield model get ` | | 2. Cost estimate | `generate_image` / `generate_video` with `get_cost: true` | `higgsfield generate cost [--param value]...` | **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 | Concern | MCP | CLI | Bundled skills | |---|---|---|---| | Schema verification (param enum, ranges, defaults) | `models_explore(action="get", model_id="")` | `higgsfield model get ` | Drop to CLI for the verify | | Cost estimate (no job submitted) | `generate_image` / `generate_video` with `get_cost: true` | `higgsfield generate cost [--param value]...` | Drop to CLI for the check, then run the slash command | | Credit balance + plan + email | `balance` tool | `higgsfield account status` | Drop to CLI | | Recent transactions (newest first) | `transactions` tool | `higgsfield account transactions --size N` | Drop to CLI | **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 --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 `../../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 --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. 2. **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. 3. **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. 4. **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. 5. **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". | | Theirs (`higgsfield-soul`) | Ours (`../higgsfield-soul/SKILL.md`) | |---|---|---| | Job | Train a Soul Character (face-faithful identity model) | Prompt-side character consistency discipline | | Input | 5–20 face photos plus a name | Free-form user request | | Output | A `reference_id` consumable by Soul-aware generation models | Production-grade prompt with Character Anchor Block, Identity/Motion separation, Two-Tool Refinement Pipeline guidance | | Invocation | `/higgsfield:soul` slash command, or `higgsfield soul-id create ...` from the CLI | Auto-loaded by our root dispatcher when character consistency is the topic | | Owns | Training run, polling, returning the `reference_id` | MCSLA structure for Soul prompts, Character Sheet creation, the 10-attribute pre-shot lock, multi-form state tracking | 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 --prompt "" --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 `../../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 seedance_lint.py "" 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 `../../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.