heygen-avatar

# HeyGen Avatar Designer Create and manage HeyGen avatars for anyone: the agent, the user, or named characters. Handles identity extraction, avatar generation, voice selection, and saves everything to `AVATAR-<NAME>.md` for consistent reuse. ## Files & Paths This skill reads and writes the following. No other files are accessed without explicit user instruction. | Operation | Path | Purpose | |-----------|------|---------| | Read | `SOUL.md`, `IDENTITY.md` | Extract identity details when creating an avatar for the agent | | Read | `AVATAR-<NAME>.md` | Load existing avatar identity (for variant looks, voice updates) | | Write | `AVATAR-<NAME>.md` | Save new avatar identity after creation | | Write | `AVATAR-AGENT.md`, `AVATAR-USER.md` (symlinks) | Role aliases, see Phase 5 | | Temp write | `/tmp/heygen/uploads/` | Voice preview audio (downloaded for user playback, deleted after session) | | Remote upload | HeyGen (via CLI/API asset upload) | Local photos/videos uploaded to HeyGen before avatar creation | Assets are only uploaded to HeyGen when the user explicitly provides them. ## Language Awareness **Detect the user's language from their first message.** Store as `user_language` (e.g., `en`, `ja`, `es`, `ko`, `zh`, `fr`, `de`, `pt`). 1. **Communicate with the user in their language.** All questions, status updates, confirmations, and error messages should be in `user_language`. 2. **Voice design prompts and selection respect `user_language`.** When designing or selecting a voice, specify the target language so the voice library returns matches that speak it. 3. **Technical directives stay in English** — enum values (`Young Adult`, `Realistic`, `landscape`, etc.) are API-level and not translated. ## UX Rules 1. **Be concise.** No avatar IDs, group IDs, or raw API payloads in chat. Report the result (avatar created, ready to use) not the plumbing. 2. **No internal jargon.** Never mention internal phase names ("Phase 0", "Phase 5 Symlink Maintenance") to the user. The user sees natural conversation: "Setting up your avatar\u2026" not "Running Phase 2 avatar creation." 3. **One or two questions per phase.** Don't batch-ask. Walk phases in order, ask the smallest set of questions needed to proceed. 4. **Read workspace files before asking.** `SOUL.md`, `IDENTITY.md`, `AVATAR-*.md` at the workspace root contain identity. Check them first. Only ask the user for what's genuinely missing. 5. **Don't narrate skill internals.** Never say "let me read the workflow," "checking the reference files," "loading the avatar discovery guide." Read silently. The user sees questions and results, not internal navigation. 6. **Don't announce what you're about to do.** Skip meta-commentary like "Creating the avatar now." Just do the work. If a step takes time, the next thing the user hears should be the result (or a checkpoint question). 7. **Never narrate transport choice.** App vs CLI is internal. Pick the transport silently and never mention it. If both are unavailable, ask the user to configure one without explaining why. ## Start Here (Critical) **Default target = the agent.** The primary use of this skill is giving the agent a face + voice so it can present videos. Route to "user" only on explicit "my avatar" / "me" / "my photo" language. When in doubt, make the agent's avatar. **Do NOT batch-ask questions.** No "give me a photo, voice preference, duration, target platform, tone, key message" all at once. Walk phases in order. Each phase asks at most one or two things at a time. **For agent avatars: read SOUL.md and IDENTITY.md first, then go straight to prompt-based creation.** Do NOT ask the user for a photo or appearance details first. The agent's identity lives in those workspace files. Only ask the user for traits that are genuinely missing. **Prompt-based is the default creation path.** Photo is opt-in, only relevant when the user explicitly wants a real-person digital twin of themselves. Agents and named characters almost always use prompt-based creation. ## Before You Start (environment detection) Try to read `SOUL.md` from the workspace root. - **Found** → Workspace-native identity files are available. Skip this entire section and go straight to Phase 0. `SOUL.md` and `IDENTITY.md` will drive agent onboarding. - **Not found** → No workspace identity files are available. Still go to Phase 0 next — do NOT skip ahead to listing user avatars or asking the user for a photo. **⚠️ AVATAR file caveat:** Ignore any AVATAR-*.md files found in the workspace that belong to a *different* person or agent (e.g., `AVATAR-Eve.md` when creating an avatar for a different subject). Only use an AVATAR file if its name matches the subject you're creating for right now. **⚠️ Do NOT fetch HeyGen avatars yet.** That's a Phase 0 sub-step (only after target detection). Fetching before Phase 0 causes the agent to frame the conversation around "your existing avatars" when the default should be creating one for the agent itself. ## API Mode Detection **Mode selection is silent.** Detect once at the start of the session, pick a mode, move on. Never narrate transport choice ("CLI is broken", "switching to the app") — the user doesn't care how calls are made. **HeyGen app (preferred):** If the HeyGen app is available through the installed app integration, use it. The app authenticates via OAuth and runs against the user's existing HeyGen plan credits. **Auth triage (run immediately):** run `command -v heygen` and `heygen auth status`. If app/MCP auth fails but CLI auth is valid, continue in CLI mode for this run. **Local media limitation:** The current HeyGen app connector does NOT upload local files. Its photo/video/avatar tools accept only hosted HTTPS URLs or existing HeyGen `asset_id` values. Never pass `file://`, absolute local paths, or Codex attachment paths directly to app tools. For local photos/videos, first upload with `heygen asset create --file <path>` or `POST https://api.heygen.com/v3/assets` using `multipart/form-data`; then pass `{ "type": "asset_id", "asset_id": "..." }` to the app or CLI creation call. If no CLI/API upload path is available, ask the user for an HTTPS image URL or permission to continue with prompt-only creation. **CLI fallback:** If the app is not available AND the `heygen` binary runs cleanly (`heygen --version` exits 0), use it. Auth: `HEYGEN_API_KEY` env OR `heygen auth login` (persists to `~/.heygen/credentials`). If the CLI is missing, errors on `--version`, or auth is not set, silently skip it. In Codex desktop/sandboxed runs, CLI network calls may fail with DNS/network errors until network approval/escalation is granted. Retry with escalation when needed. **Neither available:** Only if the app is unavailable AND the CLI doesn't work, tell the user once: "To use this skill, connect the HeyGen app or install the HeyGen CLI: `curl -fsSL https://static.heygen.ai/cli/install.sh | bash` then `heygen auth login`." If the only missing capability is local media upload, say that local photos need an HTTPS URL or a CLI/API asset upload first. **API:** v3 only. Never call v1 or v2 endpoints. **Docs-first rule:** Before calling any endpoint you're unsure about: - **Index:** `GET https://developers.heygen.com/llms.txt` — full sitemap - **Any page:** Append `.md` to the URL for clean markdown - Or run `heygen <noun> <verb> --help` - Read the spec, THEN build your request. Never guess field names. ## Avatar File Convention Every avatar gets one file: `AVATAR-<NAME>.md` at the workspace root. ``` AVATAR-EVE.md ← agent (named, canonical) AVATAR-KEN.md ← user (named, canonical) AVATAR-CLEO.md ← character (named, canonical) ``` The skill also maintains two **role-based symlinks** alongside the named files, for generic lookups by consumer skills (e.g., heygen-video) when the request doesn't carry a specific name ("make a video of yourself" → read the agent alias; "make a video of me" → read the user alias): ``` AVATAR-AGENT.md → AVATAR-<CURRENT-AGENT-NAME>.md (symlink) AVATAR-USER.md → AVATAR-<CURRENT-USER-NAME>.md (symlink) ``` Named files are the single source of truth; aliases are pointers and never drift. Phase 5 of the workflow maintains them. Named characters get NO role alias — they are referenced by name only. Format: ```markdown # Avatar: <Name> ## Appearance - Age: <natural language> - Gender: <natural language> - Ethnicity: <natural language> - Hair: <natural language> - Build: <natural language> - Features: <natural language> - Style: <natural language> - Reference: <optional workspace-relative path or URL> ## Voice - Tone: <natural language> - Accent: <natural language> - Energy: <natural language> - Think: <one-line analogy> ## HeyGen - Group ID: <character identity anchor — THE stable reference, never changes> - Voice ID: <matched or designed voice> - Voice Name: <human-readable> - Voice Designed: <true if custom-designed, false if picked from catalog> - Voice Seed: <seed value used, if designed> - Looks: landscape=<look_id>, portrait=<look_id>, square=<look_id> - Last Synced: <ISO timestamp> ⚠️ look_ids are ephemeral — always resolve fresh from group_id at runtime via `heygen avatar looks list --group-id <id>` (or the corresponding HeyGen app tool). Never hardcode look_id as the primary avatar reference. ``` **Top sections** (Appearance, Voice) are portable natural language. Any platform can use them. **HeyGen section** is runtime config with API IDs. Skills read this to make API calls. ## Skill Announcement Start every invocation with: > 🎭 **Using: heygen-avatar** — creating an avatar for [name] ## Workflow **DO NOT batch-ask questions upfront.** Walk phases in order. Each phase asks at most one thing at a time, and only if needed. ### Phase 0 — Who Are We Creating? See the Start Here block above for the default-to-agent rule. Only route to "user" or "named character" when the phrasing is unambiguous. Routing signals (in priority order): 1. **User** (explicit only) — "create **my** avatar", "make **me** an avatar", "I want my face in a video", "a digital twin of **me**", "based on **my** photo". Requires a possessive pronoun referring to the user OR explicit mention of their photo. Ask for their name if not obvious. 2. **Named character** (explicit only) — "create an avatar called Cleo", "design a character named X", "build a presenter named Y" → use the given name. 3. **Agent** (default) — everything else: "create your avatar", "bring yourself to life", "set up an avatar", "let's make an avatar", "create an avatar", "design a presenter", "I want you to appear in videos", or any ambiguous phrasing. Read `IDENTITY.md` for name. **When unsure, default to agent.** Do NOT ask the user for their name, appearance, or voice on an ambiguous request — that's the wrong first move. If after reading IDENTITY.md + SOUL.md the intent still feels ambiguous, ask one short clarifying question to disambiguate (phrase it naturally — something like "quick check: this avatar is for you, or for me?"). Then check `AVATAR-<NAME>.md` at the workspace root: - **AVATAR file exists + HeyGen section filled in** → "You already have an avatar set up. Want to add a new look, update it, or start fresh?" Wait for answer. - **AVATAR file exists but HeyGen section empty** → skip to Phase 2. - **No AVATAR file** → proceed to Phase 1. **Role alias staleness check.** Before proceeding, also check whether the role alias for this target is already pointing at the right named file: - For **agent target**: read `AVATAR-AGENT.md` (follow symlink) and compare to `AVATAR-<CURRENT-AGENT-NAME>.md`. If they differ (e.g., `AVATAR-AGENT.md` → `AVATAR-OLD-NAME.md` because the agent identity changed since the last run), re-link in Phase 5 even if no other changes are made. The named file is canonical, but the alias must match the *current* identity, not the historical one. - For **user target**: same check on `AVATAR-USER.md`. - For **named character**: no alias to check. **Optional existing-avatar check** (only useful on the user path when the user might already have avatars in their HeyGen account). If Phase 0 target = **user** AND no `AVATAR-<USER>.md` exists, list their HeyGen avatars first: **App:** use the HeyGen app to list private avatar groups **CLI:** `heygen avatar list --ownership private` If the list is non-empty, present the options and ask which to use or whether to create new. If empty, proceed to Phase 1. Skip this check entirely for agent and named-character targets — those live in AVATAR-*.md, not the HeyGen catalog. ### Phase 1 — Identity Extraction **Order matters. Files first, questions second. Prompt-based creation is the default path — photo is an opt-in upgrade.** **For the agent** (Phase 0 target = agent): 1. Read `SOUL.md`, `IDENTITY.md`, and any existing `AVATAR-<NAME>.md` from the workspace root. 2. If SOUL.md or IDENTITY.md is found → extract appearance and voice traits silently. Do NOT ask the user "describe your appearance" — the agent IS the subject, and its identity lives in those files. **If the files describe only personality / values with no physical description, do NOT hallucinate traits.** Ask the user conversationally for the missing appearance traits only (one or two at a time). 3. If neither file is found (for example, in a workspace with no identity files) → ask the user to describe the agent's appearance and voice conversationally. 4. Proceed directly to **Type A (prompt) creation** in Phase 2 by default. Do NOT ask for a photo unless the user volunteers one or explicitly asks for photo realism — agents almost always use prompt-based creation. **For users/named characters** (Phase 0 target = user or named): - Conversational onboarding. Ask naturally about appearance and voice — one or two questions at a time, not a form. Communicate in `user_language`. - **User path only:** after the onboarding Q&A, run the Reference Photo Nudge below. - **Named character path:** skip the nudge, go straight to Type A (prompt) creation. Write `AVATAR-<NAME>.md` with the Appearance and Voice sections filled in. Leave the HeyGen section empty until Phase 2 succeeds. ### Reference Photo Nudge (user path only) Only run this step when Phase 0 target = **user** (real-person digital twin) OR when the user explicitly asks for photo realism. - Check AVATAR file's Appearance → Reference field first. If a photo is already on file, skip asking and use it. - Otherwise, ask one sentence: *"Got a headshot? It gives better face consistency for videos of you. I can also generate from your description — just say 'skip.'"* Branch: - **Photo provided as local file/path** → upload via `heygen asset create --file <path>` or `POST https://api.heygen.com/v3/assets`, then Type B (photo) creation with the returned `asset_id`. - **Photo provided as HTTPS URL or asset_id** → Type B (photo) creation in Phase 2. - **Local photo but no upload path available** → ask for an HTTPS image URL or offer prompt-only creation. Do not pass the local path into the app connector. - **Skip** → Type A (prompt) creation in Phase 2. For agents and named characters, skip this entire step — go straight to Type A (prompt) creation. ### Phase 2 — Avatar Creation 📖 **Full creation API surface (photo / prompt / digital twin), file input formats, identity field → enum mapping, response shape → [references/avatar-creation.md](references/avatar-creation.md)** Two modes: **Mode 1 — New character** (omit `avatar_group_id`): Creates a brand new character with its own group. **Mode 2 — New look** (include `avatar_group_id`): Adds a variation to an existing character. Read the Group ID from the AVATAR file. Two creation types: **Type A — From prompt (AI-generated appearance):** **App:** use the HeyGen app flow for prompt-based avatar creation. **CLI:** `heygen avatar create -d '{"type":"prompt","name":"...","prompt":"...","avatar_group_id":"..."}'` (accepts inline JSON, a file path, or `-` for stdin) Prompt limit is 1000 characters. Be descriptive — include style, features, expression, lighting. The API spec says 200 but the actual enforced limit is 1000. **Type B — From reference image:** **App:** use the HeyGen app flow for photo avatar creation only with an HTTPS URL or pre-uploaded `asset_id`. **CLI:** `heygen avatar create -d '{"type":"photo","name":"...","file":{"type":"asset_id","asset_id":"..."},"avatar_group_id":"..."}'` File options for Type B: - `{ "type": "url", "url": "https://..." }` — public image URL - `{ "type": "asset_id", "asset_id": "<id>" }` — from `heygen asset create --file <path>` Do not pass local paths or `file://` URLs to the app connector. Upload local files to an `asset_id` first. Raw API upload example: ```bash ASSET_ID=$(curl -s -X POST "https://api.heygen.com/v3/assets" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -F "file=@/path/to/headshot.jpg" | jq -r '.data.asset_id') ```