HeyGen Avatar Videos . Agency OS

What it does

Creates avatar-led videos in HeyGen across four modes: a talking head of 60 seconds or more for explainers, training and VSLs; short cinematic clips of 5 to 15 seconds with body movement and camera work; a full production mixing dialogue scenes with cinematic hooks and closers; and B-roll only with no avatar. It delivers either a finished video and download link generated through the API, or a fully written prompt plus exact dashboard settings you paste in yourself. Every mode starts from an optimised prompt, because output quality tracks prompt quality almost entirely.

Say this to start

This skill has no button. You start it by saying what you want. Any of these will do it:

/create-video

> make a HeyGen video

> AI avatar video

> talking head video

> explainer video

> make a video with a talking photo

When to reach for it

an explainer or training video with a presenter
a social ad or reel that needs a talking head
a welcome or onboarding video for new clients
a short cinematic hook for the top of a video
personalised outreach video at volume
a video built from a talking photo

When NOT to use it

If you actually want	Use this instead
writing the spoken script when the ask is a sales video	`vsl-architect`
writing the persuasive copy itself	`legendary-copywriters`
a multi-shot shot list with effects timelines and density maps	`video-prompt-builder`
still image prompts or overall art direction	`creative-director`
editing raw camera or screen footage you already have	`auto-editor`
slicing an existing long video into clips and posts	`video-repurposer`

Before you start

What you need	Why
A HeyGen account at app.heygen.com	needed for every mode, including the one where you paste the prompt into the dashboard yourself	Required
A HeyGen API key set as the `HEYGEN_API_KEY` environment variable	required for the two API modes, generate-for-me and precise scene control. Without it you can still use the dashboard-prompt mode	Optional
HeyGen credits on the account	generation spends real credits. Cinematic clips run at 4 premium credits per second, so a 15 second clip is 60	Required
A check of `protocol/current-tool-stack.md`	if the workspace names a different avatar-video tool as the tool of record, the request should be routed there instead. The tool-stack file wins that decision	Required
Your topic or script, plus who the video is for	the skill needs the video type, duration and audience before it can write an optimised prompt	Required
Workspace brand files: owner profile, voice profile, ICA and verified claims	they set the styling, the script tone, the audience angle, and the grounding for anything claimed on screen or out loud	Optional
HeyGen MCP tools configured	preferred over raw HTTP calls when present. Without them the skill falls back to direct API calls with your key	Optional

Installing what it needs

No toolchain to install. This skill needs one thing: your own HeyGen API key, for the modes that generate through the API.

Set your HeyGen key

From your HeyGen account settings. Without it the skill still produces the script and the prompt for you to run manually, so it degrades rather than blocks.

echo 'export HEYGEN_API_KEY=your_key_here' >> ~/.zshrc && source ~/.zshrc

Check it worked

Should print your key. If it prints nothing, open a new terminal.

echo $HEYGEN_API_KEY

How it runs

Routing checkIt reads the workspace tool-stack file first. If a different avatar-video tool is on record, it says so in one line and routes you there rather than running. The craft below transfers either way.
It asks what kind of videoTalking head at 60 seconds or more, a cinematic clip of 5 to 15 seconds, a full production mixing both, or B-roll only with no avatar. That answer decides which references load and which generation path is used.
It asks how you want it deliveredGenerate it through the API and hand you a download link; write you a prompt to paste into the HeyGen dashboard; or take precise scene-by-scene control with exact avatar, voice and background per scene.
It writes an optimised promptEvery mode goes through prompt optimisation before anything is sent. The prompt sets format, duration, orientation, tone, avatar, then scene by scene: which are avatar scenes, which are B-roll, what the voiceover says, and the music treatment.
Generation or handoverOn the API path it submits the job and polls until the video is ready, then gives you the download URL. On the dashboard path it hands you a copyable prompt block plus the exact settings to use: duration, orientation, which avatar, style preset and whether to plan first or generate immediately.
Cinematic clips, if the video needs themShort clips use their own prompt anatomy: subject, action, setting, one camera movement, style, mood, duration, always closing with smooth motion and stable framing. Constraints are hard: 15 seconds maximum per generation, one camera movement, positive phrasing only, up to three reference images and no human faces among them.
Full productions get splitDialogue scenes are generated with the talking-head mode and hooks and closers with the cinematic mode, and it tells you the split before generating so you know what you are paying for.
Fallback and loggingIf the API errors or the video sits pending past ten minutes, it offers to switch you to the dashboard path and hands over the optimised prompt. Finished videos are logged to your workspace assets file with the date.

What you get

A finished avatar video plus a download URL when generated through the API
A copy-paste prompt block plus the exact dashboard settings to use, when you generate manually
Per-scene configuration when you need exact script, voice, background and avatar control, including transparent output for compositing
Cinematic clip prompts of 5 to 15 seconds written to the shot and camera vocabulary the model responds to
An entry appended to brand/[workspace]/assets.md recording the generated video

Honest limits

Read this before you rely on it

This one costs money on every run. Cinematic clips are 4 premium credits per second, and a queued or failed job still consumes your time.
Talking photo avatars cannot be passed through the API. If you want a talking photo, you use the dashboard-prompt mode, which means generating it yourself.
Cinematic clips are capped at 15 seconds per generation. Anything longer is multiple generations edited together.
API generation is not guaranteed. If the job errors or stays pending past ten minutes, the fallback is to hand you the prompt for the dashboard.
It does not write your sales script or your persuasive copy. It writes the prompt and produces the video around a script you bring or a topic it scripts loosely from.
If your workspace tool-stack file names a different avatar tool, this skill is not the right route and will say so.

Where people go wrong

The mistake	Do this instead
Passing a talking photo ID as the avatar ID in an API call	The API does not accept them. Switch to the dashboard-prompt mode and select the talking photo there.
Sending a rough one-line prompt and judging the tool by the result	Never send an unoptimised prompt. Quality depends almost entirely on prompt quality, which is why the skill optimises before every generation in every mode.
Writing cinematic clip prompts with negations, such as 'no shaky camera'	Positive prompting only. Describe what you want, and close with smooth motion and stable framing.
Stacking camera movements to make a clip feel dynamic	One camera movement per shot, never stacked. Dynamism comes from the subject's action and the shot choice.
Trying to script one long production as a single generation	Split it. Dialogue scenes on the talking-head path, hooks and closers on the cinematic path, then edit together.

Worth knowing

When you need a multi-shot video rather than a single scene, run video-prompt-builder first. It produces the structured shot list with effects breakdown and paste-ready blocks that feed directly into this skill's cinematic clip mode, so you are not inventing camera language shot by shot inside the generation step.