Teachable figures

English · 简体中文 · Live demos →

Turn a lesson's claim into an experiment a learner can operate. Predict a result, change a cause, read the effect, and explain a new case.

This is an agent skill, with rendering examples and verification tools. It works with a host application's lesson schema or a standalone HTML figure.

Quick install

Claude Code (available in every project):

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

For one project only, clone into that project's .claude/skills/teachable-figures. Restart Claude Code, then type /teachable-figures or simply describe a teaching task.

Codex:

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

Invoke it with $teachable-figures in a prompt.

Other agents or manual install: download the repository ZIP or the .skill file (a ZIP archive) from the latest release and extract it into the agent's skill directory. If the agent has no skill directory, ask it to read SKILL.md first.

For a Git installation, update with git pull in the install directory. For a ZIP or .skill installation, download the newer archive and replace the installed skill folder; preserve any local customizations first.

Two ways to use it

Guided mode (default). If your project has a learner workspace (see below), the skill reads it first and skips questions it already answers. It then asks one round of at most five questions, each with a recommended answer you can accept with "ok":

• the audience (a teacher or parent presenting, or a self-learner) and who the learner is;
• the claim and misconception;
• standalone HTML or an existing app;
• schematic, detailed or 3D fidelity;
• the planned controls.

For a self-learner it adds 2–4 short diagnostic questions about prerequisites and likely misconceptions, and can propose a small knowledge-point plan. It builds after you confirm the plan.

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

Direct mode. Say "just build it" or "skip questions", or name the claim, learner, target, and fidelity up front. The skill applies defaults (a self-learner build unless the workspace says otherwise) and lists every assumption, including assumed prior knowledge, in its delivery note.

/teachable-figures Just build it. Explain why adding an idler gear does not
change the final speed-ratio magnitude. Misconception: every extra gear makes
the output slower. Standalone HTML with prediction, one-turn counters, native
controls, reset, and an explanation prompt.

In Codex, write $teachable-figures instead of /teachable-figures.

What it is for, and what it is not for

Good fit	Poor fit
A mechanism the learner can change and observe: gear ratios, attention masks, cross-section areas	Data charts, dashboards, or report figures with nothing to predict
Structures that need cutting, separating, or rotating: a rocket cutaway, chest organs, garment pleats	Slide decks, posters, infographics, or static illustrations
One claim from a text, one figure per mechanism	A whole course in one request; pick the mechanisms worth a figure first
A teaching model with stated assumptions	Clinical anatomy, engineering simulation, CAD, or physics-engine accuracy; reconstruction presented as historical fact

A generated figure is a teaching design. It has not been evaluated with learners.

Learning, not teaching

The skill builds learning exercises and illustrations. Teaching, meaning presenting or lecturing an explanation, stays with the teacher, parent or text. The figure supports what the learner does: predict, operate a cause, notice the effect, and explain it.

Audience changes the build.

	Teacher or parent (presenter)	Self-learner
Who scaffolds	You, live: voiceover, questions, pointing	The artifact
Default build	Large figure, little text, a class prediction prompt, a focus guide you toggle, ordered highlights to step through while talking	Prior-knowledge probe, misconception-specific feedback, independent practice with supports removed, transfer

Ask for a teach layer only if you want the figure itself to explain: an ordered look sequence ("look here → you see this; then there → …") tied to what the learner already knows.

Learner workspace. Three Markdown files in a teachable-figures/ folder in your project form a local lookup that any coding agent reads before each lesson and updates after it:

• LESSONS.md: every lesson made.
• LEARNER.md: a learner or class profile, with prior knowledge and observed misconceptions, each with its evidence.
• LEARNING-PLAN.md: knowledge points, prerequisites and status.

Start from the templates and paste the agent snippet into AGENTS.md or CLAUDE.md. A filled sample shows a self-learner after three lessons. The files hold no names or raw audio, and you can edit or delete anything. See learner workspace.

Learning-science grounding. Every spec answers a checklist covering:

• schema: the existing schema and the change it targets;
• scaffolding and fading;
• cognitive load: one variable first, segmented steps, nothing at the predict stage that gives the answer away;
• attention and signaling: a focus guide per step and ordered highlights;
• dual coding: terms, legends and figure parts linked on hover and focus;
• misconception-targeted feedback.

This is the beginning of the README. Read the rest at the original. Read the full README ↗