Keyframe Coach

Keyframe Coach

SKILL_DIR = the directory containing this file.

Connector: MCP for Blender (official)

All Blender work goes through the official MCP for Blender server (tools mcp__blender__*). If they are deferred, load them in one ToolSearch call: select:mcp__blender__get_addon_status,mcp__blender__get_scene_info,mcp__blender__execute_blender_code,mcp__blender__look.

• Start with get_addon_status. "Could not connect" means Blender is not running or the add-on's server is off. Don't launch or repair it yourself: work headless (below). If the user wants to watch in a live Blender, tell them to enable Interface: MCP for Blender in Preferences → Add-ons and click Start MCP Server.
• If it reports up_to_date: false but connects, carry on and mention uvx mcp-for-blender install-addon to the user.
• get_scene_info: scene facts as text. Use fields: ["animation", "details"] for actions and bones, fields: ["settings"] for frame range and fps, root/query to find the armature.
• execute_blender_code: runs bpy in the live Blender. Print what you need; work in small steps.
• look: the only way to see the result (see Workflow step 7).
• Do not use the old third-party blender-mcp (ahujasid) tools such as get_viewport_screenshot or get_object_info.

Headless and keeping runs cheap

Every turn re-reads the whole conversation, so the number of turns and of images drives the cost.

• Without the connector, keep the whole animation in one script file and make each pass a single command: rebuild, audit and, when needed, render: blender -b -P anim.py -- out.blend && blender -b out.blend --python-expr "exec(open('<SKILL_DIR>/scripts/audit.py').read()); audit(...)".
• Change that script with the Edit tool, not sed: line edits in Python break indentation and cost a turn each time.
• Each image stays in context for the rest of the session. Look only once the audit is clean, and tile the key frames into one contact sheet per view (≤1024 px wide) instead of separate images: ffmpeg -pattern_type glob -i 'f_*.png' -vf "scale=256:-1,tile=4x2" -frames:v 1 sheet.png. Look again only after a visible change.
• Don't read audit.py: each line it prints says what it measured and by how much.

Step 0: two mandatory questions (always, before any animation work)

Ask both with the AskUserQuestion tool in one call. Skip a question only if the user already answered it in this conversation. Do not guess or assume defaults.

1. Export target: Unity, Unreal, Godot, Roblox (Other → ask which).
2. Style: Realistic, Stylized/cartoony, Blocky/rigid-part (Roblox-like, low-poly), Anime/snappy.

Then read references/engines.md (the target's section only) and the matching style row in references/principles.md. For Roblox R6 rigs, also load the roblox-blender-setup skill and follow it for the rig and export steps. For a creature with more than two legs, also read references/legs.md.

Ask these too when they matter and are not obvious from the request: is the clip a loop (walk, run, idle) or a one-shot (attack, jump)? In-place or root motion? Is it player-triggered (needs fast startup) or AI/cinematic? For more than two legs: which gait (walk, trot, gallop; creep or scuttle for insects and spiders)?

Workflow

1. Inspect: mcp__blender__get_addon_status, then mcp__blender__get_scene_info (with fields: ["animation", "details", "settings"]), then find the armature, its actions, the frame range and fps. Headless: print all of that, plus each leg's lowest bone, from one script.
2. Plan timing: write down the key poses and the frame number of each before keying. For attacks, list startup, active and recovery frames. Use references/principles.md for frame counts.
3. Block (pose-to-pose): key only the main poses, all on the same frames, with stepped/constant interpolation so the timing reads.
4. Breakdowns: add in-betweens that put the limbs on arcs. Check with Motion Paths.
5. Spline and polish: switch to Bezier, then offset the overlapping parts (head, arms, tail, cloth) by 1–3 frames, add overshoot and settle, and fix the easing.
6. Audit: run scripts/audit.py (below) and fix what it reports.
7. Look: mcp__blender__look with mode: "frames" and frames: [...] on the key frames, once with view: [1, 0, 0.1] (side) and once with view: "camera" (gameplay angle). Use shading: "xray" to see bones and max_size: 512 for quick checks. Headless: one contact sheet per view (above).
8. Export using the target's settings in references/engines.md.

Blender 5.x: action.fcurves is gone. Read curves through bpy_extras.anim_utils.action_get_channelbag_for_slot(action, obj.animation_data.action_slot).

Audit

scripts/audit.py reads the animation data and reports concrete problems: loop seams that don't match, foot sliding, feet clipping through the floor, leftover linear keys, scale keys the engine will drop, every bone keyed on the same frames (no overlap), and left/right twinning. It changes nothing. Run it with mcp__blender__execute_blender_code, or headless as above (never skip it):

pythonCopy code
exec(open("<SKILL_DIR>/scripts/audit.py").read())
audit("Armature", engine="unity", loop=True, feet=["foot.L", "foot.R"])

Pass feet as the lowest bone of every leg, all of them (front paws are often named hand or wrist); the foot checks are skipped without it. Treat its output as hints, not verdicts: a linear key on a mechanical motion or a held pose on purpose is fine. Tell the user what it found and what you will change before changing it.