animation/.agents/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).