HeyGen Skills: Agent Skills That Give a Coding Agent a Face and a Voice
HeyGen AI agent skills — avatar creation and video production via the v3 Video Agent pipeline
At a glance
- What is it?
- heygen-com/skills is a set of three agent skills (heygen-avatar, heygen-video, heygen-translate) that let a coding agent create a persistent avatar, script and render videos, and dub existing footage. The design is interesting because the skills talk to each other through plain markdown files rather than a shared service, but the whole thing depends on a paid HeyGen account and a working CLI or MCP connection.
- Who is it for?
- Adopt heygen-com/skills if you already run Claude Code, OpenClaw, Codex, Cursor or another agent that loads skills from a directory, and you have a HeyGen plan or are willing to pay for API usage, because the three skills chain through AVATAR-<NAME>.md files and the install is a single git clone or gh skill install.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 63 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: An Agent With No Body
A coding agent can write a script, edit a file and open a pull request, but it cannot appear in a video. If you want your agent to introduce itself, deliver a changelog as a talking head, or hand a stakeholder a share link instead of a wall of text, you are back to manual work: open a browser, upload a photo, type a script, wait for a render, copy the URL. The skills repository exists to collapse that loop into a prompt. The README's own example is an instruction to the agent: bring yourself to life, create your own avatar and make a 30-second intro video, using heygen-avatar and heygen-video, asking the user anything missing first. The target user is someone running a skill-capable agent (Claude Code, OpenClaw, Codex, Cursor and others are named) who wants video output as just another tool call. It is not a video editor, not a rendering library, and not something you embed in a product. It is glue between an agent's context and HeyGen's hosted pipeline.
Three Skills, One Markdown File Between Them
The repository ships three skills, each with its own SKILL.md: heygen-avatar, heygen-video, heygen-translate. The division of labour is stated plainly in the README: heygen-avatar creates the identity, heygen-video uses it, heygen-translate localizes finished videos. The mechanism that makes them composable is a file. heygen-avatar uploads a photo, creates what the README calls a persistent digital twin with a voice, and writes an AVATAR-<NAME>.md file. heygen-video reads that file later and reuses the avatar without re-uploading anything. The README describes these files as human-readable and machine-readable, which is the part worth noting: the integration contract is a markdown document in your workspace, not a database row or a session token. That means you can inspect it, diff it, keep it in a repo, or delete it to reset. It also means there is no schema enforcement, so if a future skill version changes the expected fields, the failure will show up as an agent misreading a file rather than a typed API error. The pipeline the README draws is linear: photo or description feeds heygen-avatar, which produces AVATAR-NAME.md, which feeds heygen-video, which produces the finished video. heygen-translate sits off to the side and takes an existing video rather than an avatar file.
Install: An Agent-Read Install Spec, or Four Manual Paths
The primary install method is deliberately unusual. You paste a prompt telling your agent to read INSTALL_FOR_AGENTS.md from the master branch and follow it, and to ask for any API keys it needs. The README says the agent then clones the repo to the right path, asks for the HeyGen API key, picks the best transport, runs a verify test, and ends with a working video. The rationale given is that the install spec lives in the repo rather than your clipboard, so the same prompt keeps working. That is a real advantage over copy-pasted setup instructions that go stale, and a real risk: you are handing an agent a remote document and asking it to execute what it says. Read INSTALL_FOR_AGENTS.md yourself first if the machine matters. The manual paths are four. Option A is gh skill install heygen-com/skills heygen-avatar (and the same for heygen-video and heygen-translate), which the README says requires GitHub CLI v2.90+ and writes to the correct directory for your agent automatically. Option B is clawhub install heygen-skills. Option C is openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen, which the README notes bundles MCP support. Option D is a git clone into a per-agent path: ~/.claude/skills/heygen-skills for Claude Code, ~/.openclaw/workspace/skills/heygen-skills for OpenClaw, anywhere your agent loads skills from otherwise. The clone command given is git clone --single-branch --depth 1 https://github.com/heygen-com/skills.git <install-path>/heygen-skills, and after cloning the three SKILL.md files are auto-discovered.
Auth: Two Modes With an Explicit Priority Order
This is the part most reviews would skip, and it is the part that determines what you pay. The skills support three auth situations in a documented priority. First, if HEYGEN_API_KEY is set, the skills use the CLI directly and do not probe for MCP. Second, if MCP tools are visible and no API key is set, they use the remote MCP server at https://mcp.heygen.com/mcp/v1/, which triggers an OAuth consent flow in your browser on first call. Third, a fallback to a CLI session created by heygen auth login, intended for interactive CLI users. The README is explicit about the billing split: CLI mode bills against your HeyGen API usage, separately metered, while MCP mode consumes your existing HeyGen plan credits with no extra API billing. That is the single most consequential configuration decision in the whole repository, and it is expressed as an environment variable. If you export HEYGEN_API_KEY for convenience and forget it, you have silently moved yourself onto metered API billing. For agent workflows the README recommends the API key path anyway, on the grounds that it is the most predictable setup. The CLI itself installs with curl -fsSL https://static.heygen.ai/cli/install.sh | bash, is described as a single static binary with no runtime deps, and follows a heygen <noun> <verb> pattern with JSON on stdout and stable exit codes. Verify with heygen --version and heygen auth status. Note that export HEYGEN_API_KEY=<your-key> is ephemeral and must be added to ~/.zshrc or ~/.bashrc to persist. For Claude Code MCP setup the command is claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/; for OpenClaw you add an mcp.servers.heygen entry with that URL to ~/.openclaw/openclaw.json.
What Breaks, and What the Skills Cannot Do
Every skill in this repository is a thin wrapper over a hosted service. There is no local model, no fallback renderer, and no offline mode described anywhere in the material. If HeyGen's API is unreachable, or your key is invalid, or your plan credits are exhausted, the agent has nothing to fall back on and the failure surfaces as a tool error mid-conversation. The README does not document rate limits, concurrency behaviour, or what happens when two agents share one API key. Treat those as unknown until you test them. There is also a cost shape that does not suit experimentation: avatar creation and video generation are billable operations, and the README does not publish per-operation pricing, so an agent that decides to retry a failed render three times is an agent that may bill you three times. The AVATAR-<NAME>.md file is a second soft spot. Because it is the only state channel, losing it means losing the reference to the avatar even though the avatar still exists in your HeyGen account; there is no documented command in the material for listing or recovering avatars. Finally, the identity model is one photo to one persistent twin. If your use case is many distinct speakers, or a synthetic presenter that must not resemble a real person, this is the wrong tool and the consent questions are yours to answer, not the repository's.
Compared With Calling the HeyGen API Directly
The obvious alternative is skipping the skills layer and calling the HeyGen API yourself, either through the CLI (github.com/heygen-com/heygen-cli) or through the MCP server. The difference is where the decisions live. Direct API or CLI use means you write the script, choose the avatar ID, pick the voice, handle the polling loop and store the resulting video URL, and your code owns every one of those steps. The skills layer moves those decisions into the agent's reasoning: the README says heygen-video goes from idea to script to a prompt-engineered video, and that heygen-avatar picks the best style and asks only for what is missing. That is the actual trade. You give up determinism and reproducibility, because a language model is choosing the script and the style, and you gain a workflow that survives vague instructions. If you need the same video produced identically on every run, the skills layer is the wrong abstraction and the CLI is the right one, since its JSON-on-stdout and stable exit codes are designed for scripts. If you want an agent to produce a reasonable video from a one-line request, the skills layer is doing work you would otherwise have to prompt-engineer yourself. A second alternative is a general video generation service with its own agent integration, but the material here gives no basis for comparing output quality, so the honest comparison is only about control and billing, not fidelity.
Maintenance, Licence and Upgrade Cost
The repository is MIT licensed, which covers the skill definitions and the markdown in this repo. It does not cover the HeyGen service, the CLI binary, the MCP server, or anything you generate with them; those are governed by HeyGen's own terms, and the MIT grant here says nothing about your rights to the output or about the consent of anyone whose likeness you upload. That is a question for HeyGen's terms, not this licence, and not something to infer from a permissive repo licence. On maintenance, the release history shows v3.0.0 and v3.1.0 both dated 2026-04-27, with v3.2.0 on 2026-05-18, and the last push to master on 2026-07-14. Two releases on the same day suggests a rapid major-version correction, and the v3 prefix in the repository description (the v3 Video Agent pipeline) means the skills track an upstream pipeline version rather than a stable interface. The practical upgrade cost is low if you installed by git clone, since you re-clone or pull; it is higher if you pinned a specific skill version through gh skill install or ClawHub, because you then need to re-run the install for each of the three skills. Because state lives in AVATAR-<NAME>.md files in your workspace rather than in the repo, upgrading the skills does not touch your avatars, which is the right design choice. Just check after an upgrade that heygen-video still parses the file format the previous version wrote.
Editorial conclusion
Adopt heygen-com/skills if you already run Claude Code, OpenClaw, Codex, Cursor or another agent that loads skills from a directory, and you have a HeyGen plan or are willing to pay for API usage, because the three skills chain through AVATAR-<NAME>.md files and the install is a single git clone or gh skill install. Do not adopt it if you need offline rendering, self-hosted inference, or a permissive path around HeyGen's billing, since every skill calls the hosted HeyGen API and the avatar lives in their account. Before writing it into a workflow, verify three things yourself: that heygen auth status returns a valid session or that MCP tools appear with no HEYGEN_API_KEY set, that the install path matches where your specific agent loads skills from, and which billing mode you are actually in, because the README states CLI mode is separately metered while MCP mode draws on plan credits.
Community notes