ahgraber 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-researchskill for library and API subjects, anddeep-researchfor 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.mdfor 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 needwhite-space: preor 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.