你现在读的这页 HTML，就是 teach 的产物——这个仓库根目录里的
MISSION.md、NOTES.md、RESOURCES.md、
lessons/、reference/、learning-records/、assets/
全部是它定义的教学工作区（teaching workspace）文件。
所以这是整个课程里特殊的一课：元课。别的课教你某个 skill 怎么干活，
这一课教你「正在教你的这套机制」本身是怎么规定的——为什么每课都有检索练习、
为什么 quiz 选项长度要对齐、为什么每个论断都要挂出处、为什么学的东西要落在文件里而不是只留在对话里。
学完这节课，你能说清楚 teach 会写哪些文件、一节课的设计规则有哪些、
它用哪套学习理论决定「下一课教什么」，以及行为不对时该改哪个文件的哪一段。
先回忆 0001 的分层：配置层（setup-matt-pocock-skills，跑一次）、
编排层（你手动启动的完整流程）、纪律层（被反复调用的 model-invoked 基本功）。
teach 属于编排层，但它是编排层里最孤立的一个：ask-matt 的地图把它列在
「Off the main flow entirely」（完全在主流程之外）那一节，
和 grill-me、prototype、research、writing-great-skills 并列。
主流程是「grill → spec → tickets → implement」那条做功能的流水线；
teach 不在那条线上，它不和任何别的 skill 交接产物，docs 的原文是
「shares no workflow with the other productivity skills; it simply owns its workspace directory and lives there」
——它和别的 productivity skill 没有共享的工作流，就是拥有自己的那个工作区目录，住在里面。
它在 bucket（技能分桶）上属于 productivity/（日常非代码工作流工具），
和 handoff、grill-me、writing-great-skills 同桶。
一句话概括它在 22 个 skill 里的角色：它是唯一一个「产物就是学习本身」的 skill。
别的 skill 的副作用落在代码、工单系统（Issue tracker）或临时目录；
teach 的副作用全部落在它自己的教学工作区里，而工作区的内容就是你学到的东西的存档。
MISSION.md 写着「对 22 个已发布 skill 达到作者级理解」、
NOTES.md 记着「课要详实但要说人话」、learning-records/ 存着前序会话的上下文、
每课一份 lessons/NNNN-*.html 配一张 reference/*.html 速查表、
所有课共用 assets/lesson.css 和 assets/quiz.js——
每一处结构都能直接对应到 teach/SKILL.md 里的某一节规定。
学这一课时，你可以随时低头看自己脚下的地板。
地图：0001 系统地图 · 路由规则：ask-matt/SKILL.md 的 「Off the main flow entirely」一节 · 本工作区的任务书：MISSION.md
teach 是 user-invoked（只能人启动）的 skill，证据有两处，成对出现：
SKILL.md 的 frontmatter 里写着 disable-model-invocation: true——
这是 Claude Code 这一侧的开关，意思是模型不能自动加载它；
agents/openai.yaml 里写着
policy.allow_implicit_invocation: false——
这是 Codex 那一侧的配对开关，意思相同。
仓库的 .agents/invocation.md 规定：一个 skill 要么在两个 harness（运行 skill 的宿主环境）
里都是 user-invoked，要么都不是，两个开关必须保持同步。
连带后果是：因为模型碰不到它，它的 description 是写给人看的——
一句给人浏览斜杠命令列表时读的简介（「Teach the user a new skill or concept, within this workspace.」），
不需要像 model-invoked skill 那样塞满触发词。
另外 frontmatter 里有一行 argument-hint: "What would you like to learn about?"，
这是输入 /teach 时给用户的参数提示：后面跟一个你想学的主题。
docs 给了一个非常干净的分界：学习是一个项目时才用它，一次性的澄清别用它。
想学一门语言、一个框架、瑜伽、理论物理，想让多次会话的积累能沉淀下来而不是蒸发掉——
这是 teach 的场景。只是此刻有个概念没搞懂，直接问 agent 就行，
那是一次性解释，不需要工作区。SKILL.md 开篇也点破了同一个判断：
这是一个 stateful request（有状态的请求）——用户打算跨多个会话学这个主题。
所以 /teach 的正确使用姿势是：选一个你愿意长期保留的目录当工作区，
在里面启动它，之后每个学习会话都回到这个目录。
| 情境 | 该用 teach 吗 |
更该去哪 |
|---|---|---|
| 想跨多个会话系统学一门主题，希望每节课和学过的东西都留在文件里 | 该——这正是它存在的理由 | — |
| 此刻有个概念没懂，想让人解释清楚 | 不该——一次性解释不需要状态 | 直接在对话里问 agent |
| 想把一个问题的背景调查外包给后台 agent，产出一份带引用的 Markdown | 不该——那是把阅读体力活委托出去，不是教学 | research |
| 不知道当前场景该走哪条流程 | 不该 | ask-matt |
调用契约：skills/productivity/teach/SKILL.md 的 frontmatter · agents/openai.yaml · .agents/invocation.md · 叙事版「什么时候伸手」：docs/productivity/teach.md
SKILL.md 的「Teaching Workspace」一节规定：把当前目录当作教学工作区，
学习状态由目录里的一组文件承载。这份清单就是 teach 的全部副作用面——
它只会写这些文件，不碰工单系统，不碰代码。
| 文件 / 目录 | 装什么 | 对应的 FORMAT 文件 |
|---|---|---|
MISSION.md |
用户想学这个主题的原因。所有教学决策都要追溯到它，它是整个工作区的地基 | MISSION-FORMAT.md |
RESOURCES.md |
经过筛选的高信任资源清单，教学的知识从这里取，不靠模型自己的记忆 | RESOURCES-FORMAT.md |
lessons/*.html |
编号递增的自包含 HTML 课，0001-短横线命名.html。这是教学的主要单元——知识和技能抵达用户的载体 |
无独立 FORMAT 文件，规则直接写在 SKILL.md 的 Lessons 一节 |
reference/*.html |
课的压缩精华：速查表、算法、语法、瑜伽动作、词汇表。课本身很少被回头翻看，速查表会被反复查 | 无独立 FORMAT 文件，规则在 SKILL.md 的 Reference Documents 一节 |
learning-records/*.md |
学习记录：用户已经学会的东西，地位相当于软件开发里的 ADR（架构决策记录）。用来计算下一课该教什么 | LEARNING-RECORD-FORMAT.md |
assets/* |
跨课复用的组件：样式表、quiz 控件、模拟器、画图助手 | 规则在 SKILL.md 的 Assets 一节 |
NOTES.md |
agent 的随手记：用户的教学偏好、工作笔记。设计新课前要回头读它 | 规则在 SKILL.md 的 NOTES.md 一节 |
清单之外还有一个不在 SKILL.md 正文、但有专属 FORMAT 文件的第八种状态：
GLOSSARY.md——这个工作区的规范语言（canonical language），
所有课、练习、学习记录都必须遵守它的用词。它的规则在 GLOSSARY-FORMAT.md 里。
你现在所在的这个工作区正好演示了这条规则的落地：CONTEXT.md 就扮演着词汇表的角色
（它定义了 Issue tracker / Issue / Decision ticket / Triage role，每个词都带「Avoid」清单和
「Flagged ambiguities」一节，形状和 GLOSSARY-FORMAT 要求的完全一致），
0004、0005 两课也都严格遵守了它的用词。
MISSION.md、RESOURCES.md、
lessons/0001–0021、reference/*.html、learning-records/0001-prior-session-context.md、
assets/lesson.css + assets/quiz.js、NOTES.md，
外加承担词汇表职责的 CONTEXT.md。
想确认「真实的 teach 工作区长什么样」，看你自己正在读的目录就是第一手证据。
SKILL.md 的 Philosophy 一节说，要学到深层水平，用户需要三样东西。
这三个词是整套机制的骨架，后面每一条规则都挂在其中一根骨头上：
| 支柱 | 是什么 | 从哪里来 |
|---|---|---|
| Knowledge（知识） | 关于主题的事实和理解 | 从高质量、高信任的资源里采集，记进 RESOURCES.md，课里每个论断挂引用 |
| Skills（技能） | 把知识用得出来的能力 | 通过 agent 设计的高相关互动课获得，靠带即时反馈的练习打磨 |
| Wisdom（智慧） | 在真实世界里判断何时怎么用技能 | 来自和其他学习者、实践者的真实互动——也就是社区，agent 教不了这个 |
不同主题三根骨头的配比不同：理论物理偏知识，瑜伽偏技能。
但有一条铁律对所有主题成立：Never trust your parametric knowledge
（永不信任模型的参数化记忆——就是模型训练时记进权重里的那些「印象」）。
在 RESOURCES.md 还没攒起来之前，agent 的首要任务是去找高质量资源，而不是凭印象开讲。
这条铁律正是你现在这门课的真实写照：每节课的关键论断都要求链回
SKILL.md 或 sibling 文件，不许凭模型记忆臆造 skill 的行为。
这是 SKILL.md 里最重要的一对学习理论概念，也是「为什么每课结尾都有检索练习」的答案：
坑在于：流利强度会给人虚假的掌握感——刚看完觉得全会了，其实什么都没存住。 存储强度才是真正的目标。要建存储强度，SKILL.md 要求用 desirable difficulty（合意难度：刻意让学习过程费点劲，费劲本身正是存得住的原因）， 具体三招：
| 招数 | 意思 | 在本课程里的落点 |
|---|---|---|
| Retrieval practice（检索练习） | 从记忆里往外掏，而不是把材料再读一遍 | 每课结尾的 quiz 和「合上页面默写」练习；quiz 上方的提示「先别往回翻表，凭记忆答」 |
| Spacing（间隔） | 把练习摊到多个时间点，不挤在一次 | 课程天然跨会话进行；learning-records 让下个会话知道该从哪里继续 |
| Interleaving（交错） | 把不同但相关的主题混着练（仅用于技能练习） | NOTES.md 明确要求「Interleave retrieval across lessons」——比如本课的 quiz 会回考 0001 的分层 |
用这对概念可以重新读懂 SKILL.md 里一句容易滑过去的话： 「Knowledge 的教学里，difficulty is the enemy（难度是敌人）；Skills 的练习里，difficulty is the tool（难度是工具）」。 意思是：教知识时要把认知负担降到最低，省出工作记忆来理解； 练技能时要刻意制造费劲的提取，费劲才存得住。一节课的标准结构——先讲知识、再用反馈循环练技能—— 就是从这一句推出来的。
每节课都必须挂在 mission 上——用户想学这个主题的那个「为什么」。
如果用户说不清 mission，或者 MISSION.md 还是空的，
teach 的第一项工作就是追问用户为什么想学这个，而不是先开课。
SKILL.md 把后果说得很直白：mission 没搞懂，知识就没有现实目标可以挂靠，
课会显得抽象，你也没有任何依据判断下一步该教什么。
本工作区的 MISSION.md 就是一个达标样本：Why 一节写的是
「看见场景就知道走哪条 flow、每个 skill 会改什么、结束后该接哪一步」，是具体结果，不是「想了解 skills」。
Mission 是会变的，而且变化是正常的。规则是：变更时更新 MISSION.md、
补一条 learning record 记下这次变化，并且改之前先跟用户确认。
对应地，MISSION-FORMAT.md 要求这个文件保持在一屏以内——
超过一屏，它就从指南针变成了计划书，不再是 mission。
Zone of proximal development（最近发展区，简称 ZPD）指
「挑战刚好够」的那个区间：太简单学不到东西，太难直接劝退。
每节课都应该让用户感觉被挑战得「刚刚好」。
用户可能直接点题说要学什么；没点题时，agent 计算 ZPD 的依据是：
读 learning-records/ 里的学习记录，结合 mission，挑出最相关、又落在 ZPD 里的那一件事。
所以 learning-records 不是日记，而是选题算法的输入——
本课程的 NOTES.md 里「ZPD notes」一节（记着「用户已经知道 plugin.json 是发布清单，不要再教」）
就是在干这件事。
Lesson 是 teach 产出的主要东西。SKILL.md 的 Lessons 一节给了它一组长相规则，
逐条对照你现在读的这页，会全部命中：
| 规则 | 原文要求 | 为什么 |
|---|---|---|
| 自包含的单个 HTML 文件 | 存进 ./lessons/，命名 0001-短横线命名.html，编号递增 |
一节课教一件范围卡得很死的事，且这件事挂在 mission 上 |
| 要美 | 干净、可读的排版和布局，「Think Tufte」（Tufte 是以信息设计著称的统计学家） | 用户以后会回来复习这些页面，难看就没有然后 |
| 要短，很快能学完 | 学习者的工作记忆很小，课必须装得进它 | 但每课要给一个能积累的具体小胜（a single tangible win） |
| 落在最近发展区里 | 直接挂 mission，挑战刚好够 | 见第 6 节 |
| 尽量帮用户打开 | 跑一条 CLI 命令把课在浏览器里打开 | 少一步 friction（摩擦），多一分真的会读的概率 |
| 互相链接 | 用 HTML 锚点链到其它课和 reference 文档 | 让工作区连成一张网，而不是一堆孤立文件 |
| 推荐一个 primary source | 每课推荐一个你找到的、质量最高、最可信的一手材料，让用户去读或看 | 课是压缩品，一手材料是真相；见本课第 14 节 |
| 提醒用户问问题 | 每课带一条「有不清楚的地方直接问 agent」的提醒 | agent 就是老师，任何不清楚的地方它都能补讲；见本课结尾 |
课是由可复用的组件拼出来的，组件存在 ./assets/：
样式表、quiz 控件、模拟器、画图助手——任何第二节课可能再用到的东西。
SKILL.md 的规定非常硬：
./assets/，
用已有的组件拼。
assets/ 里的组件再 link，
永远不要把将来的课还要复制的代码内联进某一节课里。
本工作区的组件库目前有两件：assets/lesson.css（共享样式表，每节课都 link）
和 assets/quiz.js（检索练习控件：读 data-quiz 标记和每题的
data-answer，点「核对答案」后当场给对错反馈）。
注意 quiz 控件的注释里有一句「Option labels should be equal length (caller responsibility)」——
选项等长这条规则由写课的人负责，控件不管；这条规则本身的出处见下一节。
知识先从可信资源采集，用 RESOURCES.md 记账。
课里要 littered with citations（撒满引用）——任何论断都链到外部资源背书，
提高课的可信度。知识获取阶段「难度是敌人」：任何多余的认知负担都会吃掉理解所需的工作记忆。
你现在这门课把「外部资源」具体化成了仓库内的一手材料，所以每节关键段落下都有
cite 行的出处链接。
技能的教法和知识相反：难度是工具，费劲的提取才建存储强度。 可用的工具有两类：互动课（quiz、轻量的浏览器内小任务）， 和引导用户走一串真实世界步骤的课（比如一串瑜伽动作）。 两类都必须基于 feedback loop（反馈循环：用户做完动作，立刻收到对自己表现的反馈）， 循环越紧越好——最好即时、最好自动。quiz.js 的「核对答案」按钮当场判分，就是这个要求的实现。
三根支柱里，agent 能直接给的只有知识和技能。
Wisdom（智慧）来自真实世界的真互动——在学习环境之外检验技能。
所以当用户的问题看起来需要的是智慧时，agent 的默认姿势是：先尝试回答，
但最终把用户委托给一个社区——论坛、subreddit、线下课（预算允许的话）、本地兴趣小组，
并主动去找声誉好的社区推荐给用户。
有一条明确的边界：如果用户表示不想加入任何社区，尊重这个选择。
RESOURCES-FORMAT.md 还要求把这件事记下来——
用户选择不加入社区这件事本身要写进 RESOURCES.md，
免得以后的会话反复提议同一件事。本工作区的 RESOURCES.md
就有「Wisdom (Communities)」一节，列着 mattpocock/skills 的 GitHub 讨论区和 AI Hero 社区。
teach 目录下除了 SKILL.md 还有四个 sibling，
每个对应一种状态文件的写法细则。它们才是「副作用到底长什么样」的权威：
| FORMAT 文件 | 管哪个状态文件 | 最有信息量的规则 |
|---|---|---|
MISSION-FORMAT.md |
MISSION.md |
一个工作区只能有一个 mission；要具体不要抽象（「十月跑完半马」胜过「变健康」）；用户说不清就先采访，糟糕的 mission 比没有更糟；保持一屏以内 |
RESOURCES-FORMAT.md |
RESOURCES.md | 只收高信任来源，营销包装成教育的一律不收；每条必须带一行注记（讲什么、什么时候用它），裸链接三个月后毫无用处；按 Knowledge / Wisdom 分组；缺的资源要显式写出 Gaps 一节驱动后续搜索；过时资源直接删掉，宁可五条锋利的不要三十条平庸的 |
LEARNING-RECORD-FORMAT.md |
learning-records/*.md |
模板全部内容就是「标题 + 一到三句话」，刻意轻；只在四种时刻写：真学会了非平凡的东西、用户自报先备知识、纠正了一个误解、mission 变了。「讲过了」不算「学会了」，覆盖不等于学习；后来的记录推翻前面的时，把旧的标成 superseded（已被取代）而不是删掉——理解演化的历史本身是信号 |
GLOSSARY-FORMAT.md |
GLOSSARY.md（本工作区由 CONTEXT.md 承担） |
只有用户真懂了才能收进词汇表——它是压缩后的知识记录，不是供学习的词典；要有立场：同义词里挑一个最好的，其余列为避免项；定义要短，说清这个词「是什么」而不是「怎么用」；定义内部优先用词汇表自己的词；歧义要显式标注裁决结果 |
这四个文件就是 teach 的「可拧的螺丝」的主要部分：
你觉得它写的 mission 太虚、resources 太滥、learning records 太啰嗦、词汇表收词太随意，
改的都是对应的 FORMAT 文件，而不是改某次具体的输出。
| 动作 | 写什么 | 备注 |
|---|---|---|
| 首次启动 / mission 缺失 | 采访用户后写 MISSION.md；开始攒 RESOURCES.md |
mission 空白时这是第一优先级，先于任何课 |
| 每产出一节课 | 新增 lessons/NNNN-slug.html；可能同步新增 reference/*.html；尽量跑 CLI 帮用户打开 |
编号扫现有目录取最大值加一；课之间用锚点互链 |
| 用户展现出真实的学会 / 自报先备 / 纠正误解 / mission 变化 | 新增一条 learning-records/NNNN-slug.md；mission 变化时同步更新 MISSION.md |
触发条件以 LEARNING-RECORD-FORMAT 的四条为准，「讲过了」不写 |
| 用户表达教学偏好 | 追记进 NOTES.md |
本课程的「说人话」规则就是这么进来的 |
| 课需要新组件 | 写进 assets/ 再 link |
第一个组件永远是共享样式表 |
| 任何时候 | 不碰工单系统（Issue tracker）、不碰代码仓库源码、不碰操作系统临时目录 | 它的全部世界就是当前目录这一组教学文件 |
teach 是自成闭环的 standalone（独立工具），它的「下一步」不指向别的 skill，
而是指向下一个学习会话：
ask-matt 是总路由。| 症状 | 该改哪里 | 不要误改 |
|---|---|---|
| 课越写越长、一次塞好几个主题 | teach/SKILL.md 的 Lessons 一节（范围规则：一课一件事、装得进工作记忆） |
assets/lesson.css 的排版——那是长相不是范围 |
| quiz 正确选项总是最长、格式泄题 | SKILL.md 的 Skills 一节（选项等长规则） | assets/quiz.js——控件只管判分，选项长度是写课人的责任 |
| 课凭模型印象开讲、论断没有出处 | SKILL.md 的 Philosophy / Knowledge 两节（永不信任参数化记忆；撒满引用）和 RESOURCES-FORMAT.md 的高信任规则 | 某一课里的个别事实——那是换内容，不是修行为 |
| mission 写成口号、超过一屏 | MISSION-FORMAT.md（具体优先、一屏上限、先采访） |
课的内容——课虚是因为地基虚 |
| learning records 写成流水账日记 | LEARNING-RECORD-FORMAT.md（四种触发时刻；覆盖不等于学习） |
NOTES.md——那是记偏好的，不是记学习成果的 |
| 每节课样式飘、代码在课与课之间复制 | SKILL.md 的 Assets 一节（复用是默认；新组件进 assets/ 再 link） | 单独某一节课的内联样式——治标不治本 |
| AI 从不主动来教 / 想让它主动教 | 不该改——它设计为 user-invoked；真要变，frontmatter 的 disable-model-invocation 和 openai.yaml 的 policy 必须成对改（见 .agents/invocation.md） |
description 的措辞——它是写给人看的简介，不是触发词 |
| 用户偏好没被记住，课的风格反复横跳 | 把偏好记进工作区的 NOTES.md，不是改 skill |
teach/SKILL.md 本身——偏好属于工作区，不属于 skill 定义 |
先别往回翻，凭记忆答。选项长度刻意对齐，不会从版式泄题。答错的题号回到对应小节重读。
learning-records/0001-prior-session-context.md，
用 LEARNING-RECORD-FORMAT 的四条触发条件判断它当初该不该被写——这是一次真实的作者级判断练习。
这是课程的最后一课（0021）。22 个已发布 skill 的主线深课到此走完： 总览（0001）→ 配置（0002）→ 面试（0003）→ 两块词汇地板（0004、0005）→ 跨会话与调研（0006–0008）→ 主流程五连（0009–0013）→ 工单侧三件套（0014–0016）→ 架构与冲突（0017、0018）→ 三个元工具（0019–0021）。
下一步不是新课，而是回到地图。建议的复习路径：
重读 0001 系统地图，
每看到一个 skill 名，合上书先自问那五个作者级问题——怎么启动、典型场景、会写/改什么、
下一步接什么、行为不对改哪里——答不上来的，跳回对应深课的那一节重读，而不是整课重看。
这正是检索练习 + 间隔效应的组合，也是 teach 自己的方法论要求的复习姿势。
各课的 reference/*.html 速查表（包括本课配套的
reference/teach.html）就是为这种「只查一节」的复习设计的。
本课主一手材料（请打开原文读，不要只背本页摘要）：
skills/productivity/teach/SKILL.md
—— 工作区文件清单、三支柱哲学、流利/存储强度、Lessons / Assets / Mission / ZPD / Knowledge / Skills / Wisdom / NOTES.md 各节。
…/MISSION-FORMAT.md
—— mission 的模板与规则（一个工作区一个 mission、具体优先、一屏上限）。
…/RESOURCES-FORMAT.md
—— 资源的筛选、注记、分组、Gaps 与剪枝规则。
…/LEARNING-RECORD-FORMAT.md
—— 学习记录的四种触发时刻、supersede 不删除、覆盖不等于学习。
…/GLOSSARY-FORMAT.md
—— 词汇表的收词门槛与「有立场」的定义规则。
docs/productivity/teach.md
—— 给人看的叙事版（aihero.dev/skills-teach）：
「学习是一个项目时才伸手」。
推荐 primary source： skills/productivity/teach/SKILL.md。 全部规则都从这一份文件长出来，四个 FORMAT 文件是它的附件。
导航： 上一课 0020 writing-great-skills （隔壁的元工具：怎么写好一个 skill）。 路由总图 0019 ask-matt。 复习起点 0001 系统地图。
teach/SKILL.md 和四个 FORMAT 文件的原文，不会临场编造。
课程到这里已收官：回复「复习计划 / 哪里还不牢 / 按 0001 自测一遍」，我们用 teach 自己的方法安排复习。