teardown: how a skill turns “how does this machine work?” into a 3D simulator

A1The repository: who reads each file

Click any file. Only one file in this repo, SKILL.md, gets into Claude's context automatically. Everything else is code Claude runs, code it copies, or code the browser runs.

A2Anatomy of SKILL.md

The order of its sections, and why each one is there. Expand any of them. If you're writing your own complex skill, this is the main pattern to copy.

A3The agent's loop, step by step

What Claude actually does with the skill, from the trigger to the final MP4. agent steps need judgment (Claude thinking and writing code). tool steps are deterministic scripts the skill ships. Steps 9–11 repeat until a full review pass finds nothing.

A4Ten lessons for writing complex skills

Why a skill like this beats a long prompt. Each lesson is tied to the place in teardown where you can see it.

B1One input drives everything

Rules 2 and 3: "Every gauge, chart and label reads from the same function that poses the parts", and "One input drives everything." In the V8 that input is the crank angle. Below, one number (ψ, degrees after this cylinder fires, 0–720°) drives the piston, rod, valves, charge colour, P-V diagram and valve chart, all through the formulas in v8-shared/kin.js with its real dimensions (bore 101.6 mm, crank radius 44.5, rod 145, compression ratio 10.2).

// kin.js: everything is a function of the phase ps. Nothing is keyframed.
export const pistonFrac = (ps) => {                 // 0 at TDC, 1 at BDC
  const a = (ps * Math.PI) / 180;
  const sp = E.r * Math.cos(a) + Math.sqrt(E.rod * E.rod - (E.r * Math.sin(a)) ** 2);
  return (S_TDC - sp) / STROKE;
};
export const volume = (ps) => 1 + (E.cr - 1) * pistonFrac(ps);   // in clearance volumes
export const pressure = (ps) => { /* polytropic compression, fast burn, expansion */ };

The panels in the real page (console.js) import pressure, volume, liftEx and liftIn from the same module that engine.js uses to pose the meshes. A chart can't disagree with the motion because both are computed by the same function.

B2The render(t) contract: why frames must be pure

The capture script doesn't play the page. It calls window.SIM.render(t) for t = 0, 1/60, 2/60…, waits for each screenshot, and the review step jumps straight to --still 12.5. So a frame can't depend on the frame before it. Both dots below should follow the same path. One is computed as x = f(t); the other accumulates x += v·dt like a typical game loop. Try seeking.

B3An exact solver instead of animation: the Strandbeest leg

From strandbeest-shared/jansen.js: Theo Jansen's 11 “holy numbers” plus a 15-unit crank. Each joint is where two circles intersect: it sits at a known distance from two joints already solved. Five intersections solve the whole leg for any crank angle. There's no inverse kinematics, physics or keyframing. Turn the crank and choose a joint to see its two circles.

// the two points at distance r0 from p0 and r1 from p1; pick chooses one
const cc = (p0, r0, p1, r1, pick) => { … };
export function solveLeg(th) {
  const A = [m * Math.cos(th), m * Math.sin(th)];   // crank pin
  const B = cc(A, j, PIVOT, b, hiY);
  const C = cc(A, k, PIVOT, c, loY);
  const D = cc(B, e, PIVOT, d, loX);
  const E = cc(D, f, C, g, loX);
  const F = cc(E, h, C, i, loY);                    // the foot
  return {O: [0, 0], P: PIVOT, A, B, C, D, E, F};
}

B4Auto-tour ↔ visitor handoff

From live.js. Left alone, the live page plays the film's own SCRIPT as a tour, with a fake cursor that presses the real buttons. Any click, drag, wheel or key calls takeOver(). After 25 s with no input, startTour() runs again (6 s in this demo). The camera never jumps: each frame it eases toward its target with k = 1 − e^(−dt/τ), using τ = 0.18 s on tour and 0.45 s when the visitor drives. Click the buttons, or drag the viewport.

B5The film is a script of operator moves

v8-shared/film.js doesn't use keyframes. Its SCRIPT is nine moves an operator would make: switch the camera, track a cylinder, open the throttle. Each view is a function of the seconds since it started, and moving between views blends every camera parameter with a 1.6 s smootherstep. The RPM ramp changes how fast the crank turns, and the score places a thud on every firing (one every 90° of crank), so the beat speeds up when the throttle opens. Drag the playhead.

export const SCRIPT = [
  {t: 0, cam: 'open'},   {t: 3.5, cam: 'cyl'},  {t: 6.9, track: 6},
  {t: 9.7, cam: 'valley'}, {t: 12.1, rpm: [700, 2400, 1.4]},
  {t: 14.7, cam: 'side'}, {t: 17.3, cam: 'front'}, {t: 19.9, cam: 'hero'}, {t: 22.5, track: 1},
];

C1What happens in one frame: the post-processing pipeline

The V8 stage (v8-shared/stage.js) doesn't draw straight to the screen. An EffectComposer passes the image through several full-screen passes, each reading the previous pass's texture. Click a pass.

C2Cutaways: clipping planes and stencil caps (live three.js)

Rule 4: "The part doing the work opens up." The V8 has three cutaway modes: glass (see-through liners), section (everything past a plane through the tracked cylinder is removed) and solid. A clipping plane makes the GPU throw away every fragment on one side, which leaves the cut parts hollow because there's no geometry on the cut face. The fix is a stencil cap. Toggle caps off in section mode to see the hollow shells. Drag to orbit.

C3Lighting a studio: softboxes, reflections, shadows

Glossy parts get their look from what they reflect. stage.js builds a tiny scene of glowing rectangles (a 12×12 top box, two tall side strips and a low front strip), and PMREMGenerator bakes it into a pre-filtered environment map: one mip level per roughness. Each pixel below is computed from the same layout. Compare full with plain, and try the skill's rule "roughness ≥ 0.45 and envMapIntensity ≈ 0.5 on big surfaces".

C4Easing, with numbers

SKILL.md's "Taste, with numbers" gives the agent exact curves instead of words like "smooth": entrances cubic-bezier(0.16, 1, 0.3, 1), exits cubic-bezier(0.6, 0, 0.9, 0.35) at half the entrance's length, state to state cubic-bezier(0.65, 0, 0.35, 1), and linear only for continuous motion. The film code itself uses smootherstep (6u⁵ − 15u⁴ + 10u³), which has zero velocity and zero acceleration at both ends, so camera blends never jerk.

C5Performance: frame budgets, quality tiers, shader warm-up

At 60 fps a frame has 16.7 ms. live.js watches its own frame time. After a 0.6 s settle, it averages over windows of at least 0.5 s and 6 frames. If the average is over 22 ms (below about 45 fps), the window counts as slow, and one slow window (two after the first 6 s) drops a quality tier. The tier never goes back up. Drag the GPU slider to simulate a laptop's integrated GPU.

C6The overlay: a fixed canvas, scaled, with leaders into 3D

The UI around the machine (console.js) is plain DOM and SVG laid out at a fixed 1600 × 900 CSS px. live.js scales the whole #app with one CSS transform, scale = min(innerWidth/1600, innerHeight/900), so the layout never reflows and the film and the page look identical. Callout leaders connect a fixed label to a moving 3D point. Every frame, the point is projected to screen pixels (stage.project()), and the SVG line is redrawn to that spot.

// stage.js: world point → CSS px. Returns null when the point is behind the camera.
const project = (x, y, z) => {
  pv.set(x, y, z).project(camera);          // → normalised device coords, −1..1
  if (pv.z > 1) return null;
  return [(pv.x * 0.5 + 0.5) * size.w, (-pv.y * 0.5 + 0.5) * size.h];   // y flips: NDC up, CSS down
};

C7Sound from the same model

v8-shared/score.py runs the crank model again in Python. It integrates the same RPM curve at the same 1/20 playback and places a soft 62 Hz thud on every power stroke, plus a click on every button press and a rush of air under the throttle drag. The sfx/ engine is pure Python with no dependencies. It synthesises at 48 kHz, measures loudness with ITU-R BS.1770 (K-weighting, gating) and masters to −14 LUFS, the level streaming platforms normalise to, with a true peak ≤ −2 dBFS so AAC encoding won't clip. Press play to hear the thud-and-click layer (no autoplay). The thud is pitched up here so laptop speakers can play it.

C8The three.js traps the examples already hit

SKILL.md ends its technical section with bugs the author ran into. It costs only a few lines and saves the agent hours. Here's why each one happens.

→Steal this structure for your own complex skill

teardown's shape, generalised. It fits any skill where the output is an artifact whose quality the agent has to check: reports, slide decks, data pipelines, UI, video.

my-skill/
├─ SKILL.md            # trigger description + playbook
│                      #   first run · examples table · file roles
│                      #   numbered rules · contracts · commands
│                      #   review loop + checklist + stop rule
│                      #   known traps · taste as numbers
├─ paths.mjs           # every binary / dir, env-overridable
├─ tools/
│  ├─ build.*          # deterministic: source → artifact
│  ├─ render.*         # artifact → something the model can SEE
│  └─ check.*          # contracts enforced by code, not prose
├─ kit/                # shared runtime the examples import
└─ examples/
   ├─ a-simple/        # 2–3 complete, *diverse* worked examples
   ├─ b-medium/        #   the agent copies the closest one
   └─ c-hard/