teach turns the folder you're in into a teaching workspace: a place where an agent teaches you one topic over several sessions. Its Skill file calls this "a stateful request". The state of your learning lives in files in that folder, so each new session picks up where the last one stopped.
The agent grounds everything in your mission: the real reason you want to learn. It gathers trusted sources first, then gives you short lessons with quick practice. It aims for long-term memory, not the feeling of knowing something today: it uses recall from memory, practice spread over time, and mixed-up practice.
When to use it
Use it when you want to learn a skill or concept properly, over many sessions, not just get one answer. For example: how SQL migrations really work, so you stop copying commands into your FastAPI backend, or how Docker networking works before you deploy.
You start it by typing /teach. It's user-invoked (disable-model-invocation: true), so the agent never starts it on its own.
When not to use it
You want one question answered, with sources, while you keep working: use research. It reads primary sources in the background and leaves one cited Markdown file in the repo. teach also collects trusted sources, but to build lessons over many sessions.
The agent just said something you didn't follow: use wait-what to have that one message explained again in plain words.
What it needs to start
A folder to work in. Workspace paths like ./lessons/ start from the folder you ran /teach in, so give each topic its own folder.
A mission. If you're unclear about it, or MISSION.md is empty, the agent's first job is to ask you why you want to learn this.
What it creates
All of it in the current folder:
MISSION.md: why you're learning, as a concrete goal.
RESOURCES.md: the trusted sources, split into Knowledge and Wisdom (communities to join).
lessons/0001-<name>.html: short, self-contained HTML lessons, each teaching one tightly-scoped thing tied to the mission.
reference/*.html: cheat sheets and glossaries for quick look-up later.
learning-records/0001-<name>.md: short notes of what you've shown you really understand. They work like ADRs (Architecture Decision Records: short notes of a decision and why it was made).
assets/: reusable pieces shared by lessons, such as one stylesheet.
NOTES.md: your preferences about how you like to be taught.
It creates no Issues, branches or pull requests.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt has taught for ten years: six as a voice coach, then four teaching developers. In his video of 2026-06-08 he says he wanted to "take everything I know about teaching and put it inside a skill so that anyone could learn anything".
His first idea was a stateless Skill: you name a topic, it finds a few sources and hands back one lesson. He dropped it. In his words, "all the good teaching that I do is stateful": a teacher remembers "where you've got to", what you've learned and what comes next. So teach had to save its state to files.
He compares it with two Skills in this Course. grill-me is "totally stateless", while grill-with-docs saves ADRs and Glossaries to the repo. Neither is better, he says; they're "useful in different situations".
Matt's page on the Skill (updated 2026-08-24) gives the second reason. It "treats parametric knowledge as untrusted". Parametric knowledge is what the model already knows. So teach finds high-trust sources first and cites them inside every lesson, rather than teaching from memory.
How it works underneath
teach's SKILL.md uses two terms from the psychologists Elizabeth and Robert Bjork: storage strength and desirable difficulty. In a 2011 book chapter they split what you know into two strengths. Retrieval strength is how easy something is to recall right now. Storage strength is how deeply it's tied into what you already know. How you perform in the moment shows only retrieval strength. The trap, they write, comes "if learners interpret current retrieval strength as storage strength": they start to prefer the worse ways of studying. teach's SKILL.md calls the in-the-moment kind "Fluency strength".
From snapshot/skills/teach/SKILL.md, line 75: “If the user is unclear about the mission, or the MISSION.md is not populated, your first job should be to question the user on why they want to learn this.”
The Bjorks' cure is "desirable difficulties": varying the conditions of learning, interleaving topics, spacing study out, and "using tests, rather than presentations, as study events". There's a catch. A difficulty only helps if you have the background to meet it. Otherwise "they become undesirable difficulties".
SKILL.md draws its own line. For knowledge, difficulty is the enemy, because it eats the working memory you need to understand. For skills, difficulty is the tool, because effortful recall builds storage strength. So a lesson teaches the knowledge first, then has you practise the skill in a feedback loop, with quizzes and small tasks.
For knowledge
For skills
difficulty is
the enemy
the tool
because
it eats the working memory you need to understand
effortful recall builds storage strength
For knowledge, difficulty is the enemy
The second idea is the zone of proximal development, a teaching idea Matt says he is "obsessed with". It means teaching where the learner is "perfectly challenged but not intimidated". SKILL.md works that zone out from the learning records. That's why they matter: they tell the next lesson where your edge is.
A real example
Matt's video shows his own course: solving a Rubik's Cube. Its MISSION.md said "Matt wants to be able to take a scrambled 3 by 3 Rubik's Cube and solve it unaided at least once." Lesson one was "anatomy, notation and the white cross", with diagrams, short explainers, call-outs and quizzes.
In a later session he typed teach and said he could solve everything except the corner cycle. Because the context was empty, the agent started by checking the state of the workspace. Then it wrote one new lesson for just that algorithm, with an interactive tap-through of the moves. Matt was running Opus 4.8 at medium effort. Since "everything has been saved to the file system", he can clear the context and still pick up where he stopped.
His written guide of the same day runs teach on French. It shows a reference/glossary.html cheat sheet, and lessons with "tap-to-hear audio buttons and instant-feedback quizzes".
A teach lesson on French, open in the browser, with a tap-to-hear audio button beside each phrase. From aihero.dev, 30 October 2026.
Where it goes wrong
Matt's page lists what users reported. It was updated on 2026-08-24, so one item has changed since.
Made-up content. One user learning a 2x2 Rubik's Cube got move sequences that don't solve it. Matt's answer: "teach is not reliable enough to trust unchecked, and no skill built on an LLM is." The sources and citations make a lesson cheap to check. They don't remove the need to check.
It guesses your level. "There is no assessment step." In session one there are no learning records to go on, so lessons can assume things you don't know. State your prior knowledge and your gaps in the first message, and correct the level out loud when a lesson misses. A level check is only a feature request (issue #725).
No review schedule. The lessons are designed around spacing, but "nothing schedules a review". It won't switch from new material to review on its own, so ask when you want review.
The right quiz answer always first. The page called this "still unfixed". One contributor's instruction-level fix still left the right answer in slot A 33 times out of 33 (issue #335). Newer: Matt's PR #1183, merged 2026-10-07, added "Vary which position holds the correct answer across questions." to SKILL.md. The same PR stopped courses landing in ~/.claude/skills. It left out a mechanical shuffle in the quiz widget, calling the prose rule "the smallest fix". So the current SKILL.md asks for varied positions, but nothing enforces it. If answers keep landing in one slot, ask for a shuffling component in assets/.
Thin lessons. Results vary a lot by model, harness and effort. One user got "a single 30-line HTML card" through Copilot CLI with Codex. Change those before rewriting your prompt.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick something you keep copying without understanding, such as the Alembic migrations in api/. Matt's page says to keep teach out of the project you're working in, and a separate repo is best. So next to your practice project, make a yoga-studio-learning repo and run /teach there, giving the mission "write and roll back the bookings table migration without copying commands" and, in the same message, what you already know (Python backends, SQLAlchemy models) and what you don't.
Then check that RESOURCES.md names the Alembic docs, and the next day open a fresh session there and type /teach next lesson for Alembic migrations.
From snapshot/skills/teach/SKILL.md, line 30: “Before the RESOURCES.md is well-populated, your focus should be to find high-quality resources which will help the user acquire knowledge.”
From snapshot/skills/teach/SKILL.md, lines 43–45: “- Using retrieval practice (recall from memory) - Spacing (distributing practice over time) - Interleaving (mixing up different but related topics in practice”
From snapshot/skills/ask-matt/SKILL.md, line 88: “/research: delegate reading legwork to a background agent: it investigates a question against primary sources, then leaves a cited Markdown file in the repo.”
From snapshot/web/aihero.dev/skills-teach.md, line 91: “It treats parametric knowledge as untrusted. Before it teaches, it finds high-trust resources, records them in RESOURCES.md, and cites them inside every lesson.”
From snapshot/web/bjorklab.psych.ucla.edu/wp-content-uploads-sites-13-2016-04-ebjork-rbjork-2011-pdf.md, line 71: “Such desirable difficulties (Bjork, 1994) include varying the conditions of learning, rather than keeping them constant and predictable; interleaving instruction on separate topics, rather than grouping instruction by topic (called blocking); spacing, rather than massing, study sessions on a given topic; and using tests, rather than presentations, as study events.”
From snapshot/web/aihero.dev/skills-teach.md, line 158: “One contributor tested an instruction-level fix for position, and the correct answer still landed in slot A 33 times out of 33 across nine lessons ( #335).”
From snapshot/skills/teach/SKILL.md, line 65: “Lessons are built from reusable components, stored in ./assets/: stylesheets, quiz widgets, simulators, diagram helpers”
