mcpField
O
octocode-mannequin

octocode-mannequin

github.com/bgauryyCreative & media9569 installsUpdated 9w ago
Repository

About octocode-mannequin

A skill for creating and validating keyframed humanoid poses and animations with an anatomically named, range-constrained rig. It includes a Node CLI, a Three.js viewer, and live WebMCP controls for agent-driven movement.

Key features

  1. 01Inspect rig, joints, and movement scheme
  2. 02Compose and validate constrained poses
  3. 03Validate animation frame sequences
  4. 04Generate and interact with a Three.js viewer
  5. 05Drive the rig through WebMCP tools

Use cases

  1. 01Build a constrained humanoid pose
  2. 02Check whether a joint movement is clamped
  3. 03Preview a keyframed animation
  4. 04Move the rig via agent tool calls

MCP support

The viewer exposes 11 WebMCP tools for live agent control, including reach and look_at. Agents can discover and invoke tools, then verify the resulting pose.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bgauryy/octocode --skill octocode-mannequin

After installing, type/octocode-mannequinin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
assets/
backflip.json
dance.json
idle.json
run-cycle.json
viewer.template.html
references/
anatomy-scheme.md
joint-constraints.md
movement-protocol.md
references.md
rom-table.md
viewer-guide.md
webmcp-agent.md
scripts/
skeleton.mjs

Details

From the project README

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

  1. 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).
  2. 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.
  3. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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

RefWhen
references/anatomy-scheme.mdBuilding/explaining the bone hierarchy
references/joint-constraints.mdDOF/constraint model + verified rotation directions per joint
references/rom-table.mdExact degree limits per movement
references/movement-protocol.mdWriting/validating a pose command
references/viewer-guide.mdGenerating/driving the Three.js viewer
references/webmcp-agent.mdAgent-driving the manikin via WebMCP + CDP
references/references.mdProvenance / 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.

Comments

Markdown supported