heygen

HeyGen Skills

AI agent skills for creating avatar videos. Your agent gets a face, a voice, and the ability to send video like a message.

Works with Claude Code, OpenClaw, Codex, Cursor, and other AI coding agents.

"Bring yourself to life — create your own avatar and make a 30-second intro video of yourself. Use heygen-avatar and heygen-video, ask me anything before you start."
→ reads your agent's identity files → asks only what's missing → builds the agent's avatar → picks the best style → generates the video → delivers the share link

Install

Paste this into your agent. It does the rest — clones the repo to the right path, asks for your HeyGen API key, picks the best transport, runs a verify test, and ends with a working video.

Read https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL_FOR_AGENTS.md and follow it.
Ask me for any API keys you need.

That's it. The agent fetches INSTALL_FOR_AGENTS.md and walks the rest of the install. Same prompt forever — the install spec lives in the repo, not in your clipboard.

Want to install manually instead? Follow the steps below.

Step 1 — Install the skills

The repo ships three skills: heygen-avatar, heygen-video, and heygen-translate. Pick the install path that matches your tooling.

Option A: gh skill install (works across Claude Code, Cursor, Codex, Gemini CLI, Copilot, Junie, Goose, OpenHands, Amp, Cline, OpenCode, Warp, and more — agentskills.io):

gh skill install heygen-com/skills heygen-avatar
gh skill install heygen-com/skills heygen-video
gh skill install heygen-com/skills heygen-translate

Requires GitHub CLI v2.90+. The CLI writes to the right directory for your agent automatically.

Option B: ClawHub:

clawhub install heygen-skills

Option C: OpenClaw plugin (bundles MCP support):

openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen

Option D: Git clone (legacy path):

git clone --single-branch --depth 1 https://github.com/heygen-com/skills.git <install-path>/heygen-skills

After cloning, the three skills are auto-discovered at heygen-avatar/SKILL.md, heygen-video/SKILL.md, and heygen-translate/SKILL.md.

Step 2 — Get your HeyGen API key

1. Go to app.heygen.com/api (Settings → API)
2. Generate a new API key
3. Save it somewhere safe — you can't view it again after the modal closes

Step 3 — Install the HeyGen CLI

One-line install (macOS / Linux):

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

Then set your API key:

export HEYGEN_API_KEY=<your-key>

That's ephemeral (current shell only). To persist across sessions, add export HEYGEN_API_KEY=<your-key> to your shell profile (~/.zshrc, ~/.bashrc, or equivalent).

Verify:

heygen --version
heygen auth status

The HeyGen CLI is a single static binary. No runtime deps.

Alternative: MCP (OAuth, no API key)

If you prefer OAuth and already have a HeyGen plan with credits, connect the remote MCP server instead of setting an API key. The skills will auto-detect MCP when no HEYGEN_API_KEY is set.

Claude Code:

claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/

OpenClaw: add to ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "heygen": { "url": "https://mcp.heygen.com/mcp/v1/" }
    }
  }
}

The first call triggers an OAuth consent flow in your browser.

Priority: If HEYGEN_API_KEY is set, the skills use the CLI. Otherwise they look for MCP tools. Set the key only if you want direct API access; otherwise use MCP.

Step 4 — Create your avatar

Ask the user for a photo (URL or file), then use the heygen-avatar skill:

Create my HeyGen avatar from this photo: [user's photo]

The skill uploads the photo, creates a persistent digital twin with a voice, and saves an AVATAR-<NAME>.md file for future use.

Step 5 — Make your first video

Use the heygen-video skill to generate an intro video with the avatar you just created:

Make a 30-60 second video of me introducing myself, casual tone.

The skill picks up the avatar automatically, writes a script, generates the video, and returns a share link.

That's it. You're set up. The avatar persists — every future video reuses it automatically.

What's Included

Three skills that work standalone or chain together:

heygen-avatar creates the identity. heygen-video uses it. heygen-translate localizes finished videos.

How It Works

Photo / Description          Avatar File              Finished Video
       ↓                        ↓                        ↓
  heygen-avatar    →    AVATAR-NAME.md       →    heygen-video
  (identity + voice)    (reusable state)          (script + video)

Skills communicate through AVATAR-<NAME>.md files. heygen-avatar writes them, heygen-video reads them. Human-readable and machine-readable.

Authentication

The skills support two auth modes with explicit priority:

Billing tradeoff: CLI mode bills against your HeyGen API usage (separately metered). MCP mode consumes your existing HeyGen plan credits — no extra API billing. Pick the mode that matches how you want to be charged.

CLI with API key (recommended for agents)

Get a key at app.heygen.com/api, then:

export HEYGEN_API_KEY=your-key-here

If HEYGEN_API_KEY is set, the skills use the CLI directly. No MCP probing. This is the most predictable setup for agent workflows.

The HeyGen CLI pattern is heygen <noun> <verb>. Output is JSON on stdout with stable exit codes.

• Verify: heygen auth status
• Alternative login: heygen auth login — interactive browser flow, persists to ~/.heygen/credentials

MCP (OAuth, no API key)

If you don't set an API key and HeyGen's remote MCP server is connected to your agent, the skills use MCP via OAuth. Calls run against your existing HeyGen plan credits.

• Endpoint: https://mcp.heygen.com/mcp/v1/
• Tool namespace: mcp__heygen__*
• MCP docs

You can have both configured — if HEYGEN_API_KEY is set, CLI wins.

Things to Try

After setup, try these prompts with your agent:

Requirements

• A HeyGen account — sign in via MCP (OAuth) or with an API key if you use the CLI fallback
• An AI agent that supports skills (Claude Code, OpenClaw, Codex, Cursor, or similar)
• No runtime dependencies. No packages. No build step.

Security

One optional shell script:

• scripts/update-check.sh — compares your local VERSION against the latest on GitHub. Read-only, opt-in, no data transmitted.

Data only leaves your machine through MCP / the heygen CLI (video generation) and optionally raw.githubusercontent.com (version check).

Looking for the v1 skills?

The previous version of this repo had individual skills for TTS, video translation, faceswap, video editing, and more. Those skills are preserved at heygen-com/skills-legacy.

Links

• HeyGen API Docs
• Repository
• Contributing
• Changelog

License

MIT