Skip to content

INSTALL_FOR_AGENTS.md

Latest commit

 

History

History
391 lines (291 loc) · 16.7 KB

INSTALL_FOR_AGENTS.md

File metadata and controls

391 lines (291 loc) · 16.7 KB
Raw

HeyGen Skills — Installation Guide for AI Agents

Read this entire file, then follow the steps. Ask the user for API keys when needed. Target: ~5 minutes to a fully working HeyGen integration.

This file is the agent-facing companion to INSTALL.md (human-facing). Where they overlap, this file is canonical for agent-driven installs.

Step 0: If you are not Claude Code

Read CLAUDE.md at the repo root first. It describes the runtime contract for these skills (mode detection, hard rules, transport-only-once). Claude Code reads it automatically; other agents should fetch it explicitly.

If you fetched this file by URL without cloning yet, the companion files live at:

  • https://raw.githubusercontent.com/heygen-com/skills/master/CLAUDE.md — runtime contract for the skills
  • https://raw.githubusercontent.com/heygen-com/skills/master/heygen-avatar/SKILL.md — avatar creation skill (mode detection ladder, hard rules, full creation workflow)
  • https://raw.githubusercontent.com/heygen-com/skills/master/heygen-video/SKILL.md — video generation skill (mode detection ladder, hard rules, full producer pipeline)
  • https://raw.githubusercontent.com/heygen-com/skills/master/heygen-translate/SKILL.md — video translation / dubbing skill (mode detection ladder, hard rules, proofreads workflow)
  • https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL.md — human-facing install doc

Step 1: Detect the agent host and pick the install path

Detect which agent is running before cloning. Each host expects skills at a different path. If you are not sure, ask the user "which AI coding agent are you running this from?"

Agent host Default install path
Claude Code ~/.claude/skills/heygen-skills
OpenClaw ~/.openclaw/skills/heygen-skills
Codex ~/.codex/skills/heygen-skills
Cursor ~/.cursor/skills/heygen-skills
Hermes ~/.hermes/skills/heygen-skills
Other Whatever path the host loads skills from. Ask the user.

OpenClaw users running a workspace-scoped install may have skills under ~/.openclaw/workspace/skills/heygen-skills instead — check the value of the host's --dir / workdir config. The default above is canonical for non-workspace installs and matches INSTALL.md.

# Replace <install-path> with the row from the table above:
git clone --single-branch --depth 1 \
  https://github.com/heygen-com/skills.git \
  <install-path>

For OpenClaw users, the fastest install path is ClawHub — it short-circuits Steps 1, 3, and 4 below (clones to the right path, registers with the host, and sets up the install metadata in one command):

clawhub install heygen-skills

After ClawHub install, jump straight to Step 2 (API key) and then Step 5 (avatar creation).

Step 2: Get the user's HeyGen API key (or detect MCP)

First, detect whether the user already has the HeyGen MCP server connected. If mcp__heygen__* tools are visible in the toolset, MCP is the path of least resistance — OAuth, no key handling, consumes the user's HeyGen plan credits.

If MCP is detected and the user is happy with it, skip to Step 5 (avatar creation). But before you do, warn them:

If you set HEYGEN_API_KEY later for any reason, the skill will short-circuit MCP detection (per the mode-detection ladder in heygen-video/SKILL.md or heygen-avatar/SKILL.md) and use the CLI / direct-API route instead. MCP plan credits won't be touched. To switch back to MCP, unset HEYGEN_API_KEY.

If MCP is not connected, ask the user for their HeyGen API key. They get it from app.heygen.com/api (Settings → API → New Key). Tell them: the key is shown once, copy it before closing the modal.

The HeyGen API is currently pay-as-you-go in credits — no free tier. Avatar V costs roughly 6 credits per minute of generated video. Make sure the user has credits or is on a paid plan before proceeding. Pricing changes; if the user asks for current rates, point them at help.heygen.com/api-pricing.

Step 3: Save the API key in the standard location

The key needs to be available to whichever transport the user picks in Step 4. The safe default is to set it as an environment variable in the user's shell profile.

# In ~/.zshrc, ~/.bashrc, or wherever the user's shell loads env vars:
export HEYGEN_API_KEY=hg_...

Then ask the user to either restart their shell or source the file. The agent's process inherits the parent shell's env — if the agent runs in a separate process from the user's terminal, they'll need to restart the agent host, not just re-source the shell.

If the user prefers a project-local key, drop it in .env and tell the user to never commit it. The .env.example file shows the expected variable name.

For the OpenClaw plugin path (Step 4 Option A), the key is read from the same HEYGEN_API_KEY env var. The plugin does not require a separate config step.

Step 4: Pick a transport

These skills route the actual HeyGen API call through one of three transports. The skill auto-detects which transport is available at runtime via the mode-detection ladder in each skill's SKILL.md (e.g. heygen-video/SKILL.md or heygen-avatar/SKILL.md):

  1. OpenClaw plugin if video_generate exposes heygen/video_agent_v3
  2. CLI (API-key override) if HEYGEN_API_KEY is set AND heygen --version exits 0
  3. MCP if no API key set AND mcp__heygen__* tools visible
  4. CLI (fallback) if MCP unavailable AND heygen --version exits 0

The critical rule: setting HEYGEN_API_KEY short-circuits MCP detection. If the user wants MCP-credit billing, do not set the key.

Pick a transport based on the user's host and preferences:

Option A: OpenClaw plugin (preferred for OpenClaw users)

Ships HeyGen as a first-class provider for OpenClaw's video_generate tool. Auth, polling, and error handling are native. Cleanest integration.

openclaw plugins install openclaw-plugin-heygen

The plugin reads HEYGEN_API_KEY from the environment (set in Step 3). Restart the gateway to pick up the new provider registration:

openclaw gateway restart

Verify the plugin loaded:

openclaw plugins list | grep heygen

The skill detects the plugin by checking whether video_generate exposes heygen/video_agent_v3 as a model. When detected, the heygen-video sub-skill routes the final video-generate call through video_generate(...) instead of spawning a CLI process.

Option B: HeyGen CLI (works with any agent that can shell out)

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

Then sign in:

heygen auth login

The CLI persists the key to ~/.heygen/credentials. The skill detects the CLI via heygen --version.

Option C: HeyGen MCP server (Claude Desktop, Claude Code with MCP, OpenClaw with MCP)

If MCP is already wired up, the skill detects mcp__heygen__* tools and uses them. No CLI install needed. Auth is OAuth; consumes the user's HeyGen plan credits (not API credits).

To wire MCP from scratch, follow your agent's MCP setup docs and point it at https://mcp.heygen.com/mcp/v1/. We can not configure that from inside this skill. See INSTALL.md for example configs.

Step 5: Give the agent a face (canonical install outcome)

This is the step the install is actually for. Until now we've installed files and wired auth. Now we make the thing the user came here for: an avatar the agent can use to present videos.

Default subject is the agent, not the user. The heygen-avatar sub-skill is built around the agent getting a face by default. Route to a user-avatar only on explicit "my avatar" / "me" / "my photo" language. When in doubt, make the agent's avatar.

If you are running in an OpenClaw workspace with SOUL.md and IDENTITY.md

This is the canonical path. The agent has documented identity files; the skill reads them and designs a presenter that matches.

Read heygen-avatar/SKILL.md and follow Phase 0. The skill will:

  1. Read SOUL.md and IDENTITY.md from the workspace root.
  2. Ask one or two clarifying questions about design direction (not a batch form — walk the phases in order, one or two questions at a time).
  3. Generate the avatar via the Avatar V pipeline (prompt-based by default; photo opt-in only for real-person digital twins).
  4. Save AVATAR-<AGENT-NAME>.md at the workspace root for future reuse.
  5. Maintain the AVATAR-AGENT.md symlink (or AVATAR-USER.md for user-target installs) pointing at the named file, so generic self-reference requests ("make a video of yourself" / "my video update") resolve without name lookup.
  6. Return avatar_id + voice_id for use in Step 7 (defaults).

On the happy path, this step ends with both a named file (e.g. AVATAR-EVE.md, AVATAR-ADAM.md, AVATAR-CLEO.md) and a role-based symlink (AVATAR-AGENT.md for agent target, AVATAR-USER.md for user target) at the workspace root. Named files are canonical; symlinks are pointers that consumer skills (heygen-video) can read for generic self-reference. Note that the heygen-avatar skill has a Phase 2 STOP gate before generation; if the user aborts there, no file is written and no credits are spent. That's the correct behavior — it's a confirmation gate, not a bug. Resume by re-invoking the sub-skill.

If you are running outside an OpenClaw workspace (no SOUL.md)

Claude Code, Codex, Cursor, and Hermes don't have workspace identity files. The avatar still gets created, but the skill asks the user for the design direction directly instead of reading from SOUL.md.

Same entry point: read heygen-avatar/SKILL.md and follow Phase 0. The skill detects the missing SOUL.md and switches to Phase 1 conversational onboarding — it asks the user about appearance, voice, and presenter persona one or two traits at a time, not as a single batch prompt.

Skip conditions (rare)

Skip Step 5 only if:

  • The user has explicitly said "I already have an avatar, just make a video" (they have an existing avatar_id / voice_id they want to reuse).
  • The install is purely scoped to video generation with stock avatars (the user picks from HeyGen's catalog per-call).

In either case, jump to Step 6. Otherwise, the install is incomplete without this step.

Step 6: Verify the install (opt-in)

Ask the user: "Want to run a 5-second smoke test? It generates a real video, costs roughly half a credit, and confirms the integration works end-to-end."

If yes, branch on whether Step 5 ran:

If Step 5 created an avatar:

Use heygen-video to generate a 5-second test clip with the avatar from
AVATAR-<NAME>.md saying "HeyGen install working, ready to ship." Save
the file locally and tell me the path.

If Step 5 was skipped (user has an existing avatar_id they want to reuse, or scoped install to stock avatars):

Use heygen-video to generate a 5-second test clip with avatar_id
<the user's avatar_id> and voice_id <the user's voice_id> saying
"HeyGen install working, ready to ship." Save the file locally and tell
me the path.

Expected outcome: a .mp4 file roughly 1-3 MB, 5 seconds long, with the avatar speaking the test line.

If the user declines, skip to Step 7. The skill works either way; the smoke test just removes uncertainty about whether everything is wired correctly.

If the smoke test fails, the most common causes (in order):

  1. HEYGEN_API_KEY not in current shell. Re-source the shell profile or restart the terminal / agent host.
  2. No credits on the account. Tell the user, then point them at app.heygen.com/billing.
  3. Transport not detected. Run heygen --version (Option B) or check openclaw plugins list (Option A) to confirm the path exists.
  4. waiting_for_input state from the Video Agent. The skill set mode incorrectly — see the heygen-video sub-skill's review-checkpoint handler. Re-read the sub-skill SKILL.md.

Step 7: Set agent-wide defaults

This step only applies if Step 5 ran (the user has a new AVATAR-<NAME>.md) OR if the user already has an avatar_id / voice_id they want to reuse on every call. If neither, skip to Step 8.

When it applies, save the ids as defaults so the user doesn't repeat them per-call.

For the OpenClaw plugin path (Option A), use openclaw config set:

openclaw config set plugins.entries.heygen.config.defaultAvatarId "<avatar_id>"
openclaw config set plugins.entries.heygen.config.defaultVoiceId  "<voice_id>"
openclaw config set plugins.entries.heygen.config.defaultStyleId  "<style_id>"

For the CLI path (Option B), there are no avatar / voice / style config defaults: heygen config set <key> <value> only supports the keys analytics and output. Keep the ids in the AVATAR-<NAME>.md file (or your own notes) and pass them to each command.

For the MCP path (Option C), there are no per-skill defaults; the agent passes avatar / voice ids per call. If Step 5 ran, the AVATAR-<NAME>.md file is the source of truth and the agent reads it on each video generation. If Step 5 was skipped, the user provides ids per call directly.

Step 8: Make HeyGen the default video provider (OpenClaw plugin path only)

If the user wants video_generate(...) to default to HeyGen when no model is specified:

openclaw config set agents.defaults.videoGenerationModel.primary "heygen/video_agent_v3"

This is purely an OpenClaw concern and does not affect Claude Code, Codex, or Cursor users.

Step 9: Done

The skills now have everything they need: a transport, an authenticated account, an avatar identity, and (optionally) defaults for repeated use. Tell the user:

HeyGen Skills are installed. Your agent now has a face: AVATAR-<NAME>.md. Try:

  • "Make a 30-second video of yourself introducing what we're working on this week"
  • "Send a video update to the team about today's progress"
  • "Generate a 60-second product walkthrough using my avatar"
  • "Translate this video into Spanish, Japanese, and German" (heygen-translate)

The skill handles avatar resolution, prompt engineering, aspect ratio correction, voice selection, and Frame Check automatically. Give it a topic, let it do the rest.

Upgrade

cd <install-path>/heygen-skills && git pull origin master

If the install was via ClawHub:

clawhub update heygen-skills

Re-read the active skill's SKILL.md (heygen-avatar/SKILL.md or heygen-video/SKILL.md) after the upgrade if the version bumped — the mode detection ladder occasionally adds new transports (e.g. when MCP support shipped, when the OpenClaw plugin shipped).

Troubleshooting

The agent says HEYGEN_API_KEY is not set, but the user already exported it. The export only applies to the shell that ran it. If the agent is in a separate process (most agents are), the export needs to be in ~/.zshrc or ~/.bashrc and either re-sourced or used in a fresh shell.

The CLI works in the terminal but the agent says it can't find it. The agent's PATH is different from the user's interactive shell. Tell the user to add ~/.local/bin (or wherever the CLI lands) to a PATH that the agent inherits.

waiting_for_input from the Video Agent. The skill is calling the Video Agent in chat mode by accident. Re-read the heygen-video sub-skill — it should always pass mode: "generate" for one-shot video creation. If you patched the sub-skill, you may have introduced this regression.

MCP tools listed but the skill is using the CLI / plugin instead. The skill follows the mode-detection ladder in its SKILL.md (heygen-avatar or heygen-video): plugin → CLI (API-key override) → MCP → CLI (fallback). HEYGEN_API_KEY being set short-circuits MCP detection. If the user wants MCP to be the chosen transport, unset the env var (unset HEYGEN_API_KEY) and re-detect. If the plugin is also installed, uninstall it (openclaw plugins uninstall openclaw-plugin-heygen) so MCP wins detection.

What this skill does NOT do

  • It does not handle account creation. The user must already have a HeyGen account with API access.
  • It does not bill or upgrade the user's HeyGen plan. If they run out of credits, point them at app.heygen.com/billing.
  • It does not store or transmit the API key anywhere outside the local agent environment. The key stays in the user's shell or in the agent host's config; the skill never logs it.