teach-eli5 · diff
v1.0.0 to v1.0.0
70 added, 64 removed. Audit A to A.
---
name: teach-eli5
description: >
- 像给完全不懂的小白讲清楚一件事。用户输入 /eli5 <主题> 或要求"用大白话/给外行讲明白
- /做个看图就懂的教学页"时触发。采用 mattpocock teach 方法论——以「学习目标(MISSION)」锚定、
- 「最近发展区(ZPD)」选材、每课一个自包含可打印的精美 HTML、复用组件库(assets)、沉淀术语表( glossary )与
- 学习记录( learning-records )，把复杂主题拆成"图多字少、类比先行"的小白友好教学页。
- 适用: 概念科普、技术原理给非技术人员、产品/功能讲解、知识卡片化教学。
+ 把任何复杂主题拆成「图多、字少、类比先行」的自包含教学 HTML，让零基础的人看图就能懂。
+ 用户输入 /eli5 <主题> 或要求"用大白话讲清楚""给外行讲明白""做个看图就懂的教学页"时触发。
+ 采用 mattpocock teach 方法论——以「学习目标(MISSION)」锚定、「最近发展区(ZPD)」选材、
+ 每课一个自包含可打印的精美 HTML、复用组件库(assets)、沉淀术语表(glossary)与
+ 学习记录(learning-records)。适用: 概念科普、技术原理给非技术人员、产品/功能讲解、
+ 知识卡片化教学。触发词: eli5、大白话、给外行讲、小白教程、讲明白、看图就懂、
+ explain like I'm 5、teach me simply。
argument-hint: "想搞懂什么？一句话说出你的场景"
- user_invocable: true
+ user-invocable: true
version: "1.0.0"
---
# teach-eli5 —— 给小白讲明白的教学引擎
- 把任何复杂主题，拆成「图多、字少、类比先行」的自包含教学 HTML，让零基础的人看图就能懂。
- 本技能融合了 mattpocock `teach` 的方法论（状态化、以目标锚定、最小可教学单元、复用组件、沉淀术语）与 eli5 的小白约束（不用术语、先类比、后精确）。
+ ## Purpose
- > 哲学一句话：**先让用户"啊哈"一下，再让他"记住"。** 前者靠类比和图，后者靠重复和可回看的精美页面。
+ 把任何复杂主题，拆成「图多、字少、类比先行」的自包含教学 HTML，让零基础的人看图就能懂。技能融合 mattpocock `teach` 的方法论（状态化、以目标锚定、最小可教学单元、复用组件、沉淀术语）与 eli5 的小白约束（不用术语、先类比、后精确）。
- ## 教学工作区（状态保存位置）
+ > 哲学一句话：**先让用户"啊哈"一下，再让他"记住"。** 前者靠类比和图，后者靠重复和可回看的精美页面。
- 把**当前目录**当作教学工作区。用户的学习状态用几个文件持久化，跨会话累积：
+ ## When to Use
- - `MISSION.md`：用户**为什么**想懂这个主题（所有教学决策的锚点）。格式见 [references/MISSION-FORMAT.md](./references/MISSION-FORMAT.md)。
- - `./lessons/*.html`：每**一课**是一个自包含 HTML 教学页。这是教学的主单元。命名 `0001-<slug>.html` 递增。
- - `./assets/`：**可复用组件**（共享样式表、类比卡片模板、图示 helper、quiz widget）。见 [Assets](#assets)。
- - `./references/glossary.md`：术语表，本工作区的"官方语言"。一旦建立，每课都遵守。
- - `./learning-records/*.md`：学习记录（类似软件开发的 ADR），记录用户已搞懂的非显然结论。命名 `0001-<slug>.md` 递增。
- - `NOTES.md`：你的草稿本，记用户偏好与工作备忘。
+ - 用户要"用大白话 / 给外行讲明白"一个概念或原理。
+ - 用户要一张看图就懂的教学页、科普页或知识卡片。
+ - 用户要把技术原理讲给非技术人员（客户、同事、家人）。
+ - 触发词：`/eli5 <主题>`、eli5、大白话、给外行讲、小白教程、讲明白、看图就懂、explain like I'm 5。
- ## 流程
+ ## When NOT to Use
- ### 第 0 步：定锚（Mission）
+ - 用户要正式课程、教学大纲或教案 -> 交给 `curriculum-design`。
+ - 用户要的是自己的学习路线图或十维认知拆解 -> 交给 `grasp`。
+ - 用户要一张内容型信息卡片（多模块、带主题配色、非教学向）-> 交给 `infocard`。
+ - 用户只要一段口头解释、不要可留存页面 -> 直接回答，不建工作区。
- 如果用户没说清为什么想懂这个，或 `MISSION.md` 还没写，**先访谈**再动笔。
- 含糊的目标会产出抽象的课。用 [MISSION-FORMAT](./references/MISSION-FORMAT.md) 的格式记录。
- 用户的"想搞懂"常是表层，要往下挖一层真实诉求（"想给客户解释""想面试""想修自家水管"）。
+ ## Workflow
- > 若用户只是随口要一个一次性讲解（如 `/eli5 黑洞`），可直接进入第 2 步产单课，不强制建全工作区；但**仍建议**顺手写一句 MISSION。
+ 工作区就是**当前目录**，状态写入工作区文件；文件清单与作用见 `references/workspace-conventions.md`。
- ### 第 1 步：判定起点（ZPD，最近发展区）
+ 0. **定锚（Mission）** — 若用户没说清为什么想懂、或 `MISSION.md` 不存在，先访谈再动笔；按 `references/mission-format.md` 记录。用户"想搞懂"常是表层，往下挖一层真实诉求。
+ 1. **判定起点（ZPD）** — 读 `learning-records/` 与 `NOTES.md`，判断用户已知什么、当前最该懂的"下一个最小知识点"是什么、它是否直接服务于 MISSION。小白优先用生活类比搭桥，再引入精确概念。
+ 2. **产出一课** — 写 `lessons/000N-<slug>.html`，遵守小白友好硬约束（图多字少、先类比后精确、禁行话、一个可带走的小收获、紧扣 MISSION、页尾留一句"有不懂的随时问"）。版面规范见 `references/lesson-format.md`。环境允许时用 CLI 打开该 HTML。
+ 3. **沉淀** — 每课顺手做三件事：新术语进 `GLOSSARY.md`（格式见 `references/glossary-format.md`）；真理解写成 `learning-records/000N-<slug>.md`（格式见 `references/learning-record-format.md`）；新的可复用部件写进 `assets/` 并链接，不要内联。
+ 4. **难度与复习** — 用「合意困难」设计：回忆练习（合上页复述）、间隔（隔几天再出一题）、交错（相关小主题混着练）。小白场景优先给"一张图带走"的复习页，而非测验。
- 每课都要让用户感到"刚好有点挑战"。读 `learning-records/` 和 `NOTES.md`，判断：
+ > 若用户只是随口要一次性讲解（如 `/eli5 黑洞`），可直接进入第 2 步产单课，不强制建全工作区；但仍建议顺手写一句 MISSION。
- - 用户已知什么（别重复教）
- - 当前最该懂的"下一个最小知识点"是什么
- - 这个知识点是否直接服务于 MISSION
+ ## Decision Rules
- 小白优先用**生活类比**搭桥，再引入精确概念。例子：讲"API"→先"餐厅里服务员帮你传菜"，再"程序之间传数据的约定"。
+ - `MISSION.md` 已存在且目标清晰 -> 直接进入第 1 步。
+ - 用户目标含糊 -> 先访谈，再写 MISSION；烂目标比没目标更糟。
+ - 一次性讲解请求 -> 跳过工作区搭建，直接产单课。
+ - 用户已懂某主题 -> 不再重复教，把"已知前提"记入 learning-record 后前进。
+ - 需要某个工作区文件的格式 -> 读对应 format 参考文件（见下）。
+ - 需要新的图示/quiz 组件 -> 先查 `assets/` 是否已有；没有则新增到 `assets/` 并链接。
- ### 第 2 步：产出一课（Lesson = 自包含 HTML）
+ ## Constraints
- 每一课是一个 `./lessons/000N-<slug>.html`，**小白友好**是硬约束：
+ - **不堆砌术语**：一个概念没用类比搭桥就给精确定义 = 失败。除非该词已进 `GLOSSARY.md`，且本页首次出现时就地用大白话解释。
+ - **不信参数记忆**：需要事实/数据时优先查高信任来源并标注出处，不凭记忆编造数字。
+ - **不产长文**：单课控制在"几分钟内能看完"；零基础的工作记忆很小。
+ - **图优先**：能画图说清的不用段落；SVG 内联，自包含、可离线打开。
+ - **复用是默认**：`assets/base.css` 是共享样式表，每课都链它，让所有课像"一门课"；绝不把未来会复用的代码内联进单课。
+ - **中文无乱码**：写入文件禁用 Box Drawing 等 Unicode 装饰字符（防 U+FFFD），用纯 ASCII 替代（树形 `|--`、箭头 `->`）。
- 1. **图多字少**：核心机制用 SVG 图示 / 类比图表达，正文克制。每屏只讲一件事。
- 2. **先类比，后精确**：先用生活类比让人"啊哈"，再给一句精确表述（精确句可折叠或放最后）。
- 3. **禁用行话**（除非已进 glossary 且本页首次出现时就地解释）。用词对齐 `references/glossary.md`。
- 4. **一个可带走的小收获**：每课结束时用户应能复述一个要点。
- 5. **Tufte 式排版**：干净、可读、留白足；这是用户会回头复习的页，不是一次性聊天。
- 6. **紧扣 MISSION**：说明"懂这个对你那个目标有什么用"。
- 7. **一句提醒**：页尾提示"有不懂的随时问，我可以接着讲"——你是老师，不是一次性生成器。
+ ## Verification
- 版面规范见 [references/LESSON-FORMAT.md](./references/LESSON-FORMAT.md)。每课链接到其它课与 reference 文档（HTML 锚点）。
- 如环境允许，用 CLI 命令打开该 HTML 给用户看。
+ 交付前逐项确认：
- ### 第 3 步：沉淀（每次产课顺手做）
+ - [ ] 本课服务于 `MISSION.md`，并在页内说明"懂这个对你那个目标有什么用"。
+ - [ ] 核心机制有 SVG 图示；正文克制，每屏只讲一件事。
+ - [ ] 先类比后精确，且未使用未解释的行话。
+ - [ ] 结尾有一个可复述的要点。
+ - [ ] 页面自包含：链 `assets/base.css`，无外部图片/CDN，可离线打开。
+ - [ ] 新术语、学习记录、新组件已分别沉淀到 `GLOSSARY.md` / `learning-records/` / `assets/`。
+ - [ ] 文件内无 Box Drawing 等装饰字符，无 U+FFFD。
- - **术语**：出现且用户已理解的词，加进 `references/glossary.md`（定义一两句，列出"避免混用的说法"）。
- - **学习记录**：用户展现了真理解（答对了 / 说清了 / 纠正了误区），写一条 `./learning-records/000N-<slug>.md`。仅记"决策级洞见"，不写流水账。格式见 [references/LEARNING-RECORD-FORMAT.md](./references/LEARNING-RECORD-FORMAT.md)。
- - **复用组件**：本课用到的新可复用部件（图示模板、quiz），写成 `./assets/` 下的组件并链接，别内联到单课里（`assets/base.css` 是首个该有的共享样式）。
+ ## Output
- ### 第 4 步：难度与复习
+ - **Outcome**：一个自包含、可打印、可离线打开的教学 HTML（`lessons/000N-<slug>.html`），外加累积的 `MISSION.md`、`GLOSSARY.md`、`learning-records/`、`assets/` 状态。
+ - **Done when**：本课 HTML 已产出并打开，且通过 Verification 清单；需要沉淀的术语/记录/组件已落盘。
+ - **Evidence**：页面含内联 SVG 图示与"先类比后精确"两段式；页尾有提问提醒；`GLOSSARY.md` 与 `learning-records/` 出现新课对应的条目。
- - **流利度 ≠ 记住**：当堂能答给人"学会了"的错觉，**长期留存**才是目标。
- - 用「合意困难」设计：回忆练习（合上页复述）、间隔（隔几天再出一题）、交错（相关小主题混着练）。
- - 小白场景下，**间隔复述 + 一图流总结卡**比测验更有效，优先给"一张图带走"的复习页。
+ ## References
- ## Assets（复用组件库）
+ 按需加载，不要预先全读：
- 课由 `./assets/` 里的**可复用组件**拼成。复用是默认，不是例外。
+ - `references/workspace-conventions.md` — 第一次为某个主题开课时读，确认状态文件放哪、各是什么。
+ - `references/mission-format.md` — 写或修订 `MISSION.md` 时读。
+ - `references/lesson-format.md` — 写一课 HTML、需要版面与小白硬约束细节时读。
+ - `references/learning-record-format.md` — 判断该不该写学习记录、以及怎么写时读。
+ - `references/glossary-format.md` — 往 `GLOSSARY.md` 收录术语、需要条目格式时读。
- - 动手写课前先读 `./assets/`，用已有的组件。
- - 需要新且可复用的东西，写成 `./assets/` 下的组件并链接；绝不把未来会复用的代码内联进单课。
- - 第一个该有的组件是共享样式表 `./assets/base.css`：每课都链它，让所有课像"一门课"而非一堆散页。
+ ## Examples
- ## 约束与红线
+ 按需加载：
- - **不堆砌术语**：小白要的是"懂"，不是"显得专业"。一个概念没用类比搭桥就给精确定义 = 失败。
- - **不信参数记忆**：需要事实/数据时，优先查 `references/` 与高信任外部资源并标注来源，不凭记忆编造数字。
- - **不产长文**：单课控制在"几分钟内能看完"。零基础的工做记忆很小，必须守在里头。
- - **图优先**：能画图说清的，不用段落。SVG 内联，自包含、可离线打开。
- - **中文无乱码**：写入文件禁用 Box Drawing 等 Unicode 装饰字符（防 U+FFFD），用纯 ASCII 替（树形 `|--`、箭头 `->`）。
+ - `examples/0001-what-is-api.html` — 需要看"合格的一课长什么样"（类比段落、内联 SVG 图示、精确段、样式引用）时读；它是本技能自带的样例课，直接链 `../assets/base.css`。
- ## 与 mattpocock teach 的关系
+ ## Related Skills
- 本技能取其**骨架**（MISSION 锚定、ZPD 选材、课时自包含 HTML、assets 复用、glossary/learning-records 沉淀），
- 并叠加 eli5 的**小白约束**（图多字少、类比先行、禁行话、一图流复习）。
- 原 `teach` 面向"在 workspace 里长期学一门技能"（如瑜伽、Rust），本技能面向"把一件事给外行讲明白"，
- 因此略去了社区/智慧(community)分支，强化可视化与单页可懂性。
+ - `curriculum-design` — 正式课程、教学大纲与教案设计。
+ - `grasp` — 十维认知框架与学习路线图，用于学习者的系统自学。
+ - `infocard` — 内容型信息卡片，带主题配色体系，非教学向。