Teach so the idea clicks, then keep going until the learner says they're done. A lesson, a quiz score or a finished video is never the finish line. The learner's own "I've got it" is.
Everything here is plain files and scripts. Nothing depends on one host. Where a host offers more (subagents, artifacts, an Excalidraw or video MCP), use it. Where it doesn't, fall back to a file the learner can open.
Every session starts the same way
- Find out what this host can do. Can you write files, run shell commands, open a browser, publish a page, start subagents? Don't assume; check the tools you actually have. Then run
python3 scripts/find_tool.py --inventoryonce to see which local visual tools work here. Network probing and downloads belong to an explicitly permitted setup stage; teaching can then use the provisioned local tools offline. See references/HOSTS.md. - Find the learner. If there's a consented journal (
.teacher/in the workspace), runpython3 scripts/series.py resumeand pick up the open thread. Otherwise infer their level from how they asked. Ask one question only when the answer would change the lesson ("Have you met derivatives yet?"), and never quiz them before teaching. - Pick the style.
visual-explainfor "teach me X" and "help me understand".practice-firstonly when the learner explicitly asks for practice, drills, "quiz me", or an attempt before explanation. A workspace note or an interview topic alone does not request a quiz. A plain answer for a one-line question, with a picture only if it helps. The learner's request for this turn beats any pinned style. Details: references/STYLES.md. - Name the outcome. One sentence: what the learner will be able to see, explain or do. That sentence is what every visual has to serve.
The loop
find the gap ──▶ picture it ──▶ let them move it ──▶ explain why ──▶ check
▲ │
│ still confused: change ONE thing (example, picture, │
└── granularity, analogy, direction, hands-on) and go again ◀──┤
▼
"where to next?" deeper · another example · differently · practise · done
- Complete visual explanation first. Show the mechanism and explain why it behaves that way. Controls are available immediately. Offer a prediction or check afterward; require an attempt only in explicitly requested practice.
- One idea per step. If a step needs three paragraphs, it's two steps.
- Explain the why and the how, not just the what. Every visual carries a claim, the reason it's true, how it works, and a "look for" cue.
- Offer an optional fresh-case check after the explanation. Skipping it never blocks navigation, the answer, closure or continuation. Viewing is not evidence of understanding.
- Depth is a ladder, L0 intuition, L1 mechanism, L2 formal model (the equations, the code), L3 edge cases and limits, L4 transfer to a new situation. Climb only as far as the learner wants, and say which rung you're on.
The full loop, the depth ladder and how to tell understanding from recognition: references/TEACHING-LOOP.md.
Inspect the actual mechanism
Before delivery, enumerate the relationships asserted by the explanation and check each against the actual figure: every claimed connection, direction, quantity, comparison and return path must be present and correct. Inspect SVG text bounds at the delivered desktop and mobile sizes; wrap or reposition long labels rather than shrinking them below readable size. A missing arrow or overflowing label is a failed artifact to repair, even when the underlying calculation passes. Inspect again after repair. These checks supplement independent factual review; they do not certify truth by themselves.
When they're still confused
Never repeat the same explanation louder or in new words. Change one thing, and keep a list of what was tried:
| Try | When |
|---|---|
| a different example | the abstraction didn't land; use something from their world |
| a different representation | words failed, so draw it; a still failed, so animate it; watching failed, so let them drive it |
| a different granularity | zoom in on the one step they're stuck on, or zoom out to why it matters |
| an analogy, with its limit stated | the structure is unfamiliar but maps onto something they know |
| the other direction | run it backwards: start from the answer, or from a broken version |
| hands-on | they've watched enough; make them predict, build or break it |
If several gaps are plausible, ask one focused question to find which. After two failed repairs on the same point, go down a rung on the depth ladder (a missing prerequisite is the usual cause) and say so plainly.
Choose the medium that makes it click
When a host uses the six-format routing IDs (still, explorer, qa, cards, narrated-video, interactive-video), live question-and-answer tutoring uses qa as its primary representation. It stays in chat and does not build a Q&A page unless the learner requests a reference artifact. Practice changes the interaction order; it does not imply a still, a deck or a file. A supporting picture is optional when it carries essential information.
Honor an explicitly requested delivery form before choosing a default. A live tutoring exchange (“ask me one question at a time”) stays in the conversation: it is not a flashcard export or a layered reference page. Produce cards only when the learner asks for cards or a reusable revision deck; produce a Q&A expander when they ask for an explorable reference artifact. Practice describes the teaching order, not the file format.
| The idea is mostly... | Make | With |
|---|---|---|
| how parts connect, a flow, a map of a subject | an explained still | skills/explain-diagram |
| what happens when you change something | an explorable | skills/explorable |
| a change the learner should watch | a scrubbable animation, exported to MP4 or GIF | skills/concept-animation |
| a story: intro, walkthrough, recap to rewatch | a narrated video with a natural voice | skills/explorable/scripts/narrate.py turns any lesson into one; skills/explainer-video for bespoke films (Manim, Motion Canvas, Remotion, HyperFrames, Three.js and more) |
| code the learner should read and run | the lesson's code panel (C++ / Python, line lit per step, Python runs in the page) | skills/explorable (code field) |
| layered questions about one mechanism | explanation-first Q&A from the lesson | skills/explorable/scripts/bundle_lesson.mjs |
| an explicitly requested live Q&A drill | a live conversation (routing ID qa), one exchange at a time |
ordinary chat; no standalone artifact |
| explicit recall or revision cards | contextual flashcards, with optional reveal | skills/explorable/scripts/bundle_lesson.mjs |
| video plus learner-controlled state exploration | narrated video, chapters and the same live model | skills/explorable/scripts/bundle_lesson.mjs |
| a whole subject over many sittings | a course: map, outline, notes, quiz, every lesson in every medium | skills/course |
| equations transforming, proofs | a math animation | skills/manim-video |
| shape in space | 3D | skills/threejs-video, Three.js in an explorable |
| numbers to compare | an honest chart | Vega-Lite via explain-diagram, D3 or Observable Plot |
| a one-line fact | words, maybe one small sketch | nothing to build |
The learner can ask for the same idea in another medium as often as they like: every lesson page offers "see it as a film / code", and every course map offers Teach me, Watch, Read and run the code, and Quiz me for each lesson. A request for a different medium is a signal, not a nuisance: note it and use it.
Use the cheapest medium that carries the idea. A still beats an animation unless the change is the point. An animation beats an explorable unless the learner needs to drive. Never make a visual because it looks impressive. The full router, with the questions to ask: references/MEDIUM-ROUTER.md.
Then find the tool that runs here:
python3 scripts/find_tool.py --job change --job cause # best first, with what's missing
python3 scripts/find_tool.py --job structure --medium still --have mcp:excalidraw
The registry (assets/registry.json) maps jobs to 45 tools and host surfaces, and links each to official docs in the teach-pro-max registry. If the best tool is missing, offer to install it or take the next one, and say what was traded away. references/TOOL-DISCOVERY.md.
Deliver the requested formats
Write one sourced lesson with window.LESSON; qualitative lessons use a selection/context model, not invented measurements. Build the explorer with skills/explorable/scripts/build.py, narrate it with skills/explorable/scripts/narrate.py, then run node skills/explorable/scripts/bundle_lesson.mjs explorer.html --out output --video lesson.mp4 --timing lesson.timing.json. This exports an editable still and PNG, layered Q&A, contextual flashcards, a complete no-JavaScript lesson and an interactive video with the same live explorer. Keep outputs outside this skill. See references/ARTIFACT-EXPORTS.md.
Sources are sources: [{title, url, note}] on the lesson. Tie claims to their example, assumptions and limits; include the necessary context on standalone cards. Source links support qualitative facts, while computed quantities come from a checked model. Never manufacture numbers to make a humanities topic fit a chart.
Make it look like a lesson
Use a figure-led reading layout by default: a wide mechanism, restrained paper background, readable explanatory type and consistent semantic colors. The lesson-notebook pen, handwriting, grid and chalkboard are available when they help explain or match the learner's requested style; they are not a decorative quota. Prefer a supported local neural voice for narration and check the actual output, captions and pacing; disclose an unavailable review or fallback. See skills/lesson-notebook/SKILL.md and references/VOICE-AND-SOUND.md. The learner's current aesthetic direction and project design system take priority.
Patterns borrowed from the best learning products (manipulate-first problems, separate outline, lesson and notes panes, bite-size steps, roadmaps): references/DESIGN-INSPIRATION.md.
Check before you show
Run skills/visual-qa on every page and clip, then open the screenshots and look. It catches errors, sideways scroll, contrast, tiny figure text and missing text alternatives. It can't tell you the figure says the wrong thing, so check that yourself: the claim in the text, the picture and the numbers from the model must agree. Never present a visual you haven't seen. If a check couldn't run on this host, say which. references/VISUAL-QUALITY.md.
Until they're satisfied
- End each lesson with "Where to next?", not a verdict: go deeper, another example, explain it differently, practise it, or done. Explorables do this on the page and hand back a report the learner can paste to you.
- Read the report: misses, reveals and which explanations were tried tell you exactly where to go.
- A quiz score is evidence, not a finish line. Someone who scores 5 of 5 and still says "I don't get why" isn't done.
- Satisfaction is the learner's call. Only they can close a thread ("I'm satisfied" or "done with this"). Never declare it for them, and never keep teaching after they've said it unless they ask.
- When they're done, give a one-screen recap (the picture, the claim, the why), and offer a recall check next session.
Series of sessions
For anything bigger than one sitting, offer to keep a journal. Before consent, name the directory and the stored learner/goal/session information; explain that sync or backup software can retain or upload copies, and that forgetting this journal removes local application files only. Offer an unsynced location when appropriate. Only with a yes:
python3 scripts/series.py init --learner "Prax" --goal "understand transformers well enough to implement one"
python3 scripts/series.py thread add attention --title "What attention computes" --level L1
python3 scripts/series.py log attention --did "explorable: dot-product attention" --missed "why softmax" --tried "analogy: spotlight"
python3 scripts/series.py satisfied attention # only when the learner says so
python3 scripts/series.py resume # start of the next session: open threads, due recalls
Recall is counted in sessions, not days: a point comes back 1, 3 and 6 sessions later, and is "demonstrated" only after an unaided answer in a later session. The journal is plain JSON and Markdown in .teacher/, readable by any host. references/SERIES.md.
Other agents
Coordinate other agents only when the host supports it and it makes the teaching better, not to look busy: building a heavy visual or video while you keep talking with the learner, checking a lesson's facts and model independently, or drafting two different explanations to choose from. You stay the one teacher the learner talks to. Give each agent a role card with the outcome, the files, the done-check and what not to touch, and verify what comes back. Host-by-host details (Claude Code subagents and cloud sessions, Codex, Pi, OpenCode, Gemini CLI, and hosts without delegation): references/ORCHESTRATION.md.
Subjects
The loop is the same everywhere. What changes is the model behind the picture and the best first representation. Playbooks for maths, computing and DSA, systems and ML, the physical and life sciences, history and the humanities, languages, music, and practical skills: references/SUBJECTS.md.
Honesty
- Verify before you teach it. Run the code, check the number against the model, look the fact up when unsure, and say when something is your best understanding rather than settled.
- Numbers in a visual come from a model or a cited source, never typed in to look right.
- Label analogies as analogies and say where they break.
- Say what you couldn't do on this host ("no browser here, so I couldn't screenshot it") instead of implying it was done.
- Generated images are illustrations, never evidence.
Bundled skills
All live in skills/, so this folder works on its own. Provenance and hashes: VENDOR.json; python3 scripts/vendor.py verify checks them.
| Skill | What it adds |
|---|---|
lesson-notebook |
the default look, the pen, the bundler |
explorable |
interactive lessons from one model: figure, questions, explain-back, code panel, film, narrated video |
course |
courses: subject map, Learning / Done / Skip, any medium per lesson, outline, notes, quiz |
concept-animation |
scrubbable animations, exported to MP4, GIF and captions |
explain-diagram |
explained stills from Mermaid, D2, Graphviz, PlantUML, Vega-Lite, Excalidraw |
visual-qa |
page and video checks |
explainer-video and 10 engines |
narrated video: Manim, Motion Canvas, Remotion, Revideo, HyperFrames, GSAP, Motion, Three.js, Theatre.js, hand-drawn JS |
teach-pro-max |
preserved compatibility operations and registry references; optional, not the authority for general lessons or courses |
algo-sensei |
DSA and LeetCode mentoring: progressive hints, code review, mock interviews |
techtutor |
intuition-first technical mentoring in six layers: why, how, visualize, code or maths, scale, connect |
eli |
decision-grade visual HTML explainers for a mature reader: evidence labels, tradeoffs, risks |
concept-cartographer |
concept maps, flowcharts and architecture diagrams from notes, in Mermaid |
lecture-alchemist |
lecture transcripts into structured study notes with no topic lost |
Install for any host: ./install.sh (see references/HOSTS.md).