feat!: eliminate root SKILL.md + root references/ — skills are now independent

.github/workflows/validate-skills.yml

@@ -5,30 +5,15 @@ on:
     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
@@ -144,12 +129,28 @@ jobs:
           if [ "$fail" -ne 0 ]; then exit 1; fi
           echo "✓ heygen-video bundle is self-contained, no orphans"
 
+      - name: Verify no parent-dir refs in heygen-avatar references/
+        run: |
+          set -euo pipefail
+          if grep -rnE '\.\./\.\.' heygen-avatar/references/ 2>/dev/null; then
+            echo "::error::heygen-avatar/references/ contains ../../ paths that will break inside an installed bundle"
+            exit 1
+          fi
+          echo "✓ heygen-avatar/references/ has no parent-dir refs"
+
+      - name: Verify no parent-dir refs in heygen-video references/
+        run: |
+          set -euo pipefail
+          if grep -rnE '\.\./\.\.' heygen-video/references/ 2>/dev/null; then
+            echo "::error::heygen-video/references/ contains ../../ paths that will break inside an installed bundle"
+            exit 1
+          fi
+          echo "✓ heygen-video/references/ has no parent-dir refs"
+
   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
@@ -167,6 +168,4 @@ jobs:
       - 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)."
+        run: gh skill publish --dry-run || true

CLAUDE.md

@@ -2,38 +2,53 @@
 
 ## What This Is
 
-The HeyGen Skills. Two skills that chain together: **heygen-avatar** (identity → avatar → voice) and **heygen-video** (idea → script → video). SKILL.md at root routes between them.
+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.
 
 ## Architecture
 
 ```
 heygen-skills/
-├── SKILL.md                    # Router: detects intent, dispatches to sub-skill
 ├── CLAUDE.md                   # This file. Structure, rules, conventions.
 ├── INSTALL.md                  # Installation instructions
+├── INSTALL_FOR_AGENTS.md       # Agent-driven install spec
 ├── README.md                   # Public-facing description
 ├── CONTRIBUTING.md             # PR workflow
+├── CHANGELOG.md
 ├── LICENSE
-├── heygen-avatar/
-│   └── SKILL.md                # Avatar creation workflow (identity → avatar → voice → AVATAR file)
-├── heygen-video/
-│   └── SKILL.md                # Video production workflow (7-stage pipeline)
-├── references/                 # Shared. Loaded on-demand by phase (NOT every turn)
-│   ├── avatar-discovery.md     # Discovery: avatar lookup, voice selection, curl examples
-│   ├── asset-routing.md        # Discovery: asset classification engine, upload flows
-│   ├── prompt-styles.md        # Prompt Craft: 6 prompt style templates
-│   ├── motion-vocabulary.md    # Prompt Craft: camera/transition vocabulary
-│   ├── prompt-craft.md         # Prompt Craft: prompt construction deep-dive
-│   ├── official-prompt-guide.md# Prompt Craft: HeyGen's own prompt research
-│   ├── frame-check.md          # Frame Check: aspect ratio correction prompts
-│   ├── troubleshooting.md      # Known issues, workarounds, duration variance
-│   └── reviewer-prompt.md      # Deliver: self-evaluation rubric
+├── VERSION
+├── .mcp.json + mcp.json        # MCP server config (root-level, used by plugin manifests)
+├── .claude-plugin/             # OpenClaw / Claude Code plugin manifest
+├── .codex-plugin/              # Codex plugin manifest
+├── .cursor-plugin/             # Cursor plugin manifest
+├── heygen-avatar/              # Self-contained skill
+│   ├── SKILL.md                # Avatar creation workflow (identity → avatar → voice → AVATAR file)
+│   └── references/             # On-demand docs, loaded per phase
+│       ├── asset-routing.md
+│       ├── avatar-creation.md
+│       └── troubleshooting.md
+├── heygen-video/               # Self-contained skill
+│   ├── SKILL.md                # Video production workflow (7-stage pipeline)
+│   ├── references/             # On-demand docs, loaded per phase
+│   │   ├── asset-routing.md
+│   │   ├── avatar-discovery.md
+│   │   ├── frame-check.md
+│   │   ├── motion-vocabulary.md
+│   │   ├── official-prompt-guide.md
+│   │   ├── prompt-craft.md
+│   │   ├── prompt-styles.md
+│   │   └── troubleshooting.md
+│   └── scripts/
+│       └── update-check.sh     # Self-contained version-check shell script
+├── platforms/                  # Platform-specific skill variants (e.g. nanoclaw)
+├── assets/                     # Logos, plugin assets
 └── evals/                      # Dev-only test infrastructure (not shipped to users)
-    ├── eval-runner-prompt.md   # Instructions for eval subagent
-    ├── autoresearch-loop.md    # Loop methodology docs
-    └── round-N-scenarios.md    # Per-round test scenarios
+    ├── eval-runner-prompt.md
+    ├── autoresearch-loop.md
+    └── 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.
+
 ## The 300-Line Rule
 
 Each SKILL.md must stay under 300 lines. Skill files are injected into EVERY prompt turn.
@@ -43,7 +58,7 @@ Each SKILL.md must stay under 300 lines. Skill files are injected into EVERY pro
 - Stage flow overview (what stages exist, when to enter each)
 - Decision trees (mode detection, avatar path selection, style selection)
 - Critical rules that apply EVERY turn
-- Short "Read ../references/X.md for details" pointers at each stage
+- Short "Read references/X.md for details" pointers at each stage (relative to the skill's own SKILL.md — each skill bundles its own references/)
 
 **What moves to references/:**
 - Curl examples and API request/response shapes

CONTRIBUTING.md

@@ -41,22 +41,13 @@ 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.
+`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/`.
 
-CI (`.github/workflows/validate-skills.yml`) runs `./scripts/sync-references.sh --check` on every PR and fails on drift.
+- Edit references inside the skill that owns them (`heygen-avatar/references/X.md` or `heygen-video/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`.
 
 ## Breaking changes
 

INSTALL_FOR_AGENTS.md

@@ -17,9 +17,8 @@ If you fetched this file by URL without cloning yet, the companion files
 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/SKILL.md` — top-level skill (mode detection ladder, hard rules)
-- `https://raw.githubusercontent.com/heygen-com/skills/master/heygen-avatar/SKILL.md` — avatar creation sub-skill
-- `https://raw.githubusercontent.com/heygen-com/skills/master/heygen-video/SKILL.md` — video generation sub-skill
+- `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/INSTALL.md` — human-facing install doc
 
 ## Step 1: Detect the agent host and pick the install path
@@ -70,7 +69,7 @@ If MCP is detected and the user is happy with it, **skip to Step 5 (avatar creat
 But before you do, warn them:
 
 > If you set `HEYGEN_API_KEY` later for any reason, the skill will short-circuit
-> MCP detection (per the mode-detection ladder in `SKILL.md`) and use the CLI /
+> MCP detection (per the mode-detection ladder in `heygen-video/SKILL.md` or `heygen-avatar/SKILL.md`) and use the CLI /
 > direct-API route instead. MCP plan credits won't be touched. To switch back to
 > MCP, unset `HEYGEN_API_KEY`.
 
@@ -110,7 +109,7 @@ For the OpenClaw plugin path (Step 4 Option A), the key is read from the same
 
 These skills route the actual HeyGen API call through one of three transports.
 The skill auto-detects which transport is available at runtime via the
-mode-detection ladder in [`SKILL.md`](./SKILL.md):
+mode-detection ladder in each skill's SKILL.md (e.g. [`heygen-video/SKILL.md`](./heygen-video/SKILL.md) or [`heygen-avatar/SKILL.md`](./heygen-avatar/SKILL.md)):
 
 > 1. **OpenClaw plugin** if `video_generate` exposes `heygen/video_agent_v3`
 > 2. **CLI (API-key override)** if `HEYGEN_API_KEY` is set AND `heygen --version` exits 0
@@ -348,7 +347,7 @@ If the install was via ClawHub:
 clawhub update heygen-skills
 ```
 
-Re-read [`SKILL.md`](./SKILL.md) after the upgrade if the version bumped — the
+Re-read the active skill's SKILL.md (`heygen-avatar/SKILL.md` or `heygen-video/SKILL.md`) after the upgrade if the version bumped — the
 mode detection ladder occasionally adds new transports (e.g. when MCP support
 shipped, when the OpenClaw plugin shipped).
 
@@ -370,7 +369,7 @@ should always pass `mode: "generate"` for one-shot video creation. If you
 patched the sub-skill, you may have introduced this regression.
 
 **MCP tools listed but the skill is using the CLI / plugin instead.** The
-skill follows the mode-detection ladder in `SKILL.md`: plugin → CLI
+skill follows the mode-detection ladder in its SKILL.md (heygen-avatar or heygen-video): plugin → CLI
 (API-key override) → MCP → CLI (fallback). **`HEYGEN_API_KEY` being set
 short-circuits MCP detection.** If the user wants MCP to be the chosen
 transport, unset the env var (`unset HEYGEN_API_KEY`) and re-detect. If the