teach 精读：把当前目录当成一间有状态的自习室

（本文读的是 mattpocock/skills 快照 5beb35b，2026-10-19。引用原文都能按文中路径回仓库核对。这是「逐个技能精读」系列的第二十五篇，聚焦 teach 一个技能。）

它怎么工作：把目录变成教学状态，一次产出一节 HTML 课

skills/productivity/teach/SKILL.md 开篇第一句就把自己和整套技能里其他成员区分开：

The user has asked you to teach them something. This is a stateful request - they intend to learn the topic over multiple sessions.

stateful 是关键词。它是 disable-model-invocation: true（user-invoked，只有人敲 /teach 才会起），还带一句 argument-hint: "What would you like to learn about?"——它是一个你要主动打开的教室，不是后台代理会自己触发的流程。

它做的第一件事是征用当前目录：

Treat the current directory as a teaching workspace. Workspace paths (./lessons/ and the rest) resolve from the directory /teach was run in; only the *-FORMAT.md links resolve from this skill’s folder.

这句括号值得单拎出来：工作区路径从「你在哪个目录敲的 /teach」算起，只有格式文档的链接从技能自己的目录算起。技能于是明确分成两层——一层是随人走的「课程」，一层是随技能走的「规范」。

状态落成七个文件：MISSION.md（为什么要学，所有教学决策的锚点）、RESOURCES.md（可信来源清单，含社区）、./learning-records/*.md（真正学会了什么）、./lessons/*.html（课）、./reference/*.html（速查材料）、./assets/*（可复用组件）、NOTES.md（用户的教学偏好）。

主产物是课：

A lesson is a single, self-contained HTML output that teaches one tightly-scoped thing tied to the mission. This is the primary unit of teaching in this workspace.

每条课的规格都写在正文里：要漂亮（Think Tufte）、要短（「Learners’ working memory is very small」）、要直接挂在 mission 上、要落在最近发展区里、要能一键打开给人看、要链到别的课和参考文档、要推荐一条一手来源、还要在结尾提醒用户「随时可以问 agent 追问」。而可复用的样式、小测验、示意图要沉淀进 ./assets/：Reuse is the default, not the exception.

一次真实运行长这样：你敲 /teach，说想搞懂 Rust 的 trait。它先看 MISSION.md——没建，于是先不讲课，回过头问你「为什么学、学会了要能干什么」，因为：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. 有了 mission，它去攒 RESOURCES.md（因为：Never trust your parametric knowledge.），再算你的最近发展区（读 learning-records/），最后落一节 ./lessons/0001-*.html 并打开它。

它和「一般技能」的差别：技能不持有状态，目录持有状态

整套技能里绝大多数成员是无状态的：读一次仓库，产出一样东西，结束。research 落一个带引用的文件，handoff 把对话压成一份交接文档，都只跑一次。teach 反过来——技能文件本身很薄、几乎不含内容，真正的重量分散在一组文件约定里，每份约定又各自有一个 *-FORMAT.md。技能是压在目录上的一套协议，而不是一张一次性 prompt。

第二处差别是它对模型自身知识的不信任。多数技能默认模型有足够的判断力，直接开干；teach 的第一步却是去外面把「高可信来源」收进 RESOURCES.md，把「知道什么」外包给文献和社区，只把「怎么教」留在自己手里。

第三处是它与近邻的分工，用产物写给谁、活多久一划就清楚：

• research 产出一个短命事实文件（某库这周的鉴权长什么样），写完不一定再读；
• handoff 把对话压成一份文档，写进 $TMPDIR，给下一个 agent 用，用完即弃；
• teach 把状态写进工作目录，给未来的你和未来许多次会话用，越攒越厚。

同样是「落一个 Markdown / HTML 文件」，一个进临时目录、一个进工作目录，就是交接与教学的分界线。

它有意识摒弃了什么

一、摒弃了「覆盖即学习」。 LEARNING-RECORD-FORMAT.md 把这条写得很硬：Coverage is not learning. Wait for evidence. 还有一句——Session-by-session activity logs. Learning records are not a journal: they are decision-grade insights. 学习记录是「决策级洞察」，不是流水账。

二、摒弃了题库里的格式线索。 For quizzes, each answer should be exactly the same number of words (and characters, if possible). Vary which position holds the correct answer across questions. Don't give the user any clues about the answer through formatting or order. 把一个反作弊细节写进规范——练习要逼出真实的回忆，不能靠字数或位置蒙。

三、摒弃了「讲完就算学会」。 它把知识和技能分开：知识阶段「难度是敌人」（difficulty is the enemy），技能阶段「难度是工具」（difficulty is the tool），技能必须落在一个尽可能紧的反馈环里。

四、摒弃了让模型凭记忆作答。 课要 littered with citations，每条断言都能追到来源。

五、摒弃了含糊的 mission。 MISSION-FORMAT.md：一个工作区只装一个 mission、要具体（「跑完半马」胜过「变健康」）、要短（超过一屏就不再是指南针而是计划）、模糊就先追问。

六、摒弃了「学习是线性的」这一假设。 mission 可以变；学习记录被推翻时，标 superseded by LR-NNNN 而不是删掉——理解如何演变的痕迹本身就是信号。

七、摒弃了「必须加入社区」的强推。 智慧来自社区，但 If the user expresses a preference that they don't want to join a community, respect it.

八、摒弃了预建空目录。 learning-records/「Create the directory lazily: only when the first record is written.」

原文证据

状态化的定义与路径解析：

This is a stateful request - they intend to learn the topic over multiple sessions.

Workspace paths (./lessons/ and the rest) resolve from the directory /teach was run in; only the *-FORMAT.md links resolve from this skill’s folder.

课的规格与「短」的理由：

A lesson should be beautiful, with clean, readable typography and layout, since the user will return to these later to review. Think Tufte.

The lesson should be short, and completable very quickly. Learners’ working memory is very small, and we need to stay within it.

不信任模型记忆：

Before the RESOURCES.md is well-populated, your focus should be to find high-quality resources which will help the user acquire knowledge. Never trust your parametric knowledge.

知识和技能的两种难度：

For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.

If knowledge is all about acquisition, skills are about durability and flexibility. Make the knowledge stick.

组件优先与速查优先：

Reuse is the default, not the exception.

Lessons will rarely be revisited later - reference documents will be.

可迁移结论

1. 把跨会话的状态写成一组文件，每份文件配一个格式文档。 MISSION.md / RESOURCES.md / learning-records/ / lessons/ / reference/ / assets/ / NOTES.md，七个文件各有一个 *-FORMAT.md；格式和内容分开，改格式不动正文。
2. 区分「易逝状态」和「持久状态」。 一次交接写临时目录，长期进度写工作目录。产物的位置本身就是设计。
3. 让技能做协议，而不是装内容。 正文只规定产什么、放哪、怎样才算完成；具体知识现攒现用。
4. 明确写下「不要相信你自己的记忆」。 先攒可信来源，再讲。这一步在多数技能里被默认跳过。
5. 把「学会」定义成证据，而不是覆盖。 没证据就不写记录。
6. 给练习设计反线索。 答案等长、正答位置打散——把蒙的捷径堵死。
7. 一次只用工作记忆装得下的量。 课要短、要快、要给一个能站上去的具体抓手。
8. 记录要能被修订，而不是被删除。 用 supersede 保留「理解是如何变化的」。

teach 把「学习」做成了一个有状态的应用，而不是一次性的回答。它和 handoff 是这套技能里对「状态」的两种极端态度：handoff 只求交接得干净，teach 只求积累得下来；一个写临时目录，一个写工作目录。它也把 research 的能力收编成原料——research 找的是「一条能走回源头的事实」，teach 用的正是这种材料去搭课。