Skill: higgsfield/higgsfield-soul-id (version 1.0.0)

--- version: 0.3.0 name: higgsfield-soul-id description: | Train a Soul Character — a personalized model on a person's face that Higgsfield uses for identity-faithful image and video generation. Use when: "create my Soul", "train my face", "make my digital twin", "build me an avatar", "learn my appearance", "create a character of me", "set up identity for video", "I want my face in generated images". Chain: train Soul (one-time, returns reference_id) → use in higgsfield-generate via `--soul-id <id>` with models like `text2image_soul_v2` or `soul_cinema_studio`. NOT for: one-shot face swaps (use higgsfield-generate with --image), named-character / non-photo avatars (use higgsfield-generate with prompt). argument-hint: "[name] [photo paths...]" allowed-tools: Bash --- # Higgsfield Soul Character Train a face-faithful identity model. Reusable across all Soul-powered generations. ## Step 0 — Bootstrap Before any other command: 1. If `higgsfield` is not on `$PATH`, install it: ```bash curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh ``` 2. If `higgsfield account status` fails with `Session expired` / `Not authenticated`, ask the user to run `higgsfield auth login` (interactive) and wait for confirmation. 3. Soul training requires a paid plan (Basic+). If `higgsfield account status` shows free plan, tell the user before submitting. ## UX Rules 1. Be concise. No raw IDs in chat. Just say "Soul ready" with a name reference. 2. Detect language and respond in it. CLI flags stay English. 3. Ask for the smallest set of inputs: name + photos. Pick a sensible model variant. 4. Polling is silent — training takes minutes. Don't repeat status updates. ## Workflow 1. **Get name.** One word, used for later reference. Ask if missing. 2. **Get photos.** 5–20 face photos, varied angles and lighting. Local paths or already-uploaded IDs both work — `--image` accepts either. 3. **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`. 4. **Submit.** ```bash higgsfield soul-id create --name "<name>" --soul-2 --image ./photo1.png --image ./photo2.png ... higgsfield soul-id create --name "<name>" --soul-2 --image <upload_id> --image <upload_id> ... ``` CLI auto-uploads paths. Captures returned reference id. 5. **Wait.** `higgsfield soul-id wait <id>`. Silent. Default timeout 30m. 6. **Deliver.** "Soul `<name>` ready. Use in generate with `--soul-id <id>`." ## Use the Soul Once trained, pass to `higgsfield-generate`: ```bash higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <ref_id> --wait higgsfield generate create soul_cinema_studio --prompt "..." --soul-id <ref_id> --wait ``` ## Listing existing Souls ```bash higgsfield soul-id list # all references higgsfield soul-id get <id> # one by id ``` ## Errors - `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 best - `references/troubleshooting.md` — common training failures

path: references/troubleshooting.md
content: # Soul Troubleshooting

## `Minimum Basic plan required`

Soul training needs a paid plan. Tell the user to upgrade.

## `Training failed`

Common causes:

- Too few photos (<5) or too uniform.
- Heavy occlusion (sunglasses, hats).
- Group photos confusing identity.
- Upload type mismatch (must be image uploads, not video).

Action: ask user to swap in better photos, retrain.

## `Session expired`

`higgsfield auth login`.

## Slow training

Default timeout is 30m. If still in progress: `higgsfield soul-id wait <id> --timeout 60m`.


path: references/photo-guide.md
content: # Photo Guide

What to upload for Soul training.

## Quantity

- Minimum 5, maximum 20.
- 8–12 is the sweet spot.

## Content

- Clear face, eyes visible.
- Single person per photo.
- No heavy filters, no sunglasses.

## Variety

Higher variety = better identity capture.

- Multiple angles: front, 3/4 left, 3/4 right, slight up/down.
- Different lighting: indoor, outdoor, soft, harsh.
- Different expressions: neutral, smiling, talking.
- Different distances: head shot, head-and-shoulders, full body.

## Quality

- Sharp, in-focus.
- Resolution ≥ 1024×1024 ideal.
- JPEG or PNG.

## Avoid

- Group photos.
- Heavy makeup not normally worn.
- Costumes / cosplay.
- Hats covering the face.
- Same pose repeated.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)