How it works

Planned like an article, checked like software.

The skill gives your agent a page runtime, a guide to writing and to figures, and scripts that drive a real browser. No figure ships until it has been played with.

In brief

A page answers one question. Every figure draws from one shared model, so a side view and a 3D view always agree. The agent writes the page a few sections at a time, then two scripts load it in headless Chrome: one runs the page's own self-check at desktop and phone widths, the other moves every control and turns every view into contact sheets the agent reads. What looks wrong is traced to its layer and fixed at the cause.

1Ideas

What makes a good interactive article.

Four rules the skill holds every page to, borrowed from the best long-form explorable explanations.

One idea per figure

Each figure teaches one thing, discovered by moving something. About one figure for every 130 to 180 words of text.

Prose and figures take turns

A sentence says what to try and ends with a colon. The figure lets the reader try it. The next paragraph names what they saw.

Neutral objects, colored subjects

Everything is drawn in a calm neutral. Only the parts under discussion get color, and the same color names them in the text.

Real models

Mechanisms are modeled and actually move, cut open, explode, and turn. Physics and geometry are computed from real numbers, not faked.

2Pipeline

From a question to a checked page.

Eight steps, in order. The long ones repeat: a page is built in passes and checked after each.

Frame the topic
Pin down the question the page answers, not just its subject: “what happens when the jaw locks”, not “the TMJ”. Pick a category, narrow a huge topic, and say what was left out.
SKILL.md, step 1
Study, then plan
Get the facts first: dimensions, ranges, mechanisms, names. Then a short plan: one shared model every figure draws from, and for each figure what is on screen, what the reader moves, and what they should notice.
references/craft.md, figures.md, writing.md
Scaffold
Copy the template, which carries the fonts, the theme, and the whole runtime, and leave an empty article to fill.
scripts/new-page.mjs
Build in passes
Prose and figure together, two or three sections at a time. A sentence says what to try and ends with a colon; the figure lets the reader try it; the next paragraph names what they saw.
scripts/put-article.mjs
Render
Mermaid diagrams and code turn into static SVG and HTML inside the page, so it still makes no network requests.
scripts/render.mjs
Verify
Headless Chrome at desktop and phone widths runs the page's own self-check and records errors, blank figures, dead controls, and more.
scripts/verify.mjs
Explore
Every slider is swept, every toggle flipped, every preset pressed, every view turned to four sides, and animations stepped, into one contact sheet per figure.
scripts/explore.mjs
Fix, then report
Each fault is traced to its layer and fixed at the cause. The report lists the file, one line per figure, the checks, and what was simplified.
references/fixing.md

The plan comes first

Before any figure is drawn, the agent writes the plan in the conversation: the question, the shared model, and one line per figure. A plan that lands far below the target figure count usually has paragraphs doing a figure's job.

plan

Question: What happens in the jaw joint when it locks?
Shared model: condyle and disc geometry, a two-phase opening (turn, then slide)
1. The hinge that slides: the condyle turns, then rides forward
   Figure (2D cross-section): drag the chin open / the condyle leaves its socket after 20 mm
2. The disc: a cushion that travels with the condyle
   Figure (3D): turn the joint, cut it open / the disc stays on top of the condyle
...
Colors: condyle = green, disc = blue, eminence = orange

3Spec

A figure is a small spec.

Controls, state, a step function for anything that moves, and a draw function. Colors are asked for by name, so a figure follows light and dark mode and matches the words in the text.

Controls that fit the quantity: sliders with marks, knobs, steppers, XY pads, switches, presets
Dragging with grab handles, hover readouts, and keyboard control
Prose that drives figures: numbers the reader drags, “try this” links, colored terms that light their part
3D views that turn, zoom, cut open, and explode
A self-check built in, which the scripts run

pendulum.js

demo("swing", {
  controls: [{ key: "L", label: "Length", min: 0.2, max: 2, value: 1, unit: "m" }],
  state: () => ({ th: 0.5, w: 0 }),
  step(dt, s, v) {
    s.w -= (9.81 / v.L) * Math.sin(s.th) * dt;
    s.th += s.w * dt;
  },
  draw(g, s, v) {
    const P = [g.w / 2 + 160 * v.L * Math.sin(s.th), 30 + 160 * v.L * Math.cos(s.th)];
    g.line([g.w / 2, 30], P, { stroke: "muted" });
    g.circle(P, 14, { fill: "blue" });
  },
});

4Checks

What gets checked, every time.

Both scripts need only Node 22 and Chrome, Chromium, or Edge. Without them, add ?check to a page's address for the same self-check in a panel.

`verify.mjs`: the page's own self-check

Script errors and exceptions in any figure
Blank figures that never drew
Dead controls: sliders and presets that change nothing
Still animations and views that don't turn or zoom
Loose prose: numbers and links not tied to a figure
Citations with no reference, TeX errors, leftover placeholders
Layout: sideways scroll on a phone
External requests: a page should stand alone
Words per figure, warned outside 80 to 180

It also saves screenshots of every figure in light, dark, and on a phone, for a visual pass.

`explore.mjs`: plays with every figure

Sweeps each slider across its range
Flips every toggle and presses every button and preset
Turns each 3D view to four sides
Steps animations forward in time
One contact sheet per figure, which the agent reads against the sentence before it

The question for each sheet: would a reader doing what the sentence says see what the next paragraph claims, at the values it claims?

5Fixing

Fix the cause, not the symptom.

Every fault is reproduced, traced to one of four layers, fixed there, and checked again.

Layer	What goes wrong	The fix
The model	Wrong numbers, wrong motion, an effect too small to see.	A locked joint barely deflects the jaw: fix the kinematics, don't nudge the drawing.
The figure code	Layout, clipping, framing, labels, colors.	Labels collide: change what's labeled and where it's anchored, don't shrink the text.
The prose	A claim the figure or the facts don't support.	A sentence overclaims: change the sentence or the figure so they agree.
The runtime or engine	A rendering bug that would hit any page.	Fixed in the shared code, so every page gets it.

6Runtime

What a page is made of.

A page is one HTML file with its fonts and runtime inside, and it opens from disk. On this site the runtime is split into kits, and a page downloads only the kits its figures use, so a math page never loads the 3D engine.

Kit	What it does	Loaded for
`base`	TeX to MathML, plots, numerics	every page
`runtime`	figures, controls, dragging, the self-check, article furniture	every page
`engine3d`	WebGL 3D: materials, shadows, particles, smoke, plumes	3D figures
`parts3d`	machine parts and assemblies	machines
`sim`	physics, waves, diffusion, N-body, small neural nets	simulations
`geo`	maps, globes, projections, routes	anything on Earth
`optics`	rays, lenses, prisms, the eye	light
`sound`	tones, harmonics, spectra	sound
`image`	pixels, filters, sampling, the DCT	images
`effects`	fire, smoke, airflow, ripples, glow	effects
`iso`	isometric technical illustration, SVG export	drawings

Use it →See what it makes

What makes a good interactive article.

One idea per figure

Prose and figures take turns

Neutral objects, colored subjects

Real models

From a question to a checked page.

Frame the topic

Study, then plan

Scaffold

Build in passes

Render

Verify

Explore

Fix, then report