| name | octocode-mannequin |
| description | Use when posing, animating, or explaining a 3D human skeleton/manikin: anatomical joints, ROM clamps, walk/run/dance/backflip sequences, Three.js viewer, or agent-driven WebMCP figure control (reach/look_at). Phrases like pose the manikin, skeleton scheme, animate a walk cycle. Not for general 3D scenes, physics/ragdoll, IK foot-locking, or mocap import. |
Octocode Mannequin
Anatomically-named 22-bone humanoid rig (arms-down neutral, bilaterally mirrored) plus a movement protocol that
clamps every joint to real range of motion, with a root 6-DOF channel (translate/pitch/yaw/roll) for travel,
turns, jumps and backflips — a Node CLI, a self-contained Three.js viewer (grounded, smooth Catmull-Rom
animation), and WebMCP tools an agent drives live. Flow: SCHEME → COMMAND → CLAMP+FK → RENDER → DRIVE.
Hard rules
scripts/skeleton.mjs is the single source of truth for bones/joints/ROM/movements; references and the
viewer mirror it. The viewer re-implements the clamp/sideSign/FK math — any change must be made in BOTH
files and re-verified (they must stay identical).- Movement commands use anatomical names valid for that joint, never raw signed degrees and never a movement
outside the joint's allowlist — read
references/movement-protocol.md before composing one; the CLI and the
tools reject those.
- Treat ROM values as rig defaults, not medical fact — read
references/rom-table.md before quoting a limit.
Gate
Writing a viewer file (viewer --out <file>.html) overwrites that path, and agent-driving needs a fresh
non-headless Chrome on a new port: confirm the output path and get the user's OK before the first write or
browser launch.
Workflow
- Run
node scripts/skeleton.mjs scheme first to inspect bones + joint DOF/ROM/movements; for the hierarchy read
references/anatomy-scheme.md, for the constraint model read references/joint-constraints.md, and for exact
degrees read references/rom-table.md.
- Compose a pose command using
references/movement-protocol.md, run node scripts/skeleton.mjs pose --cmd '...',
read warnings/clamped; then validate an animation by running skeleton.mjs sequence --file frames.json.
- To render, run
node scripts/skeleton.mjs viewer --out <file>.html [--pose pose.json], open it, drag sliders or
call window.applyPose/window.playSequence from the console — ready animations live in assets/
(run-cycle.json, backflip.json, dance.json, idle.json for alive breathing/sway); for the viewer's
mechanics read references/viewer-guide.md.
- To agent-drive it live, load
references/webmcp-agent.md and serve the viewer's WebMCP tools over CDP — 11 tools
incl. task-space reach (put a hand/foot at a world point) and look_at; get_scheme.guide is the frame/units
contract. Discover, invoke, verify with get_pose or a screenshot.
Stop when: the pose verifies via get_pose or a screenshot; clamped:true shows the joint is already at its ROM
limit (that is the answer — do not push past it); a movement is rejected as invalid for the joint (retry with the
reported allowlist, never with raw degrees); reach returns reached:false with a residual distance (the target is
out of range — re-target, do not re-invoke unchanged); tool discovery returns WEBMCP_NO_TOOLS or fewer than 11
tools (fall back to window.applyPose via Runtime.evaluate); screenshots come back blank (Chrome is headless —
relaunch non-headless); or the request needs physics, IK foot-locking, or mocap (out of scope, say so).
When NOT this skill
General 3D scene setup, or physics/ragdoll simulation, IK foot-locking, balance, collision, or mocap (BVH/glTF)
import. Motion is keyframed kinematics — a backflip is authored, not simulated; for why that scope was
chosen read references/references.md.
Progressive refs
| Ref | When |
|---|
references/anatomy-scheme.md | Building/explaining the bone hierarchy |
references/joint-constraints.md | DOF/constraint model + verified rotation directions per joint |
references/rom-table.md | Exact degree limits per movement |
references/movement-protocol.md | Writing/validating a pose command |
references/viewer-guide.md | Generating/driving the Three.js viewer |
references/webmcp-agent.md | Agent-driving the manikin via WebMCP + CDP |
references/references.md | Provenance / why a design choice was made |
Scripts
- Run
node scripts/skeleton.mjs for the scheme / pose / sequence / viewer subcommands (--help); zero npm installs. WebMCP CDP mechanics are delegated to the octocode-chrome-devtools skill.
