Teach Me

Turn a subject into a lesson, not a summary. A summary tells the reader what is true; a lesson leaves them able to explain it, apply it, and check themselves. The structure comes from learning science — each design choice names its principle inline, and full citations live in ATTRIBUTION.md.

Invocation Notice

• Tell the user when this skill is running: teach-me. Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match. A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.

Writing Style

Write as a professional technical writer, with the clarity of Martin Kleppmann. Lean toward ASD-STE100: short sentences, active voice, one term per concept. Keep identifiers, commands, and paths exact.

Use industry- or domain-standard terms, and define each on first use. Never coin your own terms. A made-up label reads as standard vocabulary, teaches a word that exists nowhere else, and blocks the reader from finding real sources. If a concept has no standard name, describe it in plain words instead of naming it.

Sizing the Lesson

Decide two axes per invocation:

• State — ephemeral in-chat lesson, or a saved artifact.
• Intensity — how much you build (latency the user waits through) and how much the reader must hold (cognitive load).

A full-intensity lesson has four sections in order: Background, Intuition, Walkthrough, Quiz. Lighter asks deliver a subset: "just help me grok it" is Intuition plus a line of Background.

Default light-first. Deliver the sized lesson, then close with a one-line offer of more depth or a saved artifact. Two overrides:

• When the ask names the heavy thing ("an onboarding doc", "a lesson I can revisit"), build it directly.
• Never run an upfront sizing questionnaire — persistence is a save-at-the-end decision, not an intake question.

Gathering Material

Ground every lesson in real sources; never trust parametric knowledge alone.

• At full intensity, research before teaching: use the mcp-research skill for library and API subjects, and deep-research for anything else beyond your reliable knowledge. Cite what you used.
• A light pass may skip the research hop; say so when confidence is low.
• If the subject lives in the user's local files — a codebase, documents, notes, or data — read the actual files before explaining them.
• If the subject is a specific code change, follow references/code-change.md for resolving and exploring the diff.

Section Guide

Background — activate prior knowledge (advance organizers). Write two layers: a deep layer a novice needs and an expert skips, then a narrow layer specific to the subject at hand. The split exists because extra scaffolding helps novices but hurts experts (expertise-reversal effect). For a lesson on the Reformation, the deep layer covers how the medieval church held authority; the narrow layer covers the indulgence controversy Luther answered. For a code change, the narrow layer is the subsystem the diff lands in.

Intuition — essence first. Open with one concrete toy example, then generalize (concreteness fading). To teach compound interest, follow one $100 deposit through three years before writing the formula; to teach a cache, trace one repeated lookup before defining eviction. Pair the idea with a figure — words plus pictures beat words alone (dual coding).

Walkthrough — the substance itself. Chunk it, and order the chunks purposefully so working memory is never overloaded (cognitive load theory). Build from primitives to composition: intervals before chords before progressions; functions before the pipeline that composes them.

Quiz — retrieval practice (testing effect). Five interactive multiple-choice questions with per-option feedback. Read references/quiz-design.md and apply its rules, including the self-check pass — do not write items from memory. In chat, run the quiz conversationally: pose the questions and end your turn, then give the per-option feedback after the user answers — never print the answers alongside the questions.

Figures

When a figure's point is a shape or structure, use the show-me skill's palette. If it becomes clear mid-lesson that the user only needed to see the shape, give them the visual and stop.

Format Rules

Full contracts for both formats are in references/output-formats.md. Easy to miss:

• No ASCII-art diagrams; embed figures so the file works offline.
• HTML code blocks styled as divs need white-space: pre or the browser collapses newlines.
• The quiz must be interactive in every medium — conversational in chat (ask, wait, then feedback), vanilla JS in HTML, <details> blocks in Markdown.
• Use callouts for key concepts, definitions, and edge cases.

Output

• Light path: the sized lesson in chat, closing with the one-line offer of depth or a saved artifact.
• Deep path: one dated artifact — HTML by default, Markdown on request — saved in the user-chosen directory (default .teach/), with the path returned to the user.

Lesson Series

One invocation teaches one lesson; invoke the skill again for the next. Saved lessons accrete in .teach/ into a curriculum: when the user returns to a subject, read the artifacts already there and build the next lesson on top of them — advance, don't repeat. No syllabus or planning file is needed; the dated lessons are the record.

Related Skills

• show-me — when seeing a shape settles the question; also supplies the figure palette.
• interactive-notebook-demo — when the subject is best understood by running it; an executable walkthrough.
• mcp-research / deep-research — source grounding before teaching.
• code-review — judging a change, not explaining it.
• commit-message — writing the commit message for a change.

References

• references/quiz-design.md — item-writing rules and the pre-save self-check for the quiz.
• references/output-formats.md — the HTML and Markdown artifact contracts.
• references/code-change.md — resolving and exploring a diff when the subject is a code change.
• ATTRIBUTION.md — source prompts and the learning-science citations behind each design choice.