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):

Agent	Install path
Claude Code	~/.claude/skills/heygen-skills
OpenClaw	~/.openclaw/workspace/skills/heygen-skills
Other	Clone anywhere your agent loads skills from

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:

Skill	What it does	Invoke
heygen-avatar	Photo → persistent digital twin (face + voice). Reusable across every video.	/heygen-avatar
heygen-video	Idea → script → prompt-engineered video with your avatar delivering the message.	/heygen-video
heygen-translate	Existing video → translated and dubbed version with voice cloning and lip-sync. 175+ languages.	/heygen-translate

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:

Priority	Mode	Trigger	Billing	Best for
1	CLI (API key)	HEYGEN_API_KEY is set	Direct API usage ($, separately billed)	Agents, CI, scripts
2	MCP (OAuth)	MCP tools visible AND no API key	HeyGen plan credits (no extra billing)	Users on a HeyGen plan
3	CLI (fallback)	heygen auth login session	Direct API usage ($)	Interactive CLI users

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:

Prompt	What happens
"Use heygen-avatar and heygen-video to make a 30-second cinematic intro of me as a founder. Ask me what you need."	Full pipeline: avatar → style recommendation → video. The wow moment.
"I want to make a product launch video. Use heygen-video and suggest the best style for it."	Skill recommends from 20 curated styles (A24, editorial, clean tech, etc.)
"Use heygen-avatar — I have a headshot. What kind of look would work best for a founder intro?"	Skill asks questions, recommends setting and tone before creating
"Use heygen-video to summarize this article as a 60-second explainer from my avatar: [URL]"	Fetches content, extracts key points, scripts and generates the video
"Use heygen-video to turn the key points from this PDF into a video update for my team: [file]"	PDF → script → avatar video. Any content becomes a video message.
"Use heygen-video for my team's weekly update. Ask me what shipped before writing the script."	Skill interviews you first, then writes and generates
"Use heygen-video to make a 20-second outreach video to a potential investor. What should I include?"	Skill guides the message, you approve the script, avatar delivers it
"Use heygen-avatar to give me a new look — ask me what vibe I'm going for."	Discovery flow: skill suggests options (outdoor, studio, casual, cinematic) before committing

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