The Problem

Technical documents often need a visual aid that literally builds the concept. Explaining a complex mechanism with a static diagram can leave gaps; an interactive, isometric figure that shows parts moving, shading changing, and numbers updating in real time removes those gaps. The pain point is that such figures are hard to create quickly, require multiple tools, and are difficult to embed in AI‑driven documentation.

What This Does

anatomy-skill supplies a reusable, dependency‑free kit that turns a small set of geometry and rig data into a polished SVG, an optional WebGL‑shaded canvas, and an interactive React UI.

  • Geometry & Rig – examples/spot-plate/geometry.ts, rig.ts, pose.ts describe the parts and their joints.
  • Rendering – kit/iso-kit.mjs drives the rendering pipeline, importing kit/gl.mjs for WebGL and kit/canvas-painter.mjs for 2‑D canvas.
  • React UI – kit/react/live.tsx hosts the live preview, wiring draw.tsx to the canvas and exposing controls.
  • Skill integration – agents/openai.yaml declares the /anatomy command that Claude or Codex can invoke, which in turn calls the kit code.

The output is an SVG paired with a small JS bundle that animates under mouse or keyboard. The examples (e.g., examples/raptor-engine/*) demonstrate the full flow from source files to a clickable card.

How It Is Wired

Entry Point – agents/openai.yaml defines the skill entry. When a user issues /anatomy explain …, the runtime resolves to the kit’s main export in kit/iso-kit.mjs. Core Flow – iso-kit.mjs imports gl.mjs (WebGL context setup), canvas-painter.mjs (2‑D drawing helpers), and the geometry/rig modules. It exposes renderFigure() which:

  1. Loads geometry data from geometry.ts and rig.ts.
  2. Uses draw.tsx to generate SVG nodes.
  3. If enableWebGL is true, passes the same data to gl.mjs to create a shader‑based plume.
  4. Serialises the SVG and writes it to disk via Node’s fs module (used in examples/*/build.mjs).
  5. Serves the interactive canvas through live.tsx, which mounts the React component to the page.

External Touches – The kit writes to the filesystem (fs.writeFile in examples/*/build.mjs) and serves a local HTTP preview (live.js uses http.createServer). No database or network calls are made. Hub & Cycle – The only dependency cycle is the small interplay between draw.tsx and live.tsx, which share a useState hook for joint positions. This tight coupling is intentional; the cycle is limited to the UI layer.

How To Use It

  1. Clone – git clone https://github.com/moses-y/anatomy-skill.
  2. Install – The kit uses only Node’s built‑in modules; run npm i if a package.json is added later, otherwise skip.
  3. Generate a Figure – node examples/raptor-engine/build.mjs produces raptor-engine.html and raptor-engine.svg.
  4. Preview Live – node examples/raptor-engine/live.js starts an HTTP server on http://localhost:3000.
  5. Run Tests – npm test (or node scripts/*test.mjs) executes the 44 Jest‑style test files in scripts/ and tests/.

The README already documents the npx skills add command for deploying the skill in Claude or Codex.

Real‑World Use

A technical writer can embed raptor-engine.html in a product spec. The interactive card updates numeric readouts as the user drags the engine, providing an intuitive understanding of thrust vs. pressure. The writer can modify geometry.ts to reflect design changes, re‑run build.mjs, and instantly see an updated illustration.

Code Health & Issues

  • Tests – 44 test files (mostly in scripts/*.test.mjs), covering geometry, rendering, and UI.
  • CI – .github/workflows/ci.yml runs tests and lint checks on every push.
  • Dependencies – Zero external dependencies; MIT license.
  • Missing Config – No package.json or lint config; the repo relies on Node 20+ alone.
  • Documentation – README, SKILL.md, and references/*.md provide usage guidance; deeper API docs would aid contributors.
  • Security – No secrets; CI badge shows no failures.

The Bottom Line

anatomy-skill delivers a lightweight, dependency‑free framework for generating interactive isometric illustrations that can be embedded in AI skill responses or web pages. Its minimal footprint and solid test coverage make it suitable for technical writers and developers who need quick, reproducible visual aids. The main limitation is the lack of build tooling and documentation beyond the examples, so contributors may need to add a package.json and richer API docs for broader adoption.