higgsfield-studio-soul-id
Skill1 starsChanged 4 days agoMITView on GitHub
Train a Soul on a person's face with Higgsfield, so later images and videos keep their identity. Triggers: 'create my Soul', 'train my face', 'make my digital twin', 'learn my appearance', 'put my face in generated images', 'create a character of me', 'soul id'. Part of Higgsfield Studio: training runs only after the user says yes, and every image made with the Soul is priced first and written to a ledger. Needs a Higgsfield paid plan, Node 18+ and the higgsfield command line tool.
In this repository21 other files it gives its agents.
- audio-narrateSkill
- audio-transcribeSkill
- cloudflare-opsSkill
- dokploy-opsSkill
- elevenlabs-studioSkill
- hetzner-opsSkill
- higgsfield-studio-brandkitSkill
- higgsfield-studio-marketplace-cardsSkill
- higgsfield-studio-product-photoshootSkill
- higgsfield-studioSkill
- higgsfield-studio-video-explainerSkill
- higgsfield-studio-websitesSkill
- higgsfield-studio-youtube-thumbnailSkill
- image-promptSkill
- namecheap-opsSkill
- plane-fleetSkill
- toolkit-credentialsSkill
- toolkit-updatesSkill
- video-promptSkill
- video-watchSkill
- zernio-opsSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Only train a Soul of the person asking, or of someone who has agreed to it.
- Very specific: line 45
Put --max N (a little above the price), --tag and --why "..." on every paid job.
- Very specific: line 46
Ask before spending more than about 10 credits, or 10% of what is left.
- Distinctive: line 66
Before any other command:
- Very specific: line 68
If higgsfield is not on $PATH, install it:
- Very specific: line 72
If higgsfield account status fails with Session expired / Not authenticated, ask the user to run higgsfield auth login (interactive) and …
- Distinctive: line 79
Ask for the smallest set of inputs: name + photos.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Higgsfield Soul ID
Train a Soul once from 5 to 20 photos of one person, then use it in any Soul model (text2image_soul_v2, soul_cinematic) with --soul-id <id>.
Only train a Soul of the person asking, or of someone who has agreed to it. Ask if it is not clear.
What it costs
Higgsfield gives no price for training in advance, so act soul-id create needs --yes, and the cost is measured from the account after it runs. We have not trained a Soul yet, so we have no measured figure. Tell the user that before they say yes. Images made with the Soul are cheap: text2image_soul_v2 and soul_cinematic were quoted at 0.12 credits each on 2026-10-12.
Training goes through the guard like this, after the user's yes:
node ../higgsfield-studio/scripts/hf.mjs act soul-id create --name "Sara" --soul-2 --image a.jpg --image b.jpg ... --yes --why "Soul for the spring campaign"Before anything else
sh ../higgsfield-studio/scripts/setup-deps.sh --check
node ../higgsfield-studio/scripts/hf.mjs checkThe first checks Node and the higgsfield tool, and sh ../higgsfield-studio/scripts/setup-deps.sh installs what is missing after asking. The second checks the sign-in. If Higgsfield is not signed in, the user signs in once with higgsfield auth login, which opens the browser. Never print the sign-in token or open the CLI's credential file.
Spending credits
This skill is part of the Higgsfield Studio plugin. Every paid command runs through the main skill's guard, node ../higgsfield-studio/scripts/hf.mjs. It asks Higgsfield for the price before running, refuses above --max or below the reserve, never pays twice for the same request, and writes what each job really cost to .higgsfield/ledger.jsonl in the project. The full rules are in ../higgsfield-studio/SKILL.md. The short form:
- Price first with
--dry, using every parameter the real job will use. Tell the user the total for anything over about 5 credits. - Put
--max N(a little above the price),--tagand--why "..."on every paid job. - Ask before spending more than about 10 credits, or 10% of what is left.
node ../higgsfield-studio/scripts/hf.mjs accountshows the balance. - Anything outward or not undoable goes through
actand needs--yes. Say what will happen and wait for the user's yes before adding it. - Report in plain words, in the user's language: where the file is, what it cost, what is left. No JSON or job ids unless asked.
Free commands, such as lists, model get, presets and uploads, can run as node ../higgsfield-studio/scripts/hf.mjs run <command> or as higgsfield <command> directly.
Updates
This skill is versioned with its plugin. Its version is metadata.version in the header of this file. The plugin's history, for every skill in it, is in ../higgsfield-studio/CHANGELOG.md. To check for a newer version, open the address on its Latest: line and compare the top version with this one. Read every entry in between and tell the user what changed before anything is updated.
Higgsfield's guide
Everything below is Higgsfield's official guide for this task, with its paid and outward commands already pointed at node ../higgsfield-studio/scripts/hf.mjs. The rules above win where the two differ.
Higgsfield Soul Character
Train a face-faithful identity model. Reusable across all Soul-powered generations.
Step 0 — Bootstrap
Before any other command:
- If
higgsfieldis not on$PATH, install it:sh ../higgsfield-studio/scripts/setup-deps.sh - If
higgsfield account statusfails withSession expired/Not authenticated, ask the user to runhiggsfield auth login(interactive) and wait for confirmation. - Soul training requires a paid plan (Basic+). If
higgsfield account statusshows free plan, tell the user before submitting.
UX Rules
- Be concise. No raw IDs in chat. Just say "Soul ready" with a name reference.
- Detect language and respond in it. CLI flags stay English.
- Ask for the smallest set of inputs: name + photos. Pick a sensible model variant.
- Polling is silent — training takes minutes. Don't repeat status updates.
Workflow
- Get name. One word, used for later reference. Ask if missing.
- Get photos. 5–20 face photos, varied angles and lighting. Local paths or already-uploaded IDs both work —
--imageaccepts either. - Pick variant.
--soul-2— for image generation (default)--soul-cinematic— for cinematic / video work Choose based on user's stated downstream use. Default to--soul-2.
- Submit.
CLI auto-uploads paths. Captures returned reference id.node ../higgsfield-studio/scripts/hf.mjs act soul-id create --name "<name>" --soul-2 --image ./photo1.png --image ./photo2.png ... node ../higgsfield-studio/scripts/hf.mjs act soul-id create --name "<name>" --soul-2 --image <upload_id> --image <upload_id> ... - Wait.
higgsfield soul-id wait <id>. Silent. Default timeout 30m. - Deliver. "Soul
<name>ready. Use in generate with--soul-id <id>."
Use the Soul
Once trained, pass to higgsfield-generate:
node ../higgsfield-studio/scripts/hf.mjs create text2image_soul_v2 --prompt "..." --soul-id <ref_id> --quality 2k --wait
node ../higgsfield-studio/scripts/hf.mjs create soul_cinematic --prompt "..." --soul-id <ref_id> --quality 2k --wait--soul-id is sent as the model's custom_reference_id. For a curated Soul style, list styles with higgsfield preset list soul-v2 and pass the chosen id as --style_id on text2image_soul_v2. --style_id cannot be combined with --image.
Listing existing Souls
higgsfield soul-id list # all references
higgsfield soul-id get <id> # one by idErrors
Minimum Basic plan required— user is on free plan; tell them.Training failed— check photos quality (5+ unique faces, well-lit).Session expired→higgsfield auth login.
Reference docs
references/photo-guide.md— what photos work bestreferences/troubleshooting.md— common training failures
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

