CLAUDE.md — Higgsfield Skills

What this is

Seven skills that drive the higgsfield CLI — image/video generation, narrated explainers, browser games, Marketing Studio, Virality Predictor scoring, Soul Character training, branded product photography, marketplace cards, and full-stack websites.

higgsfield-soul-id     →  trains identity, returns reference_id
higgsfield-generate →  consumes reference_id, plus 30+ models, plus Marketing Studio
higgsfield-product-photoshoot  →  self-contained, brand visuals via gpt_image_2
higgsfield-marketplace-cards  →  marketplace main, secondary, and A+ style images
higgsfield-websites  →  build/edit/deploy full-stack sites via `higgsfield website …`
higgsfield-video-explainer  →  audio + video blocks assembled by `explainer_video`
higgsfield-game-generation  →  game design + assets + browser build + deploy

Repository structure

skills/
├── README.md                          # public-facing description
├── INSTALL.md                         # human-facing install (5 options)
├── INSTALL_FOR_AGENTS.md              # agent-driven install runbook
├── CONTRIBUTING.md                    # PR workflow + checklist
├── CLAUDE.md                          # this file
├── COOKBOOK.md                        # end-to-end recipes
├── CHANGELOG.md                       # generated by release-please (when wired up)
├── VERSION                            # repo-wide version (currently 0.3.0)
├── LICENSE
├── setup                              # bash, idempotent first-time install
├── scripts/
│   └── update-check.sh                # opt-in version check
├── .claude-plugin/
│   ├── marketplace.json               # Claude Code marketplace
│   └── plugin.json
├── .codex-plugin/plugin.json          # Codex
├── .cursor-plugin/plugin.json         # Cursor
├── .github/
│   ├── workflows/validate-skills.yml  # CI: frontmatter, version sync, refs, orphans
│   ├── ISSUE_TEMPLATE/
│   ├── pull_request_template.md
│   └── CODEOWNERS
├── higgsfield-generate/
│   ├── SKILL.md
│   └── references/
│       ├── model-catalog.md
│       ├── prompt-engineering.md
│       ├── media-inputs.md
│       ├── workflows.md
│       ├── marketing-{avatars,products,modes}.md
│       └── troubleshooting.md
├── higgsfield-soul-id/
│   ├── SKILL.md
│   └── references/{photo-guide,troubleshooting}.md
├── higgsfield-product-photoshoot/
│   └── SKILL.md
├── higgsfield-marketplace-cards/
│   └── SKILL.md
├── higgsfield-websites/
│   ├── SKILL.md
│   └── references/                    # stack, wow-maker, auth, fnf-sdk, seo-*, security-*
├── higgsfield-video-explainer/
│   ├── SKILL.md
│   └── references/prompts.md
├── higgsfield-game-generation/
│   ├── SKILL.md
│   ├── references/                    # design, build, 2D/3D, texture, audio, multiplayer
│   └── scripts/                       # deterministic texture/GLB/rig helpers
├── evals/                             # dev-only test infrastructure
│   ├── README.md
│   └── scenarios.md
└── assets/                            # logo, icon, demo GIFs
    └── README.md

API conventions

All skills route through one binary: the higgsfield CLI. Do not call api.higgsfield.ai directly with curl. The CLI handles auth, retries, polling, schema validation, and auto-uploads. Skipping it bypasses critical behavior.

Model and workflow knowledge

When FNF adds a model executor or chain executor, update the generate skill knowledge instead of relying on memory.

For models: - Update higgsfield-generate/references/model-catalog.md with the model's purpose and provider. - Update higgsfield-generate/references/media-inputs.md only for unusual media roles, transforms, single-media limits, video analysis, 3D, or audio. - Update higgsfield-generate/SKILL.md only when model routing/defaults change.

For workflows: - FNF may call these "chains"; public docs and user-facing instructions call them "workflows". - Verify public exposure with higgsfield workflow list and inspect schema with higgsfield workflow get <workflow_name>. - Update higgsfield-generate/references/workflows.md with the use case, create command, cost command when available, and result retrieval. - Use public command shapes: higgsfield generate workflow <workflow_name> ... --wait, higgsfield generate cost workflow <workflow_name> ..., and higgsfield generate get/wait <job_id>. - Do not add workflow-only entries to model-catalog.md. - Current public workflows are draw_to_video and reframe. Do not mention game_character_creator unless the CLI exposes it publicly and the user explicitly asks for it.

The 300-line rule

Each SKILL.md should aim for under 300 lines. Skill files are loaded into the agent's context whenever the skill triggers — every line costs latency and tokens.

The test: if removing a section from SKILL.md would NOT break the agent's ability to decide what to do next, it belongs in references/. If it WOULD break decision-making, it stays.

What stays in SKILL.md:

What moves to references/:

Self-contained skills

Each skill folder is independent. No ../ parent-directory references. Every file in references/ is reachable from that skill's SKILL.md. This lets each skill install standalone via gh skill install higgsfield-ai/skills <skill-name>, even though we ship them together.

If two skills happen to share a doc (e.g. both higgsfield-generate and higgsfield-soul-id have troubleshooting.md), keep separate copies. Drift between skills is acceptable as long as each skill is internally consistent. CI verifies self-containment on every PR.

Version sync

A single repo-wide version must match every skill and plugin manifest:

CI fails if any drift. Don't bump versions by hand on feature branches — let release automation handle it on merge to main (when wired up).

Skill chaining

Skills communicate through return values, not implicit state.

When the user asks for both identity AND output in one request ("train Soul on these photos AND make a video of me"), run higgsfield-soul-id first, then higgsfield-generate. Don't batch-ask questions across skills — finish Soul, then start the video conversation.

Adding a new skill

See CONTRIBUTING.md → "Adding a new skill". TL;DR: new top-level higgsfield-<name>/SKILL.md folder, follow the existing frontmatter convention (Use when triggers, Chain rules, NOT for boundaries), update marketplace.json, update README.md.

Eval discipline (when running evals)

When data exists, fix it in place:

Key Decisions (Do Not Revisit Without Data)

[Empty for now. Each entry should be a defended choice — "X over Y because: Z% on metric M across N runs." Adding here means the next contributor cannot revert without showing other numbers.]

Until then, treat any major default (model selection, mode selection, prompt enhancer behavior) as conventional rather than empirical.

Related projects