heygen-com/skills: avatar video skills for Claude Code and other AI agents

What heygen-com/skills actually solves for an AI agent

Most agent tooling gives a model text and file access. It cannot appear on camera. This repository is a thin, opinionated bridge between an agent's existing identity files and HeyGen's video API, so the agent can produce a talking-head video of itself and hand back a share link.

The README frames the goal directly: "Your agent gets a face, a voice, and the ability to send video like a message." The example prompt in the README has the user tell the agent to bring itself to life, create its own avatar, and make a 30-second intro video using heygen-avatar and heygen-video, asking questions before starting. The agent is expected to read its own identity files first, then ask only for what is missing.

The audience is narrower than the topic list suggests. This is for people running Claude Code, OpenClaw, Codex, Cursor or a comparable coding agent who also have a HeyGen account or key. If you do not, nothing here works, because every skill terminates in a HeyGen API call. It is not a general video editing toolkit and it is not a local model.

Three skills, one Markdown file as the handoff

The repository ships three skills, each with its own SKILL.md: heygen-avatar, heygen-video and heygen-translate. They are designed to work standalone or chained.

The data flow is the interesting part. heygen-avatar takes a photo or description and produces a persistent digital twin with a face and a voice. heygen-video takes an idea, writes a script, and generates a video with that avatar delivering the message. heygen-translate takes an existing video and returns a dubbed version with voice cloning and lip-sync across 175+ languages, per the README.

What holds the chain together is a file, not a database. heygen-avatar writes AVATAR-<NAME>.md; heygen-video reads it. The README describes these as "human-readable and machine-readable," and that is the right design call for an agent skill: state that a model can read, a human can edit, and git can diff. It also means the avatar reference is portable across sessions without any server-side session management on the skill side.

heygen-avatar creates the identity, heygen-video consumes it, heygen-translate localizes finished output. Each skill is invoked as a slash command such as /heygen-avatar or /heygen-video in agents that support that syntax.

Installing heygen-com/skills: the agent-driven path and the manual path

The README's preferred install is to paste a single prompt into your agent, which fetches INSTALL_FOR_AGENTS.md and follows it. The prompt tells the agent to read the file and ask for any API keys it needs, and the README states the agent 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 install spec lives in the repository, so the same prompt keeps working.

If you would rather do it by hand, install the skills first. The cross-agent option uses the GitHub CLI and requires v2.90 or later:

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

The README says the CLI writes to the correct directory for your agent automatically. The legacy alternative is a shallow clone into a path your agent loads skills from, for example ~/.claude/skills/heygen-skills for Claude Code or ~/.openclaw/workspace/skills/heygen-skills for OpenClaw. After cloning, the README states the three skills are auto-discovered at heygen-avatar/SKILL.md, heygen-video/SKILL.md and heygen-translate/SKILL.md. ClawHub and an OpenClaw plugin are also listed as install options.

Next, get a key from app.heygen.com/api and install the HeyGen CLI, which the README describes as a single static binary with no runtime dependencies:

curl -fsSL https://static.heygen.ai/cli/install.sh | bash
export HEYGEN_API_KEY=<your-key>
heygen --version
heygen auth status

The export only affects the current shell; the README says to add it to ~/.zshrc, ~/.bashrc or the equivalent to persist it. If heygen --version prints a version and heygen auth status reports a valid session, the CLI half is done.

For your first real use, hand the avatar skill a photo and then ask for a video. The README's example is a 30 to 60 second self-introduction in a casual tone. The skill picks up the avatar automatically, writes a script, generates the video and returns a share link. The avatar persists, so later videos reuse it without re-uploading the photo.

The auth fork is a billing decision, not a convenience setting

This is the part of the README worth reading twice. There are two auth modes with an explicit priority order, and the choice changes how you are charged.

Priority one is the CLI with an API key. If HEYGEN_API_KEY is set, the skills use the CLI directly and skip MCP probing entirely. The README calls this the most predictable setup for agent workflows and recommends it for agents, CI and scripts. Billing is against HeyGen API usage, separately metered.

Priority two is MCP over OAuth. It applies when MCP tools are visible and no API key is set. Billing consumes your existing HeyGen plan credits with no extra API billing. The README positions it for users on a HeyGen plan. Connecting it is one command for Claude Code:

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

For OpenClaw, the README shows a JSON block in ~/.openclaw/openclaw.json with an mcp.servers.heygen.url entry pointing at the same endpoint. The first call triggers an OAuth consent flow in the browser.

Priority three is a CLI fallback using a heygen auth login session, for interactive CLI users, again billed as direct API usage.

The README states the rule plainly: set the key only if you want direct API access, otherwise use MCP. That is a clean instruction and an easy one to get wrong, because exporting HEYGEN_API_KEY for an unrelated reason silently flips a plan-credit workflow onto metered API billing. The skills do not ask which you prefer; the environment variable decides.

Where heygen-com/skills is the wrong tool

The dependency on HeyGen is total. There is no local rendering path, no fallback provider, and no offline mode. If your HeyGen account is out of credits, or your key is revoked, the skills have nothing to call. A team evaluating this as a general agent-video layer should treat it as a client library for one vendor.

Failure handling is the second gap. The README describes the CLI as producing JSON on stdout with stable exit codes, which is genuinely useful for scripting, but it does not document what the skills do when a video render fails, how long a render is expected to take, whether a partially completed job is retried, or how to resume one. The README does not document rollback either. For an interactive session where you watch the agent work, that is tolerable. For an unattended pipeline, it is an unknown you would have to discover yourself.

There is also a versioning caveat. The skills are distributed as files in a repository, and the README's manual paths clone them into agent-specific directories. A shallow clone at a fixed path is not a package manager; keeping three agent installs in sync across a team is manual work unless you standardize on gh skill install or the plugin route.

Finally, the repository is Shell-first, and its top level mixes plugin manifests for several agents (.claude-plugin/, .codex-plugin/, .cursor-plugin/, .mcp.json, mcp.json, a platforms/ directory). That breadth is the point, but it also means the surface you actually exercise depends heavily on which agent you run, and the README's step-by-step detail is deepest for Claude Code and OpenClaw.

Alternatives: HeyGen's own API versus a general agent skill

The closest alternative is not a competing skill repository. It is calling the HeyGen API or CLI directly from your own agent instructions. The difference in approach is who holds the workflow knowledge. With this repository, the script-writing step, avatar lookup, style selection and share-link delivery live in the skill files, and the agent reads them. With a direct integration, you write that orchestration yourself and keep full control over retries, logging and cost accounting, at the price of reimplementing the parts the skills already encode.

The second alternative is a generic video production tool that renders locally or through a different vendor. That removes the HeyGen account requirement entirely, and it also removes the avatar persistence model that makes this repository convenient: an AVATAR-<NAME>.md file that any later session can pick up. If your requirement is a consistent on-camera persona across many short videos, the file-based handoff here is the thing you would otherwise have to build.

A third comparison is MCP alone, without the skills. Connecting the remote MCP server gives an agent HeyGen tools, but not the opinionated sequence of reading identity files, asking only for missing details, building the avatar, choosing a style and delivering a link. The skills are the procedure; MCP is the transport. The README's auth table makes that separation explicit, since the skills auto-detect MCP when no key is set.

Maintenance, upgrades and the MIT licence

The repository is not archived. The last push was on 2026-07-14. Releases are tagged and include v3.2.0 on 2026-05-18, v3.1.0 and v3.0.0 both on 2026-04-27, and the top level contains .release-please-manifest.json and release-please-config.json, so versioning is automated through release-please rather than hand-tagged. A CHANGELOG.md and a VERSION file sit alongside them.

Upgrade cost depends on your install path. If you used gh skill install, refreshing the three skills is the same command you ran the first time, and the README notes the CLI writes to the right directory automatically. If you cloned manually, you re-pull the clone into the agent's skill directory, and you have to remember which of the four documented paths you used. The agent-driven install is the one with the least drift, because the install spec lives in the repository and the prompt does not change between versions.

The licence is MIT. That permits commercial use, modification and redistribution, and it requires the licence and copyright notice to be preserved. It provides no warranty. This is a note about what the licence identifier means, not legal advice; if you are embedding the skills in a product, have your own counsel read the LICENSE file. One practical point: the skills call HeyGen's hosted service, so the MIT licence covers the skill files, not the video service they depend on, which is governed by your HeyGen account terms.

Editorial conclusion

Adopt it if you already have a HeyGen account or API key and you want an agent to produce avatar videos without leaving the terminal; the three skills install with gh skill install heygen-com/skills heygen-avatar (and the two sibling skills), and the avatar file they write is plain Markdown you can inspect. Do not adopt it if you have no HeyGen plan or key, because every path ends at HeyGen's API, or if you need a headless pipeline with documented retry semantics, since the README does not describe what a skill does when a render fails. Before you commit, verify three things: which auth mode your agent actually picks (HEYGEN_API_KEY present means CLI and separate API billing, absent means MCP and plan credits), that your agent's skill directory matches the install path table, and that heygen auth status returns a valid session after you export the key.

Frequently asked questions

Official sources

1. heygen-com/skills on GitHub
2. License: MIT
3. Project website
4. README
5. Releases