HeyGen Avatar Designer

AVATAR-<NAME>.md

Files & Paths

SOUL.md

IDENTITY.md

AVATAR-<NAME>.md

AVATAR-<NAME>.md

AVATAR-AGENT.md

AVATAR-USER.md

/tmp/openclaw/uploads/

heygen asset create

Language Awareness

user_language

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. MCP 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)

Before You Start (environment detection)

SOUL.md

• Found → OpenClaw environment. Skip this entire section and go straight to Phase 0. Workspace-native identity (SOUL.md, IDENTITY.md) will drive agent onboarding.
• Not found → Claude Code environment, no workspace identity files. Still go to Phase 0 next — do NOT skip ahead to listing user avatars or asking the user for a photo.

API Mode Detection

mcp__heygen__*

heygen

heygen --version

HEYGEN_API_KEY

heygen auth login

~/.heygen/credentials

--version

curl -fsSL https://static.heygen.ai/cli/install.sh | bash

heygen auth login

• 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

AVATAR-<NAME>.md

AVATAR-EVE.md      ← agent      (named, canonical)
AVATAR-KEN.md      ← user       (named, canonical)
AVATAR-CLEO.md     ← character  (named, canonical)

AVATAR-AGENT.md → AVATAR-<CURRENT-AGENT-NAME>.md   (symlink)
AVATAR-USER.md  → AVATAR-<CURRENT-USER-NAME>.md    (symlink)

# 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 MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

Skill Announcement

🎭 Using: heygen-avatar — creating an avatar for [name]

Workflow

Phase 0 — Who Are We Creating?

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.

AVATAR-<NAME>.md

• 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.

• 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.

AVATAR-<USER>.md

list_avatar_groups(ownership=private)

heygen avatar list --ownership private

Phase 1 — Identity Extraction

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 (e.g., Claude Code environment with no workspace identity) → 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.

• 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.

AVATAR-<NAME>.md

Reference Photo Nudge (user path only)

• 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.'"

• Photo provided → upload via MCP

  upload_asset

  or

  heygen asset create --file <path>

  , then Type B (photo) creation in Phase 2.
• Skip → Type A (prompt) creation in Phase 2.

Phase 2 — Avatar Creation

avatar_group_id

avatar_group_id

create_prompt_avatar(name=<name>, prompt=<appearance>, avatar_group_id=<optional>)

heygen avatar create -d '{"type":"prompt","name":"...","prompt":"...","avatar_group_id":"..."}'

-

create_photo_avatar(name=<name>, file=<file_object>, avatar_group_id=<optional>)

heygen avatar create -d '{"type":"photo","name":"...","file":{"type":"url","url":"..."},"avatar_group_id":"..."}'

• { "type": "url", "url": "https://..." }

  — public image URL

• { "type": "asset_id", "asset_id": "<id>" }

  — from

  heygen asset create --file <path>

• { "type": "base64", "media_type": "image/png", "data": "<base64>" }

  — inline

avatar_item.id

avatar_item.group_id

• age: Young Adult | Early Middle Age | Late Middle Age | Senior | Unspecified
• gender: Man | Woman | Unspecified
• ethnicity: White | Black | Asian American | East Asian | South East Asian | South Asian | Middle Eastern | Pacific | Hispanic | Unspecified
• style: Realistic | Pixar | Cinematic | Vintage | Noir | Cyberpunk | Unspecified
• orientation: square | horizontal | vertical
• pose: half_body | close_up | full_body

Appearance: "[prompt]" Settings: Young Adult | Woman | East Asian | Realistic Look good? (yes / adjust / completely different)

Phase 3 — Voice

user_language

Path A — Voice Design (preferred)

user_language

"A calm, warm female voice. Professional but approachable. Japanese speaker."

design_voice(prompt=<voice description>, seed=0)

heygen voice create --prompt "..." --seed 0

--gender

--locale

• Download each

  preview_audio_url

  to a temp path (any standard download method works — no HeyGen auth needed, these are public S3 URLs)
• Send as audio attachment:

  message(action:send, media:"<path>", caption:"Option <n>: <voice_name> — <gender>, <language>")

  so it plays inline in Telegram/Discord
• After all previews sent, present selection buttons

"None of these hitting right? I can try a different set (same description, different variations) or you can tweak the description."

seed

• Clean up /tmp files after user picks

Path B — Voice Browse (fallback)

list_voices(type=private)

list_voices(type=public, language=<lang>, gender=<gender>)

heygen voice list --type private

heygen voice list --type public --language <lang> --gender <gender>

1. Read the Voice section from the AVATAR file
2. Filter by gender and language
3. Pick top 3 candidates based on personality match
4. Present with inline audio previews (same download + send pattern as Path A)
5. ⛔ STOP. Wait for the user to pick. Do NOT auto-select.

Phase 4 — Save to AVATAR File

AVATAR-<NAME>.md

## HeyGen
- Group ID: <avatar_item.group_id — THE stable reference, never changes>
- Voice ID: <chosen voice_id>
- Voice Name: <voice name>
- Voice Designed: <true if custom-designed, false if picked from catalog>
- Voice Seed: <seed value used, if designed>
- Looks: <orientation>=<avatar_item.id> (e.g., landscape=<look_id>, portrait=<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 MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

user_language

Phase 5 — Maintain Role Alias

AVATAR-<NAME>.md

• Agent target → symlink

  AVATAR-AGENT.md

  →

  AVATAR-<NAME>.md

• User target → symlink

  AVATAR-USER.md

  →

  AVATAR-<NAME>.md

• Named character → no role alias. Named characters are referenced by name only (e.g.,

  AVATAR-CLEO.md

  ); they are not the agent or the user.

cd

ln -s

|| echo

# Agent
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-AGENT.md \
  || echo "role alias skipped: fs doesn't support symlinks"

# User
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-USER.md \
  || echo "role alias skipped: fs doesn't support symlinks"

ln -sf

IDENTITY.md

AVATAR-AGENT.md

AVATAR-AGENT.md

Phase 6 — Test (Optional)

create_video_agent(avatar_id=<avatar_id>, voice_id=<voice_id>, prompt=<greeting>)

heygen video-agent create --avatar-id <id> --voice-id <id> --prompt "..." --wait

user_language

Iteration Flow

• "Adjust the prompt" → Mode 2 with existing group_id (keeps the character, adds a new look). Only Mode 1 if they say "start completely over."
• "Add a new look" / "different outfit" → Mode 2 with existing group_id. Add to Looks in AVATAR file.
• "Try a different voice" → back to Phase 3
• "Start completely over" → Mode 1, new character. Overwrite HeyGen section.

UX Rules

Video Producer Integration

heygen-video

1. Named request ("Make a video with Eve") → read

   AVATAR-EVE.md

   .
2. Agent self-reference ("make a video of yourself", "give us a video update") → read

   AVATAR-AGENT.md

   (symlink to current agent's named file).
3. User self-reference ("make a video of me", "my video update") → read

   AVATAR-USER.md

   (symlink to current user's named file).
4. No AVATAR file or symlink → fall back to stock avatars or ask user.

cat AVATAR-AGENT.md

Error Handling

• Missing SOUL.md/IDENTITY.md → conversational onboarding, write AVATAR file from answers
• API fails → retry once, then ask user to check API key
• Voice match poor → show all available voices, let user browse
• Asset upload fails → skip reference image, try prompt-only creation
• Existing avatar file with stale HeyGen IDs → offer to regenerate or keep