docs: add SKILL.md for agent discovery

Progressive disclosure file for AI agents. Frontmatter (name +
description) is ~100 tokens — loaded at startup for skill scanning.
Full instructions (~800 tokens) loaded only when the skill is invoked.

Covers: auth, key commands, async patterns, request bodies, output
contract, exit codes, and practical notes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: somanshreddy

SKILL.md

@@ -0,0 +1,86 @@
+---
+name: heygen-cli
+description: "Create AI videos, manage avatars, translate videos, and download results via the HeyGen API. Use when an agent needs to generate videos from text prompts, create avatar-based videos, translate existing videos, or automate video production workflows."
+---
+
+# HeyGen CLI
+
+Official CLI for the HeyGen video generation API. 30+ commands auto-generated from the OpenAPI spec. All output is JSON by default.
+
+- **API Docs**: https://developers.heygen.com
+- **Install**: `curl -fsSL https://heygen-cli.heygen.com/install.sh | bash`
+- **Auth**: Requires `HEYGEN_API_KEY` environment variable. The key must be provisioned by a user from https://app.heygen.com/settings/api
+
+## Key Commands
+
+```bash
+# Create video from prompt (simplest path — blocks until done)
+heygen video-agent create --prompt "Make a 30-second product demo" --wait
+
+# Create avatar video with full control
+heygen video create -d '{"video_inputs":[{"character":{"type":"avatar","avatar_id":"josh_lite"},"voice":{"type":"text","voice_id":"en_male","input_text":"Hello world"}}]}'
+
+# Check video status
+heygen video get <video-id>
+
+# Download completed video
+heygen video download <video-id>
+
+# List resources
+heygen video list --limit 5
+heygen video list --all
+heygen avatar list --limit 10
+heygen voice list
+
+# Translate a video
+heygen video-translate create -d '{"video":{"type":"url","url":"https://..."},"output_languages":["es"]}'
+```
+
+## Async Operations
+
+Video creation is asynchronous. Two patterns:
+
+**Block until done (recommended):**
+```bash
+heygen video-agent create --prompt "Demo video" --wait --timeout 5m
+# stdout: final resource JSON with video_url when complete
+```
+
+**Manual polling:**
+```bash
+heygen video create -d '{"...}'       # stdout: JSON with video_id
+heygen video get <video-id>           # stdout: JSON with status field
+heygen video download <video-id>      # downloads file, stdout: JSON with path
+```
+
+## Request Bodies
+
+Create/update commands accept JSON via `-d`/`--data`:
+- Inline: `-d '{"key": "value"}'`
+- From file: `-d request.json`
+- From stdin: `echo '{"...}' | heygen video create -d -`
+
+Flags override matching fields in the JSON when both are provided.
+
+## Output Contract
+
+- **stdout**: JSON (always). Parseable by `jq`. This is the only output agents should consume.
+- **stderr**: JSON error envelope on failure: `{"error":{"code":"...","message":"...","hint":"..."}}`
+- **Pagination**: `--all` fetches all pages into a flat JSON array.
+- Do not pass `--human`. It produces unstructured text that cannot be parsed.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error (API error, network failure) |
+| 2 | Usage error (invalid flags, missing arguments) |
+| 3 | Authentication error |
+
+## Notes
+
+- `--wait` handles polling with exponential backoff (2s to 30s). Default timeout is 10 minutes.
+- The CLI retries transient errors (429, 5xx) automatically.
+- Video download writes to `{video-id}.mp4` by default. Override with `--output-path`.
+- For the full API reference (concepts, limits, pricing), see https://developers.heygen.com