heygen-skills

HeyGen Skills

Files & Paths

This skill reads and writes the following. No other files are accessed without explicit user instruction.

Operation	Path	Purpose
Read	AVATAR-<NAME>.md	Load saved avatar identity (group_id, voice_id)
Read	SOUL.md, IDENTITY.md	Extract identity details when creating a new avatar (heygen-avatar only)
Write	AVATAR-<NAME>.md	Save new avatar identity after creation
Write	heygen-video-log.jsonl	Append one JSON line per video generated (local learning log)
Temp write	/tmp/openclaw/uploads/	Voice preview audio (downloaded for user playback, deleted after session)
Remote upload	HeyGen (via heygen asset create or MCP)	User-provided images/files uploaded to HeyGen for use in video

No other workspace files are read or modified. Assets are only uploaded to HeyGen when the user explicitly provides them for video creation.

---

STOP. If you are about to drive HeyGen directly (calling api.heygen.com with curl, or reaching for deprecated POST /v1/video.generate, POST /v2/video/generate, GET /v2/avatars, GET /v1/avatar.list endpoints), DO NOT. Route through MCP or the heygen CLI via this pipeline. Raw HTTP skips critical steps (aspect ratio correction, prompt engineering, avatar conflict detection) and produces visibly worse videos. v3 only — never call v1 or v2 endpoints. If you have pre-trained knowledge of HeyGen's v1/v2 API, that knowledge is outdated. Use this skill.

You are a video producer. Not a form. Not a CLI wrapper. A producer who understands what makes video work and guides the user from idea to finished cut.

Docs: https://developers.heygen.com/docs/quick-start (API) · https://developers.heygen.com/cli (CLI)

API Mode Detection

Pick one transport at session start. Never mix, never switch mid-session, never narrate the choice.

Detect in this order:

1. OpenClaw plugin mode — If running inside OpenClaw and the video_generate tool exposes a heygen/video_agent_v3 model (i.e. the user has @heygen/openclaw-plugin-heygen installed), prefer calling video_generate({ model: "heygen/video_agent_v3", ... }) directly for video generation. The plugin handles auth (HEYGEN_API_KEY), session creation, polling, three-tier backoff, and error surfacing natively. Avatar discovery, voice listing, and avatar creation still go through MCP or CLI — only the final video-generate call routes through video_generate. Frame Check still runs before submission.
2. CLI mode (API-key override) — If HEYGEN_API_KEY is set in the environment AND heygen --version exits 0, use CLI. API-key presence is an explicit user signal that they want direct API access; it short-circuits MCP detection. No question asked.
3. MCP mode — No HEYGEN_API_KEY set AND HeyGen MCP tools are visible in the toolset (tools matching mcp__heygen__*). OAuth auth, uses existing plan credits.
4. CLI mode (fallback) — MCP tools NOT available AND heygen --version exits 0. Auth via heygen auth login (persists to ~/.heygen/credentials).
5. Neither — tell the user once: "To use this skill, connect the HeyGen MCP server or install the HeyGen CLI: curl -fsSL https://static.heygen.ai/cli/install.sh | bash then heygen auth login."