HeyGen Expert
Act as the dispatcher for the whole HeyGen skill family installed on this machine. Never
reimplement what a leaf skill or the CLI already does — pick the right one, hand off with the
right inputs, and stop. This skill carries no video-generation logic of its own.
Two engines, one vendor
HeyGen ships two independent capability sets. Tell them apart before routing:
- HeyGen API skills (
heygen-avatar, heygen-video, heygen-translate) — thin wrappers
over the hosted HeyGen API. Fast, single-clip, presenter-led. Output is a rendered MP4 / share
URL from HeyGen's servers. Backed by the heygen CLI (~/.local/bin/heygen, repo
heygen-com/skills).
- HyperFrames (
hyperframes + ~19 companion skills) — an HTML-based, locally-rendered video
composition framework (DOM timing via data-*, seekable GSAP/Lottie/Three.js runtimes,
multi-scene, captions, keyframes, Figma import, Remotion ports). Repo heygen-com/hyperframes,
backed by the hyperframes / npx hyperframes CLI (see hyperframes-cli).
They compose: a HeyGen-rendered talking-head clip is a valid input asset into a HyperFrames
composition (title cards, lower-thirds, captions, keyframed camera moves wrapped around it). Route
identity/clip generation to the API skills first, then hand the resulting file to HyperFrames for
anything compositional.
Routing table
Match the requested deliverable, first row wins.
| Request |
Route |
| No avatar identity exists yet, and one is needed (agent, user, or a named character) |
heygen-avatar first — always before heygen-video if identity isn't established |
| "Make a HeyGen video / talking head / send a video message" with an avatar_id already known or a stock presenter is fine |
heygen-video (v3 Video Agent pipeline) |
| Localize / dub / subtitle an existing video into another language, same presenter |
heygen-translate |
| Create identity AND generate a video in the same request ("create an avatar called X and make a video") |
heygen-avatar → then heygen-video, in that order |
| Anything HyperFrames-shaped: promo, explainer, motion graphic, title card, captioned clip, slideshow/deck, overlay, Remotion port, music video, PR-to-video, changelog video, talking-head recut with graphics, Figma import |
hyperframes (the gateway skill) — do not pre-pick its sub-skill; hyperframes owns intent capture, project-state resume, and routing to hyperframes-core / hyperframes-animation / hyperframes-creative / hyperframes-keyframes / hyperframes-registry / media-use / the workflow skills (faceless-explainer, general-video, motion-graphics, music-to-video, pr-to-video, product-launch-video, remotion-to-hyperframes, slideshow, talking-head-recut, embedded-captions, changelog-video, figma) and the doctrine skills (motion-doctrine, cut-the-curve, captions-overlay, oversized-cursor, seam-craft) |
| A HeyGen clip needs to become part of a bigger composition (title card intro, captions, lower-thirds, camera moves around a talking head) |
Generate the clip via heygen-video/heygen-translate first, then hand the output file to hyperframes (media-use ingests it as a footage asset; talking-head-recut or general-video wrap it) |
| Only raw API calls needed — batch jobs, scripting, CI, status polling, asset/voice/brand management, webhooks |
heygen CLI directly, no skill needed |
| Only HyperFrames CLI operations needed — init, render, preview, publish, doctor, batch-render on an existing project |
hyperframes-cli / npx hyperframes <cmd> directly, skip the gateway's intent interview (its own state table already does this — see "Specific operation on an existing HyperFrames project") |
| Ambiguous ("make a video") |
Ask one routing question: presenter-led single clip (→ HeyGen API) or a fuller composition with graphics/captions/multi-scene (→ HyperFrames)? Default to hyperframes if the user mentions motion graphics, captions, multi-scene, or a URL/PR/Figma input — those are HyperFrames-shaped by definition |
heygen CLI cheat sheet
Binary: ~/.local/bin/heygen. JSON output by default; --human for tables;
--request-schema on any subcommand shows expected JSON input.
heygen auth login --api-key|--oauth|--device # non-interactive shells auto-pick --api-key
heygen avatar create|list|get|update|delete | looks list|get|update|delete | consent create
heygen video create|list|get|delete
heygen video-agent create|list|get|send|stop|resources get|styles list|videos list
heygen video-translate create|list|get|update|delete | batches create|get | languages list
| proofreads create|generate|get|srt get|srt update | statuses list
heygen lipsync ... heygen voice ... heygen asset ...
heygen ai-clipping ... heygen filler-word-removal ... heygen background-removal ...
heygen brand ... heygen template ... heygen webhook ...
heygen user ... heygen config list heygen update
Env: HEYGEN_API_KEY (overrides stored credentials), HEYGEN_OUTPUT=json|human. Exit codes:
0 success, 1 API/network error, 2 usage error, 3 auth error, 4 timeout (resource
created, not yet complete — poll, don't retry the create).
HyperFrames CLI cheat sheet
Invoke via npx hyperframes <cmd> (project pins its own version in package.json; hyperframes-cli
covers the full loop). Core commands: init, add, catalog, capture, lint, check,
snapshot, compare, grade-compare, preview, play, present, beats, keyframes,
render (single/batch), publish, cloud, cloudrun, feedback, lambda, doctor, browser,
info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth,
tts, remove-background. validate/inspect/layout are deprecated aliases for check.
Rendering targets: local, HeyGen-hosted cloud, AWS Lambda, Google Cloud Run.
Anti-patterns
- Don't call
heygen-video before heygen-avatar when no identity exists — it will use a stock
presenter when the user asked for a specific/recurring identity.
- Don't hand-author HyperFrames HTML/JS here — always defer to the
hyperframes gateway so intent
capture, project resume, and sub-skill routing stay centralized and don't drift from its own
state table.
- Don't use
heygen-translate to create a video that doesn't exist yet — that's heygen-video
with a target-language script.
- Don't skip
hyperframes's CLI-pin check on resumed projects (npx hyperframes@latest upgrade --project . --check) — stale pins silently change render behavior.
- API key management goes through
heygen auth, never hardcoded or echoed into logs.
1---2name: heygen-expert3description: Canonical HeyGen orchestrator. Routes any request touching HeyGen — AI avatars, presenter videos, video translation/dubbing, lipsync, or HyperFrames HTML-based video composition (motion graphics, captions, slideshows, Remotion ports, faceless explainers, product launch videos, PR-to-video, music-to-video, talking-head recuts) — to the correct skill and CLI (`heygen`, `npx hyperframes`) instead of guessing or reimplementing what those skills already do. Use when the user says "create an avatar", "make a HeyGen video", "translate/dub this video", "lipsync", "clone my voice into another language", "generate a talking head video", "make a promo/explainer/motion graphic", "hyperframes", "render a composition", or names any heygen-* / hyperframes-* skill directly. Decides HeyGen API vs HyperFrames vs CLI-only, and how to bridge a HeyGen-generated clip into a HyperFrames composition.4---56# HeyGen Expert78Act as the dispatcher for the whole HeyGen skill family installed on this machine. Never9reimplement what a leaf skill or the CLI already does — pick the right one, hand off with the10right inputs, and stop. This skill carries no video-generation logic of its own.1112## Two engines, one vendor1314HeyGen ships two independent capability sets. Tell them apart before routing:15161. **HeyGen API skills** (`heygen-avatar`, `heygen-video`, `heygen-translate`) — thin wrappers17 over the hosted HeyGen API. Fast, single-clip, presenter-led. Output is a rendered MP4 / share18 URL from HeyGen's servers. Backed by the `heygen` CLI (`~/.local/bin/heygen`, repo19 `heygen-com/skills`).202. **HyperFrames** (`hyperframes` + ~19 companion skills) — an HTML-based, locally-rendered video21 composition framework (DOM timing via `data-*`, seekable GSAP/Lottie/Three.js runtimes,22 multi-scene, captions, keyframes, Figma import, Remotion ports). Repo `heygen-com/hyperframes`,23 backed by the `hyperframes` / `npx hyperframes` CLI (see `hyperframes-cli`).2425They compose: a HeyGen-rendered talking-head clip is a valid **input asset** into a HyperFrames26composition (title cards, lower-thirds, captions, keyframed camera moves wrapped around it). Route27identity/clip generation to the API skills first, then hand the resulting file to HyperFrames for28anything compositional.2930## Routing table3132Match the requested deliverable, first row wins.3334| Request | Route |35|---|---|36| No avatar identity exists yet, and one is needed (agent, user, or a named character) | `heygen-avatar` first — always before `heygen-video` if identity isn't established |37| "Make a HeyGen video / talking head / send a video message" with an avatar_id already known or a stock presenter is fine | `heygen-video` (v3 Video Agent pipeline) |38| Localize / dub / subtitle an **existing** video into another language, same presenter | `heygen-translate` |39| Create identity AND generate a video in the same request ("create an avatar called X and make a video") | `heygen-avatar` → then `heygen-video`, in that order |40| Anything HyperFrames-shaped: promo, explainer, motion graphic, title card, captioned clip, slideshow/deck, overlay, Remotion port, music video, PR-to-video, changelog video, talking-head recut with graphics, Figma import | `hyperframes` (the gateway skill) — do not pre-pick its sub-skill; `hyperframes` owns intent capture, project-state resume, and routing to `hyperframes-core` / `hyperframes-animation` / `hyperframes-creative` / `hyperframes-keyframes` / `hyperframes-registry` / `media-use` / the workflow skills (`faceless-explainer`, `general-video`, `motion-graphics`, `music-to-video`, `pr-to-video`, `product-launch-video`, `remotion-to-hyperframes`, `slideshow`, `talking-head-recut`, `embedded-captions`, `changelog-video`, `figma`) and the doctrine skills (`motion-doctrine`, `cut-the-curve`, `captions-overlay`, `oversized-cursor`, `seam-craft`) |41| A HeyGen clip needs to become part of a bigger composition (title card intro, captions, lower-thirds, camera moves around a talking head) | Generate the clip via `heygen-video`/`heygen-translate` first, then hand the output file to `hyperframes` (`media-use` ingests it as a footage asset; `talking-head-recut` or `general-video` wrap it) |42| Only raw API calls needed — batch jobs, scripting, CI, status polling, asset/voice/brand management, webhooks | `heygen` CLI directly, no skill needed |43| Only HyperFrames CLI operations needed — init, render, preview, publish, doctor, batch-render on an existing project | `hyperframes-cli` / `npx hyperframes <cmd>` directly, skip the gateway's intent interview (its own state table already does this — see "Specific operation on an existing HyperFrames project") |44| Ambiguous ("make a video") | Ask one routing question: presenter-led single clip (→ HeyGen API) or a fuller composition with graphics/captions/multi-scene (→ HyperFrames)? Default to `hyperframes` if the user mentions motion graphics, captions, multi-scene, or a URL/PR/Figma input — those are HyperFrames-shaped by definition |4546## `heygen` CLI cheat sheet4748Binary: `~/.local/bin/heygen`. JSON output by default; `--human` for tables;49`--request-schema` on any subcommand shows expected JSON input.5051```52heygen auth login --api-key|--oauth|--device # non-interactive shells auto-pick --api-key53heygen avatar create|list|get|update|delete | looks list|get|update|delete | consent create54heygen video create|list|get|delete55heygen video-agent create|list|get|send|stop|resources get|styles list|videos list56heygen video-translate create|list|get|update|delete | batches create|get | languages list57 | proofreads create|generate|get|srt get|srt update | statuses list58heygen lipsync ... heygen voice ... heygen asset ...59heygen ai-clipping ... heygen filler-word-removal ... heygen background-removal ...60heygen brand ... heygen template ... heygen webhook ...61heygen user ... heygen config list heygen update62```6364Env: `HEYGEN_API_KEY` (overrides stored credentials), `HEYGEN_OUTPUT=json|human`. Exit codes:65`0` success, `1` API/network error, `2` usage error, `3` auth error, `4` timeout (resource66created, not yet complete — poll, don't retry the create).6768## HyperFrames CLI cheat sheet6970Invoke via `npx hyperframes <cmd>` (project pins its own version in `package.json`; `hyperframes-cli`71covers the full loop). Core commands: `init`, `add`, `catalog`, `capture`, `lint`, `check`,72`snapshot`, `compare`, `grade-compare`, `preview`, `play`, `present`, `beats`, `keyframes`,73`render` (single/batch), `publish`, `cloud`, `cloudrun`, `feedback`, `lambda`, `doctor`, `browser`,74`info`, `upgrade`, `skills`, `compositions`, `docs`, `benchmark`, `telemetry`, `transcribe`, `auth`,75`tts`, `remove-background`. `validate`/`inspect`/`layout` are deprecated aliases for `check`.76Rendering targets: local, HeyGen-hosted cloud, AWS Lambda, Google Cloud Run.7778## Anti-patterns7980- Don't call `heygen-video` before `heygen-avatar` when no identity exists — it will use a stock81 presenter when the user asked for a specific/recurring identity.82- Don't hand-author HyperFrames HTML/JS here — always defer to the `hyperframes` gateway so intent83 capture, project resume, and sub-skill routing stay centralized and don't drift from its own84 state table.85- Don't use `heygen-translate` to create a video that doesn't exist yet — that's `heygen-video`86 with a target-language script.87- Don't skip `hyperframes`'s CLI-pin check on resumed projects (`npx hyperframes@latest upgrade88 --project . --check`) — stale pins silently change render behavior.89- API key management goes through `heygen auth`, never hardcoded or echoed into logs.
Andersonlimahw