feat: add heygen-translate skill (video translation / dubbing)

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "heygen",
       "source": "./",
-      "description": "HeyGen skills for avatar creation, identity-first video, and personalized video messages. Invoke as /heygen:avatar or /heygen:video.",
+      "description": "HeyGen skills for avatar creation, identity-first video generation, personalized video messages, and video translation / dubbing. Invoke as /heygen:avatar, /heygen:video, or /heygen:translate.",
       "version": "1.3.2",
       "skills": [
         {
@@ -20,6 +20,11 @@
           "name": "video",
           "path": "heygen-video",
           "invoke": "/heygen:video"
+        },
+        {
+          "name": "translate",
+          "path": "heygen-translate",
+          "invoke": "/heygen:translate"
         }
       ]
     }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "heygen",
   "version": "1.3.2",
-  "description": "Create HeyGen avatar videos and personalized video messages. Build a persistent digital identity from a photo, then generate presenter-led videos with your digital twin.",
+  "description": "Create HeyGen avatar videos, personalized video messages, and translated / dubbed videos. Build a persistent digital identity from a photo, generate presenter-led videos with your digital twin, and localize existing videos into 175+ languages with voice cloning and lip-sync.",
   "author": {
     "name": "HeyGen",
     "url": "https://heygen.com"
@@ -18,6 +18,11 @@
     "presenter",
     "talking-head",
     "ai-avatar",
-    "avatar-video"
+    "avatar-video",
+    "translate",
+    "dub",
+    "localization",
+    "voice-cloning",
+    "lip-sync"
   ]
 }

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "heygen",
   "version": "1.3.2",
-  "description": "Create HeyGen avatar videos and personalized video messages. Build a persistent digital identity from a photo, then generate presenter-led videos with your digital twin.",
+  "description": "Create HeyGen avatar videos, personalized video messages, and translated / dubbed videos. Build a persistent digital identity from a photo, generate presenter-led videos with your digital twin, and localize existing videos into 175+ languages with voice cloning and lip-sync.",
   "author": {
     "name": "HeyGen",
     "email": "[email protected]",
@@ -20,22 +20,28 @@
     "presenter",
     "talking-head",
     "ai-avatar",
-    "avatar-video"
+    "avatar-video",
+    "translate",
+    "dub",
+    "localization",
+    "voice-cloning",
+    "lip-sync"
   ],
   "skills": "./",
   "apps": "./.app.json",
   "interface": {
     "displayName": "HeyGen",
-    "shortDescription": "Avatar videos and personalized video messages",
-    "longDescription": "HeyGen Skills give your agent a face, a voice, and the ability to send video like a message. Use heygen-avatar to build a persistent digital identity from a photo and pick a voice, then heygen-video to generate identity-first presenter videos via the HeyGen v3 Video Agent pipeline (avatar resolution, aspect ratio correction, prompt engineering, and voice selection are handled automatically).",
+    "shortDescription": "Avatar videos, personalized messages, and video translation",
+    "longDescription": "HeyGen Skills give your agent a face, a voice, and the ability to send video like a message — in any language. Use heygen-avatar to build a persistent digital identity from a photo and pick a voice, heygen-video to generate identity-first presenter videos via the HeyGen v3 Video Agent pipeline (avatar resolution, aspect ratio correction, prompt engineering, and voice selection handled automatically), and heygen-translate to localize existing videos into 175+ languages with voice cloning and lip-sync.",
     "developerName": "HeyGen",
     "category": "Design",
     "capabilities": ["Read", "Write"],
     "websiteURL": "https://heygen.com",
     "defaultPrompt": [
       "Create my HeyGen avatar from this photo",
       "Make a 30-second intro video of myself",
-      "Send a video update to my team about this week's progress"
+      "Send a video update to my team about this week's progress",
+      "Translate this video into Spanish, Japanese, and German"
     ],
     "brandColor": "#0a0a0a",
     "composerIcon": "./assets/icon.png",

.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "heygen",
   "displayName": "HeyGen",
   "version": "1.3.2",
-  "description": "Create HeyGen avatar videos and personalized video messages. Build a persistent digital identity from a photo, then generate presenter-led videos with your digital twin.",
+  "description": "Create HeyGen avatar videos, personalized video messages, and translated / dubbed videos. Build a persistent digital identity from a photo, generate presenter-led videos with your digital twin, and localize existing videos into 175+ languages with voice cloning and lip-sync.",
   "author": {
     "name": "HeyGen",
     "email": "[email protected]"
@@ -24,8 +24,13 @@
     "presenter",
     "talking-head",
     "ai-avatar",
-    "avatar-video"
+    "avatar-video",
+    "translate",
+    "dub",
+    "localization",
+    "voice-cloning",
+    "lip-sync"
   ],
-  "tags": ["video", "avatar", "ai", "identity", "presenter", "creative"],
-  "skills": ["./heygen-avatar/", "./heygen-video/"]
+  "tags": ["video", "avatar", "ai", "identity", "presenter", "creative", "translation", "localization"],
+  "skills": ["./heygen-avatar/", "./heygen-video/", "./heygen-translate/"]
 }

.github/workflows/validate-skills.yml

@@ -5,12 +5,14 @@ on:
     paths:
       - "heygen-avatar/**"
       - "heygen-video/**"
+      - "heygen-translate/**"
       - ".github/workflows/validate-skills.yml"
   push:
     branches: [master]
     paths:
       - "heygen-avatar/**"
       - "heygen-video/**"
+      - "heygen-translate/**"
       - ".github/workflows/validate-skills.yml"
 
 jobs:
@@ -43,8 +45,9 @@ jobs:
           # gh skill install --from-local requires the skills/<name>/SKILL.md convention.
           # Stage the in-repo subdir skills under a temporary skills/ root so we can validate.
           mkdir -p _ghskill_test/skills
-          cp -R heygen-avatar _ghskill_test/skills/heygen-avatar
-          cp -R heygen-video  _ghskill_test/skills/heygen-video
+          cp -R heygen-avatar    _ghskill_test/skills/heygen-avatar
+          cp -R heygen-video     _ghskill_test/skills/heygen-video
+          cp -R heygen-translate _ghskill_test/skills/heygen-translate
 
       - name: Init isolated install project
         run: |
@@ -147,6 +150,50 @@ jobs:
           fi
           echo "✓ heygen-video/references/ has no parent-dir refs"
 
+      - name: Install heygen-translate from local
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          cd _install_test
+          gh skill install ../_ghskill_test heygen-translate --from-local --scope project
+          test -f .agents/skills/heygen-translate/SKILL.md
+          echo "✓ heygen-translate installed at _install_test/.agents/skills/heygen-translate/"
+
+      - name: Verify heygen-translate installed bundle is self-contained
+        run: |
+          set -euo pipefail
+          cd _install_test/.agents/skills/heygen-translate
+          if grep -nE '\.\./' SKILL.md; then
+            echo "::error::heygen-translate/SKILL.md contains parent-dir (../) references after install"
+            exit 1
+          fi
+          fail=0
+          for ref in $(grep -oE '(references|scripts)/[a-zA-Z0-9_./-]+\.(md|sh)' SKILL.md | sort -u); do
+            if [ ! -f "$ref" ]; then
+              echo "::error::heygen-translate references $ref but it's not in the installed bundle"
+              fail=1
+            fi
+          done
+          while IFS= read -r f; do
+            base=$(basename "$f")
+            if ! grep -q "$base" SKILL.md; then
+              echo "::error::orphaned bundled file (not linked from SKILL.md): $f"
+              fail=1
+            fi
+          done < <(find references scripts -type f 2>/dev/null)
+          if [ "$fail" -ne 0 ]; then exit 1; fi
+          echo "✓ heygen-translate bundle is self-contained, no orphans"
+
+      - name: Verify no parent-dir refs in heygen-translate references/
+        run: |
+          set -euo pipefail
+          if grep -rnE '\.\./\.\.' heygen-translate/references/ 2>/dev/null; then
+            echo "::error::heygen-translate/references/ contains ../../ paths that will break inside an installed bundle"
+            exit 1
+          fi
+          echo "✓ heygen-translate/references/ has no parent-dir refs"
+
   spec-validate-soft:
     name: agentskills.io spec validation (advisory)
     runs-on: ubuntu-latest

CLAUDE.md

@@ -2,7 +2,13 @@
 
 ## What This Is
 
-The HeyGen Skills. Two independent, self-contained skills that chain together: **heygen-avatar** (identity → avatar → voice) and **heygen-video** (idea → script → video). Each ships its own bundle of references so it installs cleanly via `gh skill install`, ClawHub, the OpenClaw plugin, or direct git clone.
+The HeyGen Skills. Three independent, self-contained skills:
+
+- **heygen-avatar** — identity → avatar → voice. Output is reused by heygen-video.
+- **heygen-video** — idea → script → video. Consumes avatars from heygen-avatar.
+- **heygen-translate** — existing video → dubbed and lip-synced video in another language. Independent of the other two.
+
+Each ships its own bundle of references so it installs cleanly via `gh skill install`, ClawHub, the OpenClaw plugin, or direct git clone.
 
 ## Architecture
 
@@ -39,6 +45,13 @@ heygen-skills/
 │   │   └── troubleshooting.md
 │   └── scripts/
 │       └── update-check.sh     # Self-contained version-check shell script
+├── heygen-translate/           # Self-contained skill
+│   ├── SKILL.md                # Translation / dubbing workflow (4-phase pipeline)
+│   └── references/             # On-demand docs, loaded per phase
+│       ├── asset-routing.md
+│       ├── language-locale-guide.md
+│       ├── proofreads-workflow.md
+│       └── troubleshooting.md
 ├── platforms/                  # Platform-specific skill variants (e.g. nanoclaw)
 ├── assets/                     # Logos, plugin assets
 └── evals/                      # Dev-only test infrastructure (not shipped to users)
@@ -47,7 +60,7 @@ heygen-skills/
     └── round-N-scenarios.md
 ```
 
-*No root SKILL.md, no root references/.* The two skills are independent. If shared docs drift between them, that's acceptable — each skill is internally consistent and authored independently.
+*No root SKILL.md, no root references/.* The three skills are independent. If shared docs drift between them, that's acceptable — each skill is internally consistent and authored independently.
 
 ## The 300-Line Rule
 

CONTRIBUTING.md

@@ -43,9 +43,9 @@ gh pr create --title "Short summary" --body "$(cat <<'EOF'
 - [ ] No spec-sheet language leaked into user-facing output
 ## References layout
 
-`heygen-avatar/` and `heygen-video/` are *independent, self-contained skills*. Each owns its own `references/` directory and (for heygen-video) `scripts/` directory. There is no root `SKILL.md` and no root `references/`.
+`heygen-avatar/`, `heygen-video/`, and `heygen-translate/` are *independent, self-contained skills*. Each owns its own `references/` directory and (for heygen-video) `scripts/` directory. There is no root `SKILL.md` and no root `references/`.
 
-- Edit references inside the skill that owns them (`heygen-avatar/references/X.md` or `heygen-video/references/X.md`).
+- Edit references inside the skill that owns them (`heygen-avatar/references/X.md`, `heygen-video/references/X.md`, or `heygen-translate/references/X.md`).
 - If two skills happen to share a doc (e.g. both have `troubleshooting.md` and `asset-routing.md`), edit the relevant copy. Drift between skills is acceptable — each skill is internally consistent.
 - CI (`.github/workflows/validate-skills.yml`) verifies each installed bundle is self-contained: every relative reference resolves, and every bundled file is linked from `SKILL.md`.
 

INSTALL.md

@@ -2,12 +2,13 @@
 
 Grab an [API key](https://app.heygen.com/api) and set it in your shell. If you're already on a HeyGen plan with MCP connected to your agent, you can skip the key — MCP will be used automatically.
 
-The repo ships *two* skills you can install:
+The repo ships *three* skills you can install:
 
 - **`heygen-avatar`** — build a persistent digital identity from a photo or description
 - **`heygen-video`** — generate identity-first presenter videos
+- **`heygen-translate`** — translate / dub existing videos into 175+ languages with voice cloning and lip-sync
 
-Most users want both. They chain together: `heygen-avatar` returns an avatar id that `heygen-video` consumes.
+Most users want avatar + video together. They chain: `heygen-avatar` returns an avatar id that `heygen-video` consumes. `heygen-translate` is independent — install it whenever you need to localize finished videos.
 
 ## Option 1 — `gh skill install` (works across 12+ agents)
 
@@ -16,20 +17,23 @@ If you have [GitHub CLI](https://cli.github.com) v2.90+ available, this is the m
 ```bash
 gh skill install heygen-com/skills heygen-avatar
 gh skill install heygen-com/skills heygen-video
+gh skill install heygen-com/skills heygen-translate
 ```
 
 Project scope (current repo only) is the default. For user scope (every project on this machine):
 
 ```bash
-gh skill install heygen-com/skills heygen-avatar --scope user
-gh skill install heygen-com/skills heygen-video  --scope user
+gh skill install heygen-com/skills heygen-avatar    --scope user
+gh skill install heygen-com/skills heygen-video     --scope user
+gh skill install heygen-com/skills heygen-translate --scope user
 ```
 
 Pin to a release tag for reproducibility:
 
 ```bash
-gh skill install heygen-com/skills [email protected] --pin
-gh skill install heygen-com/skills [email protected]  --pin
+gh skill install heygen-com/skills [email protected]    --pin
+gh skill install heygen-com/skills [email protected]     --pin
+gh skill install heygen-com/skills [email protected] --pin
 ```
 
 ## Option 2 — ClawHub
@@ -38,7 +42,7 @@ gh skill install heygen-com/skills [email protected]  --pin
 clawhub install heygen-skills
 ```
 
-ClawHub installs both skills to your agent's default skills directory automatically.
+ClawHub installs all three skills to your agent's default skills directory automatically.
 
 ## Option 3 — OpenClaw plugin
 

INSTALL_FOR_AGENTS.md

@@ -19,6 +19,7 @@ live at:
 - `https://raw.githubusercontent.com/heygen-com/skills/master/CLAUDE.md` — runtime contract for the skills
 - `https://raw.githubusercontent.com/heygen-com/skills/master/heygen-avatar/SKILL.md` — avatar creation skill (mode detection ladder, hard rules, full creation workflow)
 - `https://raw.githubusercontent.com/heygen-com/skills/master/heygen-video/SKILL.md` — video generation skill (mode detection ladder, hard rules, full producer pipeline)
+- `https://raw.githubusercontent.com/heygen-com/skills/master/heygen-translate/SKILL.md` — video translation / dubbing skill (mode detection ladder, hard rules, proofreads workflow)
 - `https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL.md` — human-facing install doc
 
 ## Step 1: Detect the agent host and pick the install path
@@ -330,6 +331,7 @@ Tell the user:
 > - "Make a 30-second video of yourself introducing what we're working on this week"
 > - "Send a video update to the team about today's progress"
 > - "Generate a 60-second product walkthrough using my avatar"
+> - "Translate this video into Spanish, Japanese, and German" (heygen-translate)
 
 The skill handles avatar resolution, prompt engineering, aspect ratio
 correction, voice selection, and Frame Check automatically. Give it a topic,

README.md

@@ -24,13 +24,14 @@ Want to install manually instead? Follow the steps below.
 
 ### Step 1 — Install the skills
 
-The repo ships two skills, `heygen-avatar` and `heygen-video`. Pick the install path that matches your tooling.
+The repo ships three skills: `heygen-avatar`, `heygen-video`, and `heygen-translate`. Pick the install path that matches your tooling.
 
 **Option A: `gh skill install`** (works across Claude Code, Cursor, Codex, Gemini CLI, Copilot, Junie, Goose, OpenHands, Amp, Cline, OpenCode, Warp, and more — [agentskills.io](https://agentskills.io)):
 
 ```bash
 gh skill install heygen-com/skills heygen-avatar
 gh skill install heygen-com/skills heygen-video
+gh skill install heygen-com/skills heygen-translate
 ```
 
 Requires GitHub CLI v2.90+. The CLI writes to the right directory for your agent automatically.
@@ -59,7 +60,7 @@ openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen
 git clone --single-branch --depth 1 https://github.com/heygen-com/skills.git <install-path>/heygen-skills
 ```
 
-After cloning, the two skills are auto-discovered at `heygen-avatar/SKILL.md` and `heygen-video/SKILL.md`.
+After cloning, the three skills are auto-discovered at `heygen-avatar/SKILL.md`, `heygen-video/SKILL.md`, and `heygen-translate/SKILL.md`.
 
 ### Step 2 — Get your HeyGen API key
 
@@ -138,14 +139,15 @@ The skill picks up the avatar automatically, writes a script, generates the vide
 
 ## What's Included
 
-Two skills that work standalone or chain together:
+Three skills that work standalone or chain together:
 
 | Skill | What it does | Invoke |
 |-------|-------------|--------|
 | **heygen-avatar** | Photo → persistent digital twin (face + voice). Reusable across every video. | `/heygen-avatar` |
 | **heygen-video** | Idea → script → prompt-engineered video with your avatar delivering the message. | `/heygen-video` |
+| **heygen-translate** | Existing video → translated and dubbed version with voice cloning and lip-sync. 175+ languages. | `/heygen-translate` |
 
-**heygen-avatar** creates the identity. **heygen-video** uses it.
+**heygen-avatar** creates the identity. **heygen-video** uses it. **heygen-translate** localizes finished videos.
 
 ## How It Works