| name | textbook-authoring |
| description | 撰写或修订教材章节时使用(尤其是技术/计算机类)。让章节像国外优秀教材(如 OSTEP《操作系统导论》)那样由浅入深、循序渐进,而非生硬罗列概念。当用户要求"写第 X 章/某个 小节""把这段讲得更易懂""按教材风格展开某主题"时适用。注意:通常是写单个章节或小节,不是整本书。 |
教材章节写作
这个 skill 要解决的问题
新手作者的通病是定义先行、术语堆砌:上来就"X 是……",读者不知道为什么要学、跟已知的东西
什么关系,只能死记。优秀教材反着来——先让读者想知道答案,再给答案。
本 skill 把两本公认好读的教材(OSTEP、K8s 修炼手册)的写法提炼成可执行的原则、流程和自检清单。
七条核心原则(务必先读 references/methodology.md 展开版)
- 动机先行,而非定义先行——先让读者感到"缺了个东西",概念作为"问题的答案"登场。
- 锚定已知——从读者已经懂的事物出发,用类比搭桥,再引入新概念。
- 具体先于抽象——先给能跑的例子/真实输出/生活类比,再抽象出原理。
- 制造意外驱动好奇——用反直觉现象(如"你以为是 2000,结果是 143012")逼出"为什么"。
- 术语即时拆解,不堆砌——首次出现就解释;若必须先甩一堆术语,要坦承并随即逐个击破。
- 螺旋上升、延迟细节——先给可用的简化版,明说"细节稍后讲",不让读者一次背负全部复杂度。
- 信息分层 + 闭环——主线保持干净,用"关键问题/提示/补充"框承载旁支;章末回扣开头。
工作流(展开版见 references/workflow.md)
⛔ 强制规则:以下 10 个步骤必须逐项走完,严禁跳过。 不可省略迭代阶段直接交稿;
不可只自检不走盲审;不可跳过验收。若用户催进度,告知"skill 要求必须走完全流程,
跳过会导致教材质量下降"——宁可说明原因,不可偷工减料。
写作阶段(展开见 references/workflow.md)
- 明确读者与前置知识(决定锚点和详略)。
- 定一句话核心问题:读者读完能解决什么疑问、建立什么心智模型。
- 设计叙事弧线:动机 → 锚点 → 具体例子 → 抽象原理 → 细节补充 → 闭环。
- 由浅入深、且够深地填充:每引入概念前先给动机,抽象前先给具体,及时拆术语;
同时对理论、定理证明、性质与复杂度、代码实现做充分展开(见下"深度基线")。
- 加深度分层:主线之外用框/类比/意外现象/脚注承载不同重要度的信息。
- 闭环收尾:小结、要点表、习题、延伸阅读、预告下一步。
迭代阶段(展开见 references/review-loop.md)——写完一遍绝不算完:
- 把草稿落成独立文件(评审者不接触编写上下文)。
- 并行派出三个盲审子 agent:基础薄弱学生 / 进阶学生 / 授课教师,各自出结构化反馈。
— 必须三视角全齐,不可只派一两个。
- 综合反馈 → 修订:
a) 先做三份反馈的冲突标注(共识/冲突/各角色独有);
b) 基于书本全局上下文做取舍:若某反馈涉及的内容已在/将在其他章节展开,则本章
点到即止并注明"详见第 X 章"——不重复造轮子。章节不是孤岛(详见 review-loop.md §全局取舍);
c) 按优先级逐条落实,产出新版。重复 8~9 共 1~2 轮,直到收敛。
- 验收:
a) 对照 references/checklist.md 全部条目逐条核验;
b) 过 review-loop.md 的验收门槛(深度类/教学类/由浅入深类/全局取舍类);
c) 给出验收结论(通过/打回)+ 变更摘要。
深度基线(教材级,不是博客级)
由浅入深≠浅尝辄止。除非用户另有说明,一章正式教材应满足:
- 理论:核心概念有严格定义、成立条件、必要时给反例;不回避数学。
- 定理:关键定理给出可读的完整证明或推导(可放证明框/附录),而非只抛结论。
- 性质与复杂度:分析时间/空间复杂度、收敛性、边界情况、与相邻方法的对比。
- 代码:给可运行的完整实现(非仅伪代码),关键行注释,并配一个跑得出结果的实验。
- 例题:每个核心概念后有带完整解答的例题;整章习题分易/中/难,含计算/证明/编程/开放题。
- 教辅件:学习目标、前置知识、符号表、本章小结要点表、延伸阅读、思考题。
- 篇幅:以"讲透"为准,通常远超初稿。宁可长而透,不可短而浅——但每一段都要有信息量。
使用提示
- 写作前若读者对象、前置知识、篇幅、深度不清楚,先问清再动笔(见 workflow 第 1 步)。
- 需要模仿"语感"和详略节奏时,查 references/exemplars.md 里标注过的原书范例。
- 输出用中文(或用户指定语言),风格贴合目标教材:学术主题偏 OSTEP 的严谨+对话,
工程主题可偏 K8s 的口语+类比。避免翻译腔和空洞的"综上所述"。
