feat: make heygen-avatar + heygen-video install cleanly via gh skill

.github/workflows/validate-skills.yml

@@ -0,0 +1,172 @@
+name: Validate Skills
+
+on:
+  pull_request:
+    paths:
+      - "heygen-avatar/**"
+      - "heygen-video/**"
+      - "references/**"
+      - "scripts/**"
+      - ".github/workflows/validate-skills.yml"
+      - "SKILL.md"
+  push:
+    branches: [master]
+    paths:
+      - "heygen-avatar/**"
+      - "heygen-video/**"
+      - "references/**"
+      - "scripts/**"
+      - ".github/workflows/validate-skills.yml"
+      - "SKILL.md"
+
+jobs:
+  references-in-sync:
+    name: Root references/ stays in sync with subdir copies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify references are in sync (no drift)
+        run: ./scripts/sync-references.sh --check
+
+  self-contained-bundles:
+    name: Skills install cleanly via gh skill (self-contained)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install latest gh
+        run: |
+          curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+            | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+          sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+            | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+          sudo apt update
+          sudo apt install -y gh
+          gh --version
+
+      - name: Verify gh skill is available
+        run: |
+          if ! gh skill --help >/dev/null 2>&1; then
+            echo "::error::gh skill subcommand not available in installed gh"
+            exit 1
+          fi
+
+      - name: Stage skills under skills/ for from-local install
+        run: |
+          # 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
+
+      - name: Init isolated install project
+        run: |
+          # gh skill install --scope project writes to <project_root>/.agents/skills.
+          # Initialize an isolated git repo for the install target so it becomes
+          # its own project root (otherwise gh skill walks up to the outer repo).
+          mkdir -p _install_test
+          cd _install_test
+          git init -q
+          git -c user.email='ci@heygen.com' -c user.name='CI' commit -q --allow-empty -m bootstrap
+
+      - name: Install heygen-avatar from local
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          cd _install_test
+          gh skill install ../_ghskill_test heygen-avatar --from-local --scope project
+          test -f .agents/skills/heygen-avatar/SKILL.md
+          echo "✓ heygen-avatar installed at _install_test/.agents/skills/heygen-avatar/"
+
+      - name: Verify heygen-avatar installed bundle is self-contained
+        run: |
+          set -euo pipefail
+          cd _install_test/.agents/skills/heygen-avatar
+          # No parent-dir references in installed SKILL.md.
+          if grep -nE '\.\./' SKILL.md; then
+            echo "::error::heygen-avatar/SKILL.md contains parent-dir (../) references after install"
+            exit 1
+          fi
+          # Every relative reference in SKILL.md must exist inside the installed bundle.
+          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-avatar references $ref but it's not in the installed bundle"
+              fail=1
+            fi
+          done
+          # Every bundled references/* and scripts/* file must be linked from SKILL.md.
+          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-avatar bundle is self-contained, no orphans"
+
+      - name: Install heygen-video from local
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          cd _install_test
+          gh skill install ../_ghskill_test heygen-video --from-local --scope project
+          test -f .agents/skills/heygen-video/SKILL.md
+          echo "✓ heygen-video installed at _install_test/.agents/skills/heygen-video/"
+
+      - name: Verify heygen-video installed bundle is self-contained
+        run: |
+          set -euo pipefail
+          cd _install_test/.agents/skills/heygen-video
+          if grep -nE '\.\./' SKILL.md; then
+            echo "::error::heygen-video/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-video 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-video bundle is self-contained, no orphans"
+
+  spec-validate-soft:
+    name: agentskills.io spec validation (advisory)
+    runs-on: ubuntu-latest
+    # Advisory only — fails are reported as warnings, not blocking.
+    # Root SKILL.md will fail validation today (name: heygen-skills doesn't match directory `.`).
+    # That's tracked as a known issue and is not a blocker for gh skill install.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install latest gh
+        run: |
+          curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+            | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+          sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+            | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+          sudo apt update
+          sudo apt install -y gh
+
+      - name: Run gh skill publish --dry-run
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh skill publish --dry-run || true
+          echo "::warning::Root SKILL.md does not satisfy gh skill publish naming rules (expected — gh skill publish to agentskills.io registry is a follow-up)."

.gitignore

@@ -6,3 +6,8 @@ node_modules/
 
 evals/
 scripts/release.sh
+
+# Local CI fixtures
+.agents/
+_ghskill_test/
+_install_test/

CONTRIBUTING.md

@@ -41,6 +41,22 @@ gh pr create --title "Short summary" --body "$(cat <<'EOF'
 - [ ] Full generation tested (video_id if applicable)
 - [ ] SKILL.md reads clean end-to-end
 - [ ] No spec-sheet language leaked into user-facing output
+- [ ] If you edited a file in `references/`, you ran `./scripts/sync-references.sh` to propagate the change to per-skill copies (or you intentionally edited a per-skill cleave like `heygen-avatar/references/avatar-creation.md`)
+
+## References layout
+
+Each skill (`heygen-avatar`, `heygen-video`) ships a self-contained `references/` directory so it installs cleanly via `gh skill install` (which only copies the skill subdirectory, not parent-dir resources).
+
+- **Source of truth** for shared docs: `references/<file>.md` at the repo root.
+- **Per-skill copies** are byte-identical mirrors of the root files.
+- **Per-skill cleaves** (`heygen-avatar/references/avatar-creation.md`, `heygen-video/references/avatar-discovery.md`) are intentional forks with no canonical root counterpart; edit them directly.
+
+**Editor workflow:**
+1. Edit the canonical root file (`references/<file>.md`).
+2. Run `./scripts/sync-references.sh` to propagate the change to per-skill copies.
+3. `git add` everything together and commit.
+
+CI (`.github/workflows/validate-skills.yml`) runs `./scripts/sync-references.sh --check` on every PR and fails on drift.
 
 ## Breaking changes
 

INSTALL.md

@@ -2,15 +2,53 @@
 
 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.
 
-## Option 1 — ClawHub (recommended)
+The repo ships *two* skills you can install:
+
+- **`heygen-avatar`** — build a persistent digital identity from a photo or description
+- **`heygen-video`** — generate identity-first presenter videos
+
+Most users want both. They chain together: `heygen-avatar` returns an avatar id that `heygen-video` consumes.
+
+## Option 1 — `gh skill install` (works across 12+ agents)
+
+If you have [GitHub CLI](https://cli.github.com) v2.90+ available, this is the most portable install. `gh skill` writes to the right directory for your agent automatically (Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Junie, Goose, OpenHands, Amp, Cline, OpenCode, Warp, and more):
+
+```bash
+gh skill install heygen-com/skills heygen-avatar
+gh skill install heygen-com/skills heygen-video
+```
+
+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
+```
+
+Pin to a release tag for reproducibility:
+
+```bash
+gh skill install heygen-com/skills heygen-avatar@v2.3.1 --pin
+gh skill install heygen-com/skills heygen-video@v2.3.1  --pin
+```
+
+## Option 2 — ClawHub
 
 ```bash
 clawhub install heygen-skills
 ```
 
-ClawHub installs to your agent's default skills directory automatically.
+ClawHub installs both skills to your agent's default skills directory automatically.
+
+## Option 3 — OpenClaw plugin
+
+For OpenClaw users who want bundled MCP support too:
+
+```bash
+openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen
+```
 
-## Option 2 — Git clone
+## Option 4 — Git clone
 
 Clone into your agent's skills directory:
 

README.md

@@ -22,21 +22,45 @@ That's it. The agent fetches [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md) an
 
 Want to install manually instead? Follow the steps below.
 
-### Step 1 — Clone into your skills directory
+### Step 1 — Install the skills
 
-Detect which agent you are and clone to the right path:
+The repo ships two skills, `heygen-avatar` and `heygen-video`. 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
+```
+
+Requires GitHub CLI v2.90+. The CLI writes to the right directory for your agent automatically.
+
+**Option B: ClawHub:**
+
+```bash
+clawhub install heygen-skills
+```
+
+**Option C: OpenClaw plugin** (bundles MCP support):
+
+```bash
+openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen
+```
+
+**Option D: Git clone** (legacy path):
 
 | Agent | Install path |
 |-------|-------------|
 | **Claude Code** | `~/.claude/skills/heygen-skills` |
 | **OpenClaw** | `~/.openclaw/workspace/skills/heygen-skills` |
-| **ClawHub** | Run `clawhub install heygen-skills` and skip to Step 2 |
 | **Other** | Clone anywhere your agent loads skills from |
 
 ```bash
 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`.
+
 ### Step 2 — Get your HeyGen API key
 
 1. Go to **[app.heygen.com/api](https://app.heygen.com/api)** (Settings → API)

heygen-avatar/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 2.3.0 # x-release-please-version
 name: heygen-avatar
 description: |
   Create a persistent HeyGen avatar — a reusable face + voice identity for the agent,
@@ -204,6 +205,8 @@ For agents and named characters, skip this entire step — go straight to Type A
 
 ### Phase 2 — Avatar Creation
 
+📖 **Full creation API surface (photo / prompt / digital twin), file input formats, identity field → enum mapping, response shape → [references/avatar-creation.md](references/avatar-creation.md)**
+
 Two modes:
 
 **Mode 1 — New character** (omit `avatar_group_id`):
@@ -231,6 +234,8 @@ File options for Type B:
 - `{ "type": "asset_id", "asset_id": "<id>" }` — from `heygen asset create --file <path>`
 - `{ "type": "base64", "media_type": "image/png", "data": "<base64>" }` — inline
 
+📖 **When to use each (URL vs asset_id vs base64), upload routing, and edge cases → [references/asset-routing.md](references/asset-routing.md)**
+
 **Response:** Returns `avatar_item.id` (look ID) and `avatar_item.group_id` (character identity).
 
 Map identity fields to HeyGen enums for the prompt:
@@ -411,3 +416,5 @@ simply `cat AVATAR-AGENT.md` and get whatever the current agent's avatar is.
 - Voice match poor → show all available voices, let user browse
 - Asset upload fails → skip reference image, try prompt-only creation
 - Existing avatar file with stale HeyGen IDs → offer to regenerate or keep
+
+📖 **Known issues, retry patterns, broken voice previews, error → action mapping → [references/troubleshooting.md](references/troubleshooting.md)**