| name | video.from-script |
| description | Render approved avatar + voice + script briefs into HeyGen MP4 videos with async job polling. |
| user-invocable | true |
| requires | {"bins":["node"]} |
| credentials | [{"id":"heygen-api-key","kind":"api_key","required":true,"secret_ref":{"source":"store","id":"HEYGEN_API_KEY"},"scope":"HeyGen Direct API avatar video generation.","how_to_obtain":"Create or regenerate the API token from HeyGen account settings. Set `HEYGEN_API_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HEYGEN_API_KEY \"<api-key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HEYGEN_API_KEY \"<api-key>\"`."}] |
| metadata | {"hybridclaw":{"category":"media","short_description":"Async HeyGen avatar videos from script text.","tags":["video","avatar-video","heygen","from-script","mp4"],"related_roadmap":["R55","R55.2"],"issue":875,"depends_on":["R55.1","heygen"],"stakes_tiers":{"green":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"escalation":{"writes":"confirm-each","route":"f8"},"cost_measurement":{"system":"UsageTotals","sub_limit_contract":"R5.4","sub_limit_key":"heygen"}}} |
Video From Script
Use this skill when the user wants an avatar video from three concrete inputs:
an avatar or image source, a voice id, and approved script text. The backing
provider is HeyGen Direct API via the bundled heygen adapter.
Scope
- plan avatar video generation from script text
- start a HeyGen video generation job and return the job id immediately
- poll job status until it is
completed, failed, or still rendering
- download the completed MP4 into
.generated-videos
- keep HeyGen API keys behind gateway secret injection
Template videos, free-form prompt-to-video, public publishing, social posting,
and custom avatar training are outside this skill. Use video-generation for
native Sora/Veo prompt videos and heygen for lower-level HeyGen API work.
Polling is the completion transport implemented for R55.2; webhook callbacks
belong in a provider/gateway adapter if that transport is added later.
Default Workflow
- Confirm the user has provided an avatar source, voice id, and final script.
- Run public-facing marketing, sales, training, or onboarding copy through
/brand-voice before starting a credit-consuming render.
- Use
plan if the request is vague or needs an explicit risk summary.
- Use
start after the operator grants the exact credit-consuming render.
Return the jobId to the user because HeyGen renders asynchronously.
- Use
status --job-id <id> to poll conservatively. Add --download only
after the status is complete or when the user asks you to fetch the MP4.
- Use
render --wait only when the user explicitly wants the agent to wait
for the final MP4 in the same run.
Do not run parallel render bursts. HeyGen quotas are tight and account/plan
dependent.
Command Contract
Run the helper with Node:
node skills/video.from-script/video-from-script.cjs --help
In packaged agent workspaces this skill can be mounted with a hyphenated
directory name. If the command above fails with Cannot find module, run:
node skills/video-from-script/video-from-script.cjs --help
Plan without contacting HeyGen:
