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

# 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).