Skill Learning

teach

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 17 处。

入口 skill：teach左右滑动切换语言 · 段落位置自动对齐
The user has asked you to teach them something. This is - they intend to learn the topic over multiple sessions.
## Teaching Workspace
Treat the current directory as a teaching workspace. The state of their learning is captured in this directory in several files:
- `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This should be used to . Use the format in [MISSION-FORMAT.md](./MISSION-FORMAT.md). - `./reference/*.html`: A directory of reference materials. These are the compressed learnings from the lessons - cheat sheets, reference algorithms, syntax, yoga poses, glossaries. They are . They should be beautiful documents which print out well, and are designed for quick reference. - `RESOURCES.md`: A list of resources which can be explored to ground your teaching in contextual knowledge, or to acquire knowledge and wisdom. Use the format in [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md). - `./learning-records/*.md`: A directory of learning records, which capture what the user has learned. These are loosely equivalent to architectural decision records in software development - they capture non-obvious lessons and key insights that may need to be revised later, or drive future sessions. These should be used to calculate the . They are titled `0001-<dash-case-name>.md`, where the number increments each time. Use the format in [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md). - `./lessons/*.html`: A directory of lessons. 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. - `./assets/*`: Reusable **components** shared across lessons. See [Assets](#assets). - `NOTES.md`: A scratchpad for you to jot down user preferences, or working notes.
## Philosophy
To learn at a deep level, the user needs three things:
- **Knowledge**, captured from high-quality, high-trust resources - **Skills**, acquired through highly-relevant interactive lessons devised by you, based on the knowledge - **Wisdom**, which comes from interacting with other learners and practitioners
Before the `RESOURCES.md` is well-populated, your focus should be to find high-quality resources which will help the user acquire knowledge. .
Some topics may require more skills than knowledge. Learning more about theoretical physics might be more knowledge-based. For yoga, more skills-based.
### Fluency vs Storage Strength
You should be careful to split between two types of learning:
- **Fluency strength**: in-the-moment retrieval of knowledge - **Storage strength**: long-term retention of knowledge
Fluency can give the user , but storage strength is the real goal. Try to design lessons which build long-term retention by :
- Using retrieval practice (recall from memory) - Spacing (distributing practice over time) - Interleaving (mixing up different but related topics in practice - for skills practice only)
## Lessons
A lesson is the main thing you produce: the unit in which knowledge and skills reach the user. Each lesson is one self-contained HTML file, saved to `./lessons/` and titled `0001-<dash-case-name>.html` where the number increments each time.
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. But each lesson should give the user that they can build on. It should be directly tied to the mission, and should be in the user's .
If possible, open the lesson file for the user by running a CLI command.
Each lesson should link via HTML anchors to other lessons and reference documents.
Each lesson should recommend a primary source for the user to read or watch. This should be the most high-quality, high-trust resource you found on the topic.
Each lesson should contain a reminder to ask followup questions to the agent. The agent is their teacher, and can assist with anything that's unclear.
## Assets
Lessons are built from reusable **components**, stored in `./assets/`: stylesheets, quiz widgets, simulators, diagram helpers, and anything else a second lesson could reuse.
. Before authoring a lesson, read `./assets/` and build from the components already there. When a lesson needs something new and reusable, write it as a component in `./assets/` and link to it; never inline code a future lesson would duplicate.
A shared stylesheet is the first component every workspace earns: every lesson links it, so the lessons look like one consistent course rather than a pile of one-offs. As the workspace grows, so should the component library.
## The Mission
Every lesson should be tied into the mission - the reason that the user is interested in learning about the topic.
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.
Failing to understand the mission will mean knowledge acquisition is not grounded in real-world goals. Lessons will feel too abstract. You will have no way of judging what the user should do next.
Missions may change as the user develops more skills and knowledge. This is normal - make sure to update the `MISSION.md` and add a learning record to capture the change. Confirm with the user before changing the mission.
##
Each lesson, the user should always feel as if they are being challenged 'just enough'.
The user may specify an exact thing they want to learn. If they don't, figure out their by:
- Reading their `learning-records` - Figuring out the right thing to teach them based on their mission - Teach the most relevant thing that fits in their
## Knowledge
Lessons should be designed around a skill the user is going to learn. The knowledge in the lesson should be only what's required to acquire that skill. You teach the knowledge first, then get the user to practice the skills via an interactive feedback loop.
Knowledge should first be gathered from trusted resources. Use `RESOURCES.md` to keep track of them. Lessons should be - links to external resources to back up any claim made. This increases the trustworthiness of the lesson.
For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.
## Skills
If knowledge is all about acquisition, skills are about durability and flexibility. Make the knowledge stick.
For skill acquisition, difficulty is the tool. is what builds storage strength. Skills should be taught through interactive lessons. There are several tools at your disposal:
- Interactive lessons, using quizzes and light in-browser tasks - Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses)
Each of these should be based on a **feedback loop**, where the user receives feedback on their performance. This feedback loop should be , giving feedback immediately - and ideally automatically.
For quizzes, each answer should be exactly the same number of words (and characters, if possible). Don't give the user any clues about the answer through formatting.
## Acquiring Wisdom
Wisdom comes from true real-world interaction - testing your skills outside the learning environment.
When the user asks a question that appears to require wisdom, your default posture should be to attempt to answer - but to ultimately delegate to a **community**.
A community is a place (online or offline) where the user can test their skills in the real world. This might be a forum, a subreddit, a real-world class (budget permitting) or a local interest group.
You should attempt to find high-reputation communities the user can join. If the user expresses a preference that they don't want to join a community, respect it.
## Reference Documents
While creating lessons, you should also create reference documents. Lessons can reference these documents - they are useful for tracking raw units of knowledge useful across lessons.
Lessons will rarely be revisited later - reference documents will be. They should be , in a format designed for quick reference.
Some learning topics lend themselves to reference:
- Syntax and code snippets for programming - Algorithms and flowcharts for processes - Yoga poses and sequences for yoga - Exercises and routines for fitness - Glossaries for any topic with its own nomenclature
Glossaries, in particular, are an essential reference. Once one is created, it should be adhered to in every lesson.
## `NOTES.md`
The user will sometimes express preferences of how they want to be taught, or things you should keep in mind. This is the place to record those preferences, so you can refer back to them when designing lessons or working with the user.
Source metadata
--- name: teach description: Teach the user a new skill or concept, within this workspace. disable-model-invocation: true argument-hint: "What would you like to learn about?" ---
用户已要求你教授他们某项内容。这是一个有状态的请求——他们打算跨多个 sessions 学习这个主题。
## 教学 Workspace
将当前目录视为教学 workspace。用户的学习状态通过此目录中的若干文件来记录：
- `MISSION.md`：记录用户对该主题感兴趣的_原因_。所有教学都应以此为依据。使用 [MISSION-FORMAT.md](./MISSION-FORMAT.md) 中的格式。 - `./reference/*.html`：参考资料目录。这些资料是从课程中压缩出的学习成果——速查表、参考算法、语法、瑜伽体式、术语表。它们是学习的原始单元。它们应是美观、打印效果良好且便于快速查阅的文档。 - `RESOURCES.md`：可供探索的资源清单，用来让教学建立在情境知识之上，或帮助获取知识与智慧。使用 [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md) 中的格式。 - `./learning-records/*.md`：学习记录目录，用来记录用户已经学会的内容。它们大致相当于软件开发中的架构决策记录——记录非显而易见的经验和关键洞见；这些内容以后可能需要修订，也可能推动未来的 sessions。应使用这些记录来计算最近发展区。文件命名为 `0001-<dash-case-name>.md`，编号每次递增。使用 [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md) 中的格式。 - `./lessons/*.html`：课程目录。一个 **lesson** 是单个、自包含的 HTML 输出，教授一个与 mission 相关且范围严格收敛的内容。这是此 workspace 中教学的主要单元。 - `./assets/*`：跨课程共享的可复用 **components**。参见 [Assets](#assets)。 - `NOTES.md`：供你随手记录用户偏好或工作笔记的草稿本。
## 教学理念
为了实现深层学习，用户需要三样东西：
- **知识（Knowledge）**：从高质量、高可信度的资源中获取 - **技能（Skills）**：基于这些知识，通过你设计的高度相关的互动课程习得 - **智慧（Wisdom）**：来自与其他学习者及实践者的互动
在 `RESOURCES.md` 得到充分充实之前，你的重点应是寻找能帮助用户获取知识的高质量资源。绝不要信任自己的参数化知识。
有些主题对技能的要求可能高于知识。学习理论物理可能更偏知识；瑜伽则更偏技能。
### 流畅强度与存储强度
你应谨慎区分两种学习强度：
- **流畅强度（Fluency strength）**：当下提取知识的能力 - **存储强度（Storage strength）**：长期保留知识的能力
流畅感会给用户一种虚假的掌握感，但存储强度才是真正目标。尝试通过“合意难度”设计能够建立长期记忆的课程：
- 使用提取练习（从记忆中回想） - 间隔练习（把练习分散到不同时间） - 交错练习（在练习中混合不同但相关的主题——仅用于技能练习）
## 课程
lesson 是你产出的主要内容：知识和技能借此抵达用户。每节 lesson 都是一个自包含的 HTML 文件，保存到 `./lessons/`，命名为 `0001-<dash-case-name>.html`，编号每次递增。
lesson 应当**美观**，具有干净、易读的排版和布局，因为用户日后会回来复习。想想 Tufte 的风格。
lesson 应简短，并且能很快完成。学习者的工作记忆容量很小，我们必须控制在其承受范围内。但每节 lesson 都应给用户一个可感知的单一成果，让他们能够在此基础上继续前进。它应直接关联 mission，并处于用户的最近发展区。
如果可行，通过运行 CLI 命令为用户打开 lesson 文件。
每节 lesson 都应通过 HTML anchors 链接到其他 lessons 和 reference documents。
每节 lesson 都应推荐一项供用户阅读或观看的一手资料。它应是你针对该主题找到的质量最高、可信度最高的资源。
每节 lesson 都应提醒用户向 agent 追问。agent 是他们的老师，可以协助解释任何不清楚之处。
## Assets
lessons 由存放在 `./assets/` 中的可复用 **components** 构建：样式表、测验组件、模拟器、图表辅助工具，以及任何可被第二节 lesson 复用的内容。
复用是默认做法，而不是例外。在编写 lesson 前，先读取 `./assets/`，并基于已有 components 构建。lesson 需要新的可复用内容时，把它写成 `./assets/` 中的 component 并链接过去；绝不要内联编写会被未来 lesson 重复使用的代码。
共享样式表是每个 workspace 首先应获得的 component：每节 lesson 都链接它，因此所有 lessons 看起来像一门一致的课程，而不是一堆互不相干的一次性产物。workspace 不断增长时，component library 也应随之增长。
## Mission
每节 lesson 都应与 mission 联系起来——也就是用户对该主题感兴趣的原因。
如果用户不清楚 mission，或 `MISSION.md` 尚未填充，你的首要任务应是询问他们为什么想学习这项内容。
未能理解 mission，就意味着知识获取没有扎根于现实目标。lessons 会显得过于抽象，你也无从判断用户下一步应做什么。
随着用户掌握更多技能和知识，mission 可能发生变化。这很正常——务必更新 `MISSION.md`，并新增一条 learning record 来记录这次变化。更改 mission 前先向用户确认。
## 最近发展区
每节 lesson 都应始终让用户感觉自己受到的挑战“恰到好处”。
用户可能会明确指定想学的具体内容。如果没有，就通过以下方式判断他们的最近发展区：
- 阅读其 `learning-records` - 根据其 mission 判断适合教授的内容 - 教授处于其最近发展区内、相关性最高的内容
## 知识
lessons 应围绕用户将要掌握的一项技能来设计。lesson 中的知识应仅限于掌握该技能所必需的内容。先教授知识，再让用户通过互动反馈循环练习技能。
知识应首先从可信资源中收集。使用 `RESOURCES.md` 跟踪这些资源。lessons 中应遍布引用——用外部资源链接支持每一项主张。这会提高 lesson 的可信度。
在获取知识时，难度是敌人。它会吞噬理解所需的工作记忆。
## 技能
如果说知识重在获取，那么技能重在持久性和灵活性。让知识真正留下来。
在技能习得中，难度是工具。费力提取正是建立存储强度的方式。技能应通过互动 lessons 来教授。你可以使用多种工具：
- 使用测验和轻量浏览器内任务的互动 lessons - 引导用户完成一系列现实步骤的 lessons（例如瑜伽体式）
这些方式都应建立在一个**反馈循环**之上，让用户收到关于自身表现的反馈。这个反馈循环应尽可能紧密，立即给出反馈，最好还能自动给出。
对于测验，每个答案的单词数应完全相同（如果可能，字符数也相同）。不要通过格式给用户任何答案线索。
## 获取智慧
智慧来自真正的现实互动——在学习环境之外检验自己的技能。
当用户提出的问题似乎需要智慧时，你的默认姿态应是先尝试回答，但最终把问题委托给一个**社群（community）**。
community 是用户能够在现实世界中检验技能的线上或线下场所。它可能是论坛、subreddit、线下课程（预算允许时）或本地兴趣小组。
你应尝试寻找用户可以加入的高声誉 communities。如果用户表示不愿加入 community，请尊重这一偏好。
## 参考文档
创建 lessons 的同时，也应创建 reference documents。lessons 可以引用这些文档——它们适合跟踪跨课程有用的原始知识单元。
lessons 日后很少会被重看，reference documents 则会。它们应以便于快速查阅的格式，呈现 lesson 的压缩精华。
有些学习主题特别适合做成参考资料：
- 编程的语法与代码片段 - 流程的算法与流程图 - 瑜伽体式与序列 - 健身的练习与训练计划 - 任何拥有专门术语体系的主题所需的术语表
尤其是术语表，它是一种关键参考资料。一旦创建，就应在每节 lesson 中遵循。
## `NOTES.md`
用户有时会表达他们希望采用的教学方式，或希望你记住的事项。这里就是记录这些偏好的地方，便于你在设计 lessons 或与用户协作时回看。
Source metadata
--- name: teach description: 在当前 workspace 中教授用户一项新技能或概念。 disable-model-invocation: true argument-hint: "你想学习什么？" ---

Entry SHA-256: a32df9dcdfc0c4fdc1c98e1ed3940c5f56b84c1aa90ff60346f32b8b53915b43

2. Why This Skill Is Clever

一句话核心机制

把一个目录变成跨 session 持续演进的教学系统：以 mission 定方向，以可信资源供给知识，以 learning records 校准最近发展区，再用短小、可互动、可复用的 HTML lessons 建立长期保持。

触发与调用边界

直接来源： frontmatter 的 disable-model-invocation: true 表明 teach 只能由用户显式调用；argument-hint 让用户指出学习主题。正文进一步声明这是跨多个 sessions 的 stateful request，因此它不是用来回答一次性问题的普通解释器。

支持背景： productivity 索引把 teach 列在 User-invoked；配套 docs 将它定位为“一项主题就是一个长期项目”，并建议每个主题使用独立 workspace。这些信息用于解释边界，不属于本页展示的原始 SKILL.md。

信息架构与执行顺序

  1. 读取或建立 MISSION.md，先弄清用户为什么要学；mission 不明确时必须先访谈。
  2. 在 RESOURCES.md 中收集高质量、高可信资源，禁止直接信任模型的 parametric knowledge。
  3. 读取 learning-records，结合 mission 判断用户的 zone of proximal development。
  4. 只设计一节范围紧、很快能完成并带来 a single tangible win 的 HTML lesson。
  5. 先降低知识获取阶段的无关难度，再通过提取、间隔、交错和即时 feedback loop 给技能练习加入合意难度。
  6. 先读取 assets/ 并复用组件；把可跨课程复用的新能力沉淀为 component。
  7. 同步更新 reference documents、learning records 与 NOTES.md，让后续 session 能从文件状态继续。
  8. 遇到依赖现实判断的 wisdom 问题时先尝试回答，最终引导用户到高声誉 community 中检验技能。

最巧妙的设计点

1. 用文件系统把“教学记忆”从对话中剥离

“The state of their learning is captured in this directory”

直接来源： mission、resources、lessons、references、learning records、assets 和 notes 各自拥有一种状态。后续 session 不需要依赖旧对话仍在上下文中，而是从 workspace 恢复课程进度。

解释： 这是一个小型 event-sourced 教学系统：lesson 是交付物，learning record 是对能力变化的解释性日志，mission 是长期目标，resources 是证据账本。角色分离让状态比聊天摘要更可审计。

2. 把“知道”拆成知识、技能与智慧三种不同获取机制

“the user needs three things”

直接来源： 知识来自可信资源；技能来自互动 lessons；智慧来自真实学习者和实践者。skill 没有让一个 LLM 同时冒充百科、教练和现实社群，而是为三种目标指定不同通道。

解释： 这种拆分防止教学只产出流畅的说明文。尤其是 wisdom 最终委托给 community，明确承认模型不能替代真实情境中的判断反馈。

3. 区分流畅强度与存储强度，避免“看懂了就是学会了”

“Fluency can give the user an illusory sense of mastery”

直接来源： 真实目标是 storage strength；retrieval practice、spacing 与 interleaving 用 desirable difficulty 构造长期保持。设计评价标准从“页面读起来顺不顺”转向“以后能否提取并应用”。

4. 同一份难度，在知识与技能阶段扮演相反角色

“For acquiring knowledge, difficulty is the enemy.”

“For skill acquisition, difficulty is the tool.”

直接来源： 获取新知识时，额外难度会占用工作记忆；练习技能时，费力提取反而建立存储强度。这个二阶段模型避免把所有内容都做成轻松阅读，也避免在概念尚未理解时过早增加认知负担。

5. 用 mission 与 learning records 动态计算下一步

“figure out their zone of proximal development”

直接来源： 用户未指定下一课时，agent 必须读取 learning records，并根据 mission 选择处于最近发展区内、最相关的内容。课程顺序因此不是固定大纲，而是由目标和已证实能力共同驱动。

解释： 这里的“计算”仍是语言模型判断，不是量化测评。优势是适应性强，风险是首节课没有历史记录时容易错误估计起点。

6. 把复用组件与耐久参考资料提升为一等产物

“Reuse is the default, not the exception.”

直接来源： lessons 应先读 assets/，共享 stylesheet 是每个 workspace 的第一个 component；reference documents 则保存 the compressed essence of the lesson。短期教学体验与长期复习资产由不同文件承担。

解释： 这让课程随着数量增长仍保持一致，并避免每节 lesson 内联重复 quiz、simulator 或样式。不过它也引入了链接完整性与 component 版本兼容问题，需要实际渲染验证。

防失败机制与明确不变量

Trade-offs、可移植风险与 harness 假设

直接来源： skill 使用 disable-model-invocation、CLI 打开文件、相对路径、HTML anchors 和一组格式模板，这些都假定 harness 能定位 skill 资源，并允许在当前目录写文件及打开本地 HTML。

支持背景： 配套 docs 指出一个真实路径歧义：./MISSION-FORMAT.md 是相对于 skill 安装目录，而 ./lessons/ 应相对于教学 workspace。若 agent 把两类 ./ 解析成同一根目录，课程可能被写进 skill 目录。docs 还记录了 quiz 正确答案位置偏置、首次缺少水平评估、没有自动 spaced-repetition 调度以及停止条件不可靠等限制。

解释：

可迁移原则

  1. 把长期状态写入具有明确所有权的产物，而不是寄希望于会话记忆。
  2. 先区分知识、技能与判断，再为每一类选择正确反馈来源。
  3. 让目标与已证实能力共同决定下一学习单元。
  4. 知识输入阶段减少摩擦，技能练习阶段加入有目的的困难。
  5. 把一次性体验与长期参考分开设计。 lesson 负责教学路径，reference 负责日后快速提取。
  6. 把组件复用设为默认，并在第二次复制发生前抽取。
  7. 证据机制的目标不是让用户盲信，而是让核验足够便宜。

今日实践题

假设你要用这个架构学习“在生产环境排查 PostgreSQL 慢查询”，第一节 lesson 的 single tangible win 应是什么？你会把哪些内容放进 lesson，哪些压缩到 reference，又如何设计一次带即时反馈的提取练习？

Evidence note

Source & provenance
Repository path
skills/productivity/teach/SKILL.md
Generated
2026-08-28 09:41 Asia/Shanghai
Upstream commit
6654f6b60cd9d5be8b54c6fafe44346dabeb3b76
Source
View on GitHub

Source: mattpocock/skills · Original content remains under its upstream license. Translation and commentary are for personal learning.