init: animation pipeline hub — Mac↔PC bridge for converting and implementing animations

Skills (.claude/skills/): animation-creation, iclone-video-mocap,
pose-estimation (MediaPipe models via LFS), retarget-animations (deprecated).
Tools: cc/mixamo/kevin/mocap retargeters + composite baker.
Plans: animation-gen-pipeline + skills-adoption.
exchange/: incoming-fbx, converted-glb, reference-video (LFS for fbx/glb/mp4).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

plans/animation-skills-adoption-2026-07-13.md

@@ -0,0 +1,112 @@
+# Animation skills adoption — 2026-07-13
+
+Goal: let agents **create** animations and rig them onto GLBs for ariki-game, not just
+retarget existing packs. All animation runs on the one shared Quaternius skeleton (65
+bones, UE names), so the bottleneck is tooling that gets new motion onto that rig. This
+report records the research tiering, what this pass integrated (file authoring only), and
+the orchestrator runbook for the install/launch steps an agent must not do.
+
+## Research findings
+
+**Tier 1 — adopt now (integrated or queued for trial this pass):**
+
+- **blender-mcp** (github.com/ahujasid/blender-mcp, MIT, 16k+ stars) — MCP server bridging
+  the agent to a live Blender via a socket addon; the agent sends arbitrary `bpy` to build
+  armatures, keyframe, set up IK/NLA, and export GLB. *Why Tier 1:* the one capability the
+  project was missing — direct programmatic Blender authoring from the agent loop.
+- **Blender Toolkit skill** (majiayu000) — Mixamo→custom-rig retarget with fuzzy bone
+  matching over a WebSocket bridge. *Why Tier 1:* directly comparable to the project's own
+  `tools/mixamo_retarget.py`; trial it head-to-head and keep the winner.
+- **Blender Animation & Rigging Expert skill** — programmatic armatures, IK/FK, drivers,
+  NLA via MCP. *Why Tier 1:* the deep-blender companion to blender-mcp for non-trivial rigs.
+- **Extend our own project skill** (this pass) — the existing `.claude/skills/animation-creation/`
+  is the cheapest surface; adding Path 5 + gltf-transform keeps everything in one place.
+
+**Tier 2 — trial before committing:**
+
+- **gltf-transform** (gltf-transform.dev, donmccurdy) — headless GLB surgery: inspect,
+  merge, resample, prune, dedup; same-skeleton clip transplants need no Blender. *Why Tier
+  2:* documented here and usable via `npx`, but the project's clip-editing volume is
+  currently low; adopt the recipes, verify the v4 API on first real use.
+- **PoseCap** (github.com/CorridorTech/PoseCap) — markerless mocap, video → PEAR model →
+  SMPL-X poses → Blender keyframes; works on pre-recorded clips; custom-rig retarget is
+  roadmap-only; UI extension, not headless. *Why Tier 2:* promising video-to-motion path,
+  but SMPL-X→Quaternius retarget is unbuilt — eval before investing.
+- **OpenClaw / freshtechbro Blender pipeline skills** — engine export-settings knowledge.
+  *Why Tier 2:* useful reference for engine-specific gotchas, redundant once our export
+  block is canonical.
+
+**Tier 3 — skip for now:**
+
+- **godot-mcp servers** — redundant: the game already has an agent API on port 4329 plus an
+  in-scene `VideoRecorder`; a Godot MCP adds nothing.
+- **DavinciDreams 3D Design Team plugin and other knowledge-only skill packs** — broad and
+  shallow; the targeted recipes above cover the same ground more concretely.
+
+## Integrated in this pass
+
+File authoring only (no installs, no commits):
+
+- **A — `.mcp.json`**: registered the `blender` MCP server (`uvx blender-mcp`).
+- **B — `.claude/skills/animation-creation/SKILL.md`**: added **Path 5 — Author in live
+  Blender (blender-mcp)** and a **GLB surgery without Blender (gltf-transform)** section,
+  both pointing at the new reference docs.
+- **C — `references/blender-mcp-recipes.md`** (new): `bpy` recipes for setup, keyframing,
+  IK setup + bake, NLA layering, and an **export block mirrored exactly from
+  `tools/mixamo_retarget.py`** (`NLA_TRACKS` mode, `export_force_sampling`, size-opt off),
+  plus gotchas (`*RM` variants, `RESET` clip, one armature/GLB, fps=30, quaternion mode).
+- **D — `references/gltf-transform-recipes.md`** (new): CLI/SDK inspect, same-skeleton clip
+  transplant sketch (flagged `verify against gltf-transform v4 API before first use`),
+  resample/prune/dedup shrink pass, and when-to-prefer-over-Blender guidance.
+
+## Orchestrator runbook
+
+**Not run by the authoring agent.** The orchestrator (or Jeremy) executes these:
+
+1. **blender-mcp smoke test.** From a shell: `uvx blender-mcp` — confirm the server starts
+   and binds the socket (Ctrl-C to stop; this only checks installability).
+2. **Install the Blender addon.** Download `addon.py` from
+   github.com/ahujasid/blender-mcp and in Blender 5.1.2
+   (`/Applications/Blender.app`): Edit → Preferences → Add-ons → Install → select
+   `addon.py` → enable. Then 3D View sidebar → BlenderMCP → **Connect**.
+3. **Reload MCP config.** Restart Claude Code so the `blender` server in `.mcp.json` is
+   picked up; confirm the `blender` MCP tools (`execute-code`, etc.) are now available.
+4. **blender-mcp agent smoke test.** Through the MCP tools: import a game GLB
+   (`assets/quaternius/kevin/kevin_male_social.glb`), keyframe a wave on `hand_l`
+   (see `blender-mcp-recipes.md` keyframing recipe), export GLB into
+   `assets/quaternius/mixamo/`, and confirm the new clip appears in
+   `scenes/animation_showcase.tscn`.
+5. **gltf-transform smoke test.** `npx @gltf-transform/cli inspect
+   assets/quaternius/kevin/kevin_male_social.glb` — confirm it lists the animations and
+   their durations. (No install step; `npx` fetches the CLI on demand.)
+6. **Skill trials (user-level install at `~/.claude/skills/`).** Install **Blender Toolkit**
+   (majiayu000) and **Blender Animation & Rigging Expert**. Run one Mixamo clip → Quaternius
+   retarget through Blender Toolkit and compare the output against
+   `tools/mixamo_retarget.py` in the dance test bed — keep whichever loses as
+   reference-only.
+7. **PoseCap eval.** Install the PoseCap Blender extension; run one short dance clip →
+   SMPL-X keyframes; assess quality vs the existing "match video to shipped clips via the
+   pose-estimation skill" approach **before** investing in SMPL-X→Quaternius retarget.
+
+> **Always ASK Jeremy before any game launch.** Run `tinqs pull` before launching the game
+> so the working tree is current.
+
+## Verification
+
+- **Retarget round-trip:** a clip authored via blender-mcp (or retargeted through Blender
+  Toolkit) plays correctly in the dance test bed (`SCENE=dance_test_bed
+  bash tools/game.sh spawn` — ask Jeremy first), recorded with the in-scene
+  `VideoRecorder` to `~/Downloads/*.mp4` and scored against source footage with the
+  `pose-estimation` skill.
+- **gltf-transform clip transplant:** a clip moved between two same-skeleton GLBs via the
+  SDK recipe plays in `scenes/animation_showcase.tscn` at the expected `<pack>/<ClipName>`,
+  confirming the channel-target re-pointing worked.
+
+## Open items
+
+- Confirm the gltf-transform v4 SDK call for cross-document animation copy on first real
+  use (the `copyToDocument` sketch in `gltf-transform-recipes.md` is flagged for this).
+- Decide Blender Toolkit vs `tools/mixamo_retarget.py` after the head-to-head retarget
+  trial (runbook step 6).
+- Decide whether to invest in SMPL-X→Quaternius retarget after the PoseCap quality eval
+  (runbook step 7).