ywEdAi/teachable-figures

What it does

Teachable figures is an agent skill that converts a single lesson claim into an experiment a learner can operate: predict a result, change a cause, read the effect, then explain a new case. The skill writes a teaching spec first — claim, misconception, cause, observable effect, truth model — and then builds either a standalone HTML figure or a figure for a host application's lesson schema teaching spec and renderer choice.

It ships with rendering kits derived from two upstream skills (mechanical/isometric SVG and turning 3D), six reviewed complete lessons, and browser-based verification tools. The bundled "Anatomy" kit is a toolkit for explanatory objects such as cutaways and joints, not a medical atlas.

Good fits are mechanisms the learner can change and observe (gear ratios, attention masks, cross-sections) and structures that need cutting or rotating. Poor fits are data charts, dashboards, slide decks, and anything that is supposed to be a clinical, CAD, or physics-engine-accurate model fit guidance.

Install and first run

In Claude Code, clone into the personal skills directory:

git clone https://github.com/ywEdAi/teachable-figures.git ~/.claude/skills/teachable-figures

For a single project, clone into that project's .claude/skills/teachable-figures instead. Restart Claude Code, then invoke /teachable-figures followed by the teaching task. In Codex, clone into ~/.codex/skills/teachable-figures and invoke with $teachable-figures install steps.

Guided mode, the default, asks at most five questions with a recommended answer each — learner, claim and misconception, standalone HTML or host app, fidelity, and planned controls — and builds after you confirm. You can skip the round with "just build it" and state the claim, learner, target, and fidelity up front; the skill then applies defaults and lists its assumptions in the delivery note usage modes. Example prompt:

/teachable-figures Explain to middle-school students why an idler gear
does not change the speed-ratio magnitude.

To see output before installing, the six live examples run directly in a browser, and the example pages also work offline with native controls, reset, and an explanation prompt. The How it works page is itself a teachable figure about the skill.

Constraints and limits

The skill and the standalone pages have no package runtime dependencies; Node.js is needed only for the Anatomy builders, and Playwright is a development dependency for browser checks. Run npm ci, npm test, and npm run test:browser from the repository; the browser suite expects an installed Google Chrome unless you set BROWSER_CHANNEL=chromium checks.

Generated figures are teaching designs and have not been evaluated with learners; passing model and browser checks does not establish learning effectiveness or screen-reader usability. Upstream Anatomy examples are rendering demonstrations whose automatic tours must be disabled before lesson integration. The six complete lessons do not autoplay limits.

The repository declares no license for its own lesson material, app references, or screenshots. The bundled Anatomy and iso-figure contributions keep their MIT notices, and the chest meshes come from Human Reference Atlas / HuBMAP under CC BY 4.0 sources and licenses.

HotRepo's take

The project appeared on HotRepo's new-project board for JavaScript on 2026-11-01 with 99 stars gained in a window starting 2026-10-31T10:45Z new-board snapshot. No all-language daily rank has been recorded. The sampled star curve over the same period rose from 101 to 200, then flattened in the last few hours. That is a short observation window and says nothing about teaching quality; the README's own statement that the figures have not been tested with learners is the relevant benchmark.