Jonathon's AI Wiki

higgsfield-ai/skills — Official Higgsfield AI Skills Bundle (Claude Code / Cursor / Codex)

11 min read

Source: ai-research/higgsfield-ai-skills-bundle-2026-05-06.md — README + COOKBOOK from higgsfield-ai/skills GitHub repo (MIT, 102 stars / 10 forks / 8 commits, v0.3.0).

Repo: https://github.com/higgsfield-ai/skills Stars: 102 Language: Shell (100%) License: MIT Version: 0.3.0

Higgsfield’s official, vendor-published agent-skills bundle — four Markdown-based skills that work in Claude Code, Cursor, Codex, and any other agent runtime that loads SKILL.md files. Wraps the existing Higgsfield MCP / Python SDK / CLI surfaces in a curated four-skill API: train a face once via higgsfield-soul-id, then drive image generation (higgsfield-generate), product photography (higgsfield-product-photoshoot), and marketplace listings (higgsfield-marketplace-cards) from natural-language prompts. The skills bundle is the CLI + Skill path the Nate Herk creative-agency tutorial argued is faster and more agent-friendly than MCP — now packaged officially.

Key Takeaways

  • Vendor-published, not community. This is Higgsfield’s own repo. Until now the Higgsfield MCP was the official agent surface; this bundle is the new official primary.
  • Cross-agent by design. Three plugin manifests at the repo root (.claude-plugin/ + .cursor-plugin/ + .codex-plugin/) plus Markdown SKILL.md format works in any agent that loads SKILL.md. Single source of truth, four runtimes.
  • Four bundled skills, three install paths. higgsfield-generate + higgsfield-soul-id + higgsfield-product-photoshoot + higgsfield-marketplace-cards. Install via npx skills add, gh skill install, or /plugin marketplace add inside Claude Code — each handles the underlying Higgsfield CLI install + auth automatically.
  • The skills CHAIN: train Soul → reuse reference_id everywhere. higgsfield-soul-id returns a reference_id; higgsfield-generate and Marketing Studio jobs consume it. One-time 15-45 min training, infinite reuse.
  • Backend-side prompt enhancement is the key architectural choice. product-photoshoot and marketplace-cards rewrite the user’s prompt before submitting to gpt_image_2 — explicit instruction in the README: “Avoid composing gpt_image_2 prompts manually.” The skill is the prompt engineer.
  • higgsfield-marketplace-cards is new (vs the Higgsfield MCP’s six pre-existing skills). Targets Amazon-style listing assets — main image, secondaries, A+ style modules — with hidden marketplace-compliant prompt templates the user never sees.
  • higgsfield-product-photoshoot exposes 10 modes. product_shot, lifestyle_scene, closeup_product_with_person, moodboard_pin, hero_banner, social_carousel, ad_creative_pack, virtual_model_tryout, conceptual_product, restyle. Each has its own prompt-enhancer template — picking the mode is the dominant lever, not the prompt copy.
  • higgsfield-generate Marketing Studio exposes 9 video modes. ugc (default), ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. Cookbook explicitly says modes are NOT interchangeable; pick the right one.
  • Model-routing defaults are baked in. Images route to gpt_image_2 / nano_banana_2 by default; video routes to seedance_2_0 (or kling3_0 as cheaper image-to-video fallback). The skill handles the cost/quality tradeoff.
  • MIT license, only 8 commits. Brand-new repo, vendor-driven, opt-in to fast iteration. Watchlist candidate.

The Four Skills

SkillSlash commandJob
higgsfield-generate/higgsfield:generateImage + video gen across 30+ models (Nano Banana 2, Soul V2, Veo 3.1, Kling 3.0, Seedance 2.0, Flux 2, GPT Image 2, …) + Marketing Studio (avatars + products + hooks)
higgsfield-soul-id/higgsfield:soul-idTrain a Soul Character — face-faithful identity model, returns a reference_id
higgsfield-product-photoshoot/higgsfield:product-photoshootBrand product imagery via 10 mode-specific prompt enhancers backed by gpt_image_2
higgsfield-marketplace-cards/higgsfield:marketplace-cardsAmazon-style marketplace product cards: main + secondaries + A+ style modules

The first three already appear as user-wide skills on a Claude Code install — visible in this repo’s available-skills list as higgsfield-generate, higgsfield-soul-id, higgsfield-product-photoshoot. The marketplace-cards skill is the newest of the four.

Install

npx skills — recommended cross-agent

npx skills add higgsfield-ai/skills

Claude Code marketplace

/plugin marketplace add higgsfield-ai/skills
/plugin install higgsfield@higgsfield

gh skill install (GitHub CLI v2.90+)

gh skill install higgsfield-ai/skills

Setup script (universal fallback)

git clone --depth 1 https://github.com/higgsfield-ai/skills.git
cd skills
./setup

Each method handles Higgsfield CLI install + auth. The INSTALL_FOR_AGENTS.md file is paste-able into any agent for fully agent-driven install.

product-photoshoot — 10 Modes

ModePurpose
product_shotProduct on neutral / studio / catalog background
lifestyle_sceneProduct in a real environment — hands, action, atmosphere
closeup_product_with_personTight crop with hands or partial face — beauty, demonstrating
moodboard_pinVertical 2:3 Pinterest-native pin, moodboard feel
hero_bannerWide-format website / email / campaign header
social_carousel3–10 connected slides for IG / LinkedIn / Facebook
ad_creative_packCoordinated pack of static ad variants for Meta / TikTok / Pinterest / Google
virtual_model_tryoutProduct worn or used by an AI-rendered model
conceptual_productSurreal / CGI-style / levitating / splash / sculptural product
restyleTransform an existing image’s aesthetic, mood, or seasonal context

Mode selection is the dominant lever — the backend rewrites the prompt for each mode before submitting to gpt_image_2.

generate Marketing Studio — 9 Video Modes

ModePurpose
ugcDefault. Casual, organic-feel content from a presenter
ugc_how_toTutorial / explainer
ugc_unboxingUnboxing reveal
product_showcaseClean product highlight, polished
product_reviewPresenter giving an opinion
tv_spotBroadcast-style commercial
wild_cardExperimental, model picks the vibe
ugc_virtual_try_onTrying on clothing — UGC vibe
virtual_try_onTrying on clothing — polished, model-driven

“Modes serve distinct purposes and aren’t replaceable. ugc reads as smartphone-captured organic material; tv_spot reads as professional broadcast-grade production. Don’t intermix them without deliberate creative reasoning.” — COOKBOOK

Quick Reference — pick a skill

What you wantSkillNote
Generate any image / video from a prompthiggsfield-generatePrefers gpt_image_2 / nano_banana_2 for images, seedance_2_0 for video
Image with my own facehiggsfield-soul-id THEN higgsfield-generateOne-time training, then --soul-id <ref>
Branded product photo (studio / lifestyle / Pinterest / hero / ad pack)higgsfield-product-photoshootMode-specific enhancer + gpt_image_2
Marketplace product cards / A+ style contenthiggsfield-marketplace-cardsHidden marketplace-compliant prompt templates
Branded ad video / UGC / unboxing / TV spothiggsfield-generate (Marketing Studio mode)avatars + products + optional hooks/settings
Train a custom face identityhiggsfield-soul-id5–20 photos → reference_id
Image-to-video animationhiggsfield-generateseedance_2_0 with --start-image; kling3_0 cheaper fallback

Three End-to-End Workflows (from COOKBOOK.md)

Workflow 1 — Brand Campaign from a Founder Photo

One headshot → trained Soul → 5 lifestyle product photos → top 2 animated to 5-second video clips.

User prompt:

Train my Soul on this headshot, then make 5 lifestyle photos of my product
[bottle.jpg] in scenes I'd post on Instagram, and animate the best 2 into
5-second clips. Save everything to ./campaign/.

Three CLI calls behind the scenes:

# 1. Soul training
higgsfield soul-id create --name "founder" --soul-2 \
  --image headshot1.png --image headshot2.png ... \
  --max-train-steps 1000
 
# 2. Lifestyle photoshoot — 5 variants in one call
higgsfield product-photoshoot create \
  --mode lifestyle_scene \
  --prompt "founder using product in 5 distinct IG-feed scenes: morning coffee, desk, café, gym, home office" \
  --image bottle.jpg \
  --count 5 \
  --output-dir ./campaign/photos
 
# 3. Top-2 image-to-video
higgsfield generate create kling3_0 \
  --prompt "subtle product reveal, camera slowly pulls back, ambient motion" \
  --start-image ./campaign/photos/lifestyle-01.jpg \
  --duration 5 --aspect_ratio 1:1 --sound off \
  --output-dir ./campaign/videos --wait

Cost optimization tip: --count 5 on photoshoot is cheaper and more visually consistent than 5 separate runs.

Workflow 2 — UGC Ad Batch from a Product URL

Shopify URL → 4 distinct ad styles in parallel (UGC + unboxing + product review + TV spot) at 9:16, 15s each. Zero asset uploads required.

# Fetch product
higgsfield marketing-studio products fetch \
  --url https://shop.example.com/sneakers --wait
 
# Pick a preset character matching brand vibe
higgsfield marketing-studio avatars list --json \
  | jq '.[] | select(.tags | contains(["sporty"]))'
 
# 4 modes in parallel
PRODUCT_IDS_JSON=$(mktemp); AVATARS_JSON=$(mktemp)
printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"
 
for mode in ugc ugc_unboxing product_review tv_spot; do
  higgsfield generate create marketing_studio_video \
    --prompt "<short hook tied to the mode>" \
    --avatars @"$AVATARS_JSON" \
    --product_ids @"$PRODUCT_IDS_JSON" \
    --mode $mode --duration 15 --resolution 720p --aspect_ratio 9:16 \
    --output-dir ./ads/$mode --wait &
done
wait

Creative tip: Hooks (--prompt) impact performance more than mode choice. Test 4 hooks × 1 mode before 1 hook × 4 modes.

Workflow 3 — Founder Video Update for the Team

Train Soul once → recurring 60-second team-update videos from a single instruction each week.

# One-time
higgsfield soul-id create --name "founder" --soul-2 \
  --image photo01.png --image photo02.png ... \
  --output-dir ./identity
# reference_id stored in ./identity/training-manifest.json
 
# Recurring — Marketing Studio with custom character
higgsfield generate create marketing_studio_video \
  --prompt "<full script with scene labels>" \
  --avatars @<custom-avatar-json> \
  --mode ugc --duration 60 --aspect_ratio 16:9 --wait
 
# Or recurring — direct Soul model (simpler, less branded)
higgsfield generate create soul_cinematic \
  --prompt "<full script>" \
  --soul-id <reference_id> \
  --duration 60 --aspect_ratio 16:9 --wait

Production tips:

  • For >30s talking-head: train with --soul-cinematic for vocal uniformity. --soul-2 is for shorter clips.
  • Author scripts for spoken delivery, not reading. ~150 words per minute target.
  • Don’t pad scripts to match runtime — overstuffed scripts produce hurried delivery.

Shared Patterns Across Workflows

  1. Train identity once, reuse forever. Soul training is 15–45 min one-time; every subsequent video featuring that face is single-prompt.
  2. Let the backend refine prompts for branded work. product-photoshoot augments prompts before submitting to gpt_image_2. “Avoid composing gpt_image_2 prompts manually” is the explicit instruction.
  3. Iterate cheaply, finalize expensively. Start with budget models (flux, z_image) for prompt exploration; switch to premium (nano_banana_pro, gpt_image_2) once direction is validated.
  4. Timestamped filenames. Format yyyy-mm-dd-hh-mm-ss-name.ext for traceability of which output came from which run.

Try It

  • Install via /plugin marketplace add higgsfield-ai/skills if you’re already a Claude Code user. Inside Claude Code: /plugin install higgsfield@higgsfield. Skills register, CLI installs, auth runs once.
  • Run Workflow 3 (Founder Video Update) as the lowest-effort first test: train Soul on 12 founder photos, then ask the agent to ship a 60-second team-update from a script. One-time setup pays off across every weekly update afterwards.
  • For WEO Marketly client work: the dental-practice equivalent of Workflow 1 is “train Soul on the dentist’s headshot, generate 5 office-tour photos, animate the best 2.” Direct fit for OmniPresence (internal WEO Marketly script-production system)|OmniPresence (internal WEO Marketly script-production system) script delivery without a recording session.
  • Use marketplace-cards for any Amazon FBA / e-commerce client. Hidden marketplace-compliant templates means the user doesn’t need to learn marketplace-image rules — the skill encodes them.
  • Compare with the existing Higgsfield MCP surface. The skills bundle is now the recommended primary; MCP is the lower-level integration layer. The Nate Herk thesis (CLI-over-MCP) is the architectural argument; this repo is the productization.

Implementation

Tool/Service: higgsfield-ai/skills (https://github.com/higgsfield-ai/skills) Runtime requirements: Claude Code, Cursor, Codex, or any agent loading Markdown SKILL.md files. Underlying Higgsfield CLI gets installed automatically by the skill setup. Setup: One install command (npx skills add higgsfield-ai/skills recommended). CLI install + auth is handled. Cost: Skills themselves are free + MIT-licensed. Generation costs are paid via the user’s Higgsfield account (per-call credits — see Higgsfield overview for credit pricing). Integration notes:

  • All four skills share Higgsfield CLI auth — install once, all four work
  • Soul reference_id from soul-id is consumable by generate and Marketing Studio jobs — preserve it across sessions in a persistent location
  • The plugin manifests in .claude-plugin/ / .cursor-plugin/ / .codex-plugin/ are the per-agent install hooks; only one is needed per machine
  • COOKBOOK.md, INSTALL.md, INSTALL_FOR_AGENTS.md, CONTRIBUTING.md, CLAUDE.md are the user-facing operating docs; the per-skill SKILL.md files are the agent-facing operating docs

Open Questions

  • Marketplace-cards detail. The README + COOKBOOK don’t document the modes for higgsfield-marketplace-cards (just “main image, secondary images, A+ style modules”). The skill’s own SKILL.md (in the repo) likely has the full mode list — worth a follow-up read.
  • Custom-avatar registration cost. Workflow 3 references higgsfield marketing-studio avatars create to register a Soul as a Marketing Studio custom character. Cost of this registration step is undocumented in the README.
  • text2image_soul_v2 vs gpt_image_2 inside product-photoshoot. COOKBOOK says you can swap to Soul models in photoshoot for facial continuity in animations — but product-photoshoot is described as backed by gpt_image_2. Implementation question: does --mode lifestyle_scene accept a model override, or is this a generate thing?
  • Skill update cadence. 8 commits as of fetch on 2026-05-06. Brand-new repo, MIT, vendor-shipped — likely fast iteration. Watchlist for v0.4+.
  • Eval harness in evals/. The repo has an evals/ directory but its contents and methodology aren’t surfaced in README/COOKBOOK. Worth a follow-up if this turns out to be vendor-published quality benchmarks.
  • Cross-agent feature parity. The README says works in “Claude Code, Cursor, Codex, and other AI coding agents that load Markdown-based skills” — but each runtime has its own skill-discovery mechanism. Are all four skills equally invokable in Cursor? Codex? Worth testing.
  • Cost vs higgsfield-mcp. Both surfaces ultimately call the same backend API. Is there a per-call overhead difference? Probably not — both end up at api.higgsfield.com. Confirms the Nate Herk CLI-over-MCP thesis is about agent-side ergonomics, not backend cost.

Graph View

Backlinks