textbook-writer

Textbook-Writer-Skills 教材写作套件

简体中文 | English

Textbook-Writer-Skills 是一套装进编程智能体（Claude Code / Codex / 国内 WorkBuddy）的教材写作 skill 组合。它把成熟的教学设计方法装进 AI 的工作流：先想清楚「学生学完该带走什么」，再倒推章节和习题，一章一章写出有主线、有梯度、题目答案可信的成体系教材——中途断了随时续写。当前 v0.6.2：5 个 skill（1 个主调度 + 3 个流水线子 skill + 1 个独立辅助）覆盖从工作目录规划到审核定稿的五阶段全流程，理科、人文社科与经济学都能写。

一套内核，多个学科门类。 学科差异不散落在流程里，而是收拢成可插拔的学科档案——随学科变化的只有四件事：题型集、验证手段、认知动词、章内段义。内置三份：stem 面向数学、物理、计算机等答案可复算的学科（已跑通全案回归）；humanities 面向历史、哲学、文学、政治学、社会学、艺术史等答案取决于论证的学科，把"真算复核"换成"核对来源"（大纲与单章两条路径已由 eval 7、8 实跑验证）；economics 面向经济学与金融学这类混合学科——模型题能复算、统计数据只能核来源、政策题两者都不适用而要给论证要点，三类手段在同一本教材里交织（eval 9、10 待跑）。三份档案共用同一套验证纪律，换的只是核的方式。支持一个新门类不需要改内核，只需加一份档案、在索引里登记一行。

阶段交接契约、落盘布局与状态机的准确定义以 handoff-contract.md 为准，学科差异的收口处是 subject-profile-spec.md。

设计理念

拼的是教学设计，不是长文生成。 写教材的难点不在写作本身，在教学设计。已有工具解决的是「把素材组织成长文档」，这套 skill 解决的是「怎么把一门知识教明白」。

• 关键决策由作者拍板。 教学定位、UbD 五件套、章节树是一本教材的灵魂。skill 给出草案后会停在两个检查点（gate）等作者明确确认，任何「流程优化」都不得绕过——它的职责是逼你想清楚，不是替你做主。
• 诚实优先于流畅。 验证不了的结论宁可标注「需作者确认」，也不输出一个看起来自信的编造结果。
• 用流水线代替一口气写完。 流水线上的 4 个 skill 各管一段，阶段之间靠书面契约交接，互不读对方的中间过程——这是长教材写得完、每章质量稳定的工程保证。

不可妥协的底线：每道题的答案必须按学科档案定义的手段核过才输出（理科真算复核、文科核对来源与引文出处），验证不了的一律标注 ⚠️ 需作者确认；阶段 2/3 的双 gate 必须作者明确确认才放行。这两条不与任何目标权衡——学科可以换，纪律不换：档案能定义"用什么方式验证"，不能定义"是否需要验证"。

✅ 能做的 / ⛔ 不做的

✅ 这套 skill 会做的	⛔ 这套 skill 不做的
一轮提问定教学定位，产出 UbD 五件套	替你拍板教学定位与章节取舍（双 gate 停下等你确认）
倒推章节树，做全书 Bloom 梯度体检	替你判断学界有争议处该站哪一边（会列出主要分歧请你定）
按四段式逐章写正文，维护术语表一致性	把你已有的讲义素材整理成一门课
生成三类题，答案按学科档案定义的手段核过（理科真算复核 / 文科核对来源与引文出处）	输出验证不了却假装已验证的答案；凭记忆编造引文、出处或年份
进度落盘 .progress.json，断了从断点续写	在线课程平台与 LMS 集成
动笔前规划并创建工作目录（可选 git）	自动生成插图

「不替你做主」不是缺点，是这套流水线的设计前提：教学定位、UbD 五件套、章节树决定一本教材的成败，AI 出草案，判断权留给懂学科的你。

五条红线的完整表述见 CONTRIBUTING.md 的「红线约束」一节，契约层的权威定义见 handoff-contract.md。

能写哪些学科

学科覆盖由三份可插拔的学科档案定义，阶段 1 按你的学科自动判定、打印一次（如 学科档案：humanities），此后逐章透传——你不需要指定档案，判得不对在阶段 1 直接说。权威索引与判定口径见 subject-profile-spec.md 第 5 节。

档案	覆盖学科	验证方式	实测状态
stem	数学各分支、物理、化学、工程、计算机科学与算法	真算复核：逐题沿与解答不同的路径实际复算并比对结果	✅ 全案回归通过（eval 1–6）
humanities	历史、哲学、文学、政治学、社会学、艺术史、宗教研究	核对来源：引文逐字核对原文并记明版本与位置，绝不凭记忆编造出处	✅ 大纲与单章两条路径实跑通过（eval 7、8）
economics	经济学各分支（微观、宏观、计量、国际、发展、产业组织）与金融学	混合：模型题复算 + 统计数据核对权威来源 + 政策题给论证要点与评价标准	⏳ eval 9、10 待跑（档案与用例已入库）

分界从同一个问题问起：**这门学科的典型习题，答案能不能由一条与解答不同的路径重新算一遍并比对结果？**基本都能，走 stem；基本都不能（答案取决于论证与立场），走 humanities；一半能一半不能（模型可复算、数据只能核来源），走 economics。

站在边界上的学科，各档案第 1 节写明了判定口径：

• 语言学习、法学、会计：语法规则、法条、判例、准则都是确定性可核查事实——以规则应用题为主走 stem（把「复算」读作「查条文原文并比对」），以案例论证、法理辨析为主走 humanities；
• 心理学、地理：计算题与实证数据题走 stem，理论论述与政策讨论按 humanities 的论述题处理；实证形态与经济学同构（实证数据 + 统计推断）的教材也可参照 economics——它会先向你说明已知差异再动笔；
• 经济学内部再分：纯数理推导为主体（数理经济学、金融工程）走 stem，以论证与文本为主体（经济思想史、比较经济制度、政治经济学）走 humanities，两类题在同一本书里交织（绝大多数经济学原理、中级微观/宏观、计量入门教材）走 economics；
• 交叉主题（科学史、数字人文）：以哪类题为主体就走哪份档案，另一类按对方档案的对应题型处理，分工写进教材设计文档。

清单之外的学科也能写，但不会静默硬套：阶段 1 匹配不到档案时，它会向你说明「本学科暂无专属档案，将按最接近的档案处理」并列出已知差异（哪些题型没有对应的验证手段、章内段式是否需要调整），由你决定继续还是调整范围——档案决定全书的验证纪律与章内段式，这个近似能不能接受，只有懂学科的你有资格判断。

它解决三个坑

直接对 AI 说「帮我写一本教材」，通常会踩中三个坑。这套 skill 的全部设计都是冲着它们去的。

坑一：写出来的是知识点汇编，不是教材

AI 很乐意一章一章罗列概念，像把百科词条装订成册：没有贯穿全书的主线，习题和「学生该学会什么」对不上，学完不知道该带走什么。

解法是先设计、后动笔。 借用教育学的成熟方法「UbD 逆向设计」：动笔前先逼作者回答「学生学完该带走什么」，形成五件套——大概念、持久理解、核心问题、迁移目标、学习目标——作者确认后，才由此倒推章节树和每章的例题/习题计划，和主线对不上的章要砍或改。配套的梯度纪律：每道题标注 Bloom 认知层级（记忆→理解→应用→分析→评价→创造），全书自动做梯度体检——题目扎堆单一层级（≥60%）或缺了应用/分析层会直接告警；每章正文遵循固定的四段式节奏（概念讲解 → 示范例题 → 引导练习 → 独立习题），不会有的章全是概念、有的章全是题。

这套设计还要对读者可见才算兑现：学习目标不止留在设计文档里，章首摊开成学生能读的「读完本章，你应该能……」，章末给一份自检清单——逐条对照章首目标，拿不准就指回该重读的那一段、该自测的那道题。定稿时另生成 00-前言.md（写给谁、怎么用这本书、带链接的目录）与术语表里的符号约定节，读者打开这个目录知道从哪进、遇到不认识的记号知道去哪查。

下图是同一本《线性代数入门》的阶段 1–3 产物——教学定位、UbD 五件套（大概念）、章节树，两处 gate 停点清晰可见：

同一本教材 58 道题的全书梯度体检报告——分布表、可视化条形图、三条自动检查规则：

坑二：例题看着头头是道，一算就错

编造是 AI 写教材最致命的毛病——理科是算错，读者照着例题演算发现书是错的；文科是伪造引文与史实错位，虚构文献、张冠李戴的名言、错乱的纪年。两者伤的是同一样东西：整本教材的信誉。

解法是每道题都验一遍，验的方式由学科档案定。 理科（stem 档案）用一条与解答不同的路径实际复算，复算过程随题附上；文科（humanities 档案）把引文逐字核对原文并记明版本与位置，事实性断言核对作者提供的材料或学界公认来源，论述题不给标准答案而给论证要点加评价标准。经济学（economics 档案）两种手段都要用——模型题走复算，统计数据核对权威来源并标明机构、口径与年份，同一章里两种验证记录并存。三份档案共用同一套纪律：确实验证不了的明确标注 ⚠️ 需作者确认，绝不假装已验证，也绝不凭记忆编造引文、出处或统计数值。

下图是 textbook 端到端跑出的《线性代数入门》第 4 章片段——四段式节奏与每道题的真算验证标签清晰可见：

写文科要先算一笔成本：引文能不能核实，取决于手上有没有材料。eval 8 实测，完全不提供史料时 9 道题里有 3 道挂着 ⚠️ 需作者确认（引文未核）——无史料输入时，预期约三分之一的题需要你事后核定。这不是缺陷，是 humanities 档案预告的必然结果（它宁可标注，也不逐字引用一句核不实的话）。想把这个比例压下去，在阶段 1 就把史料、原著版本、文献清单交给它——档案会主动向你索要。

坑三：章数一多就写崩

把 10+ 章教材塞进一个对话，上下文迟早爆掉：写到第八章忘了第二章的记号，术语前后不一致；中途断线只能从头再来。

解法是一章一章独立写、进度落盘。 每章写作只接收四件轻量输入——该章大纲切片、全书 UbD 五件套、术语表、前章小结（外加一个学科档案 id，决定本章段式与验证手段），不读任何其他章的正文，章数再多也不会撑爆上下文。写作进度实时写入 .progress.json，任何时刻中断，下次一句话就能从断点续写，已完成的章不会被重写。

五阶段流水线 × skill 能力

一张表看全：谁在哪一阶段干什么、产出落到哪个文件、哪两处会停下等你、由哪个 eval 用例守着。

阶段	执行 skill	做什么	产出	Gate	验收用例
0 · 起步（可选）	textbook-init	一轮提问弄清写一本还是多本、放在哪里、要不要版本管理	工作目录骨架（可选 git 与 README 工作说明）	—	eval 6
1 · 教学定位确认	textbook-outline	学科 / 读者起点 / 深度 / 篇幅，并按学科定出学科档案	00-教材设计.md「## 一、教学定位」	否（一轮提问）	eval 1
2 · UbD 预期结果设计	textbook-outline	大概念、持久理解、核心问题、迁移目标、学习目标	「## 二、UbD 五件套（已确认）」	⏸ 是（核心 gate）	eval 1
3 · 评估与章节设计	textbook-outline	章节树 + 例题计划 + 全书梯度报告 + 表现性任务	「## 三、章节树与梯度规划（已确认）」「## 四、表现性任务」	⏸ 是（次要 gate）	eval 1
4 · 章节正文编写	textbook-chapter → textbook-exercises	四段式正文（段标题由学科档案定），每道题按档案的手段核过	NN-<章标题>.md × N + 98-参考答案.md + 术语表增量	否	eval 2, 3、8
5 · 审核定稿	textbook（主 skill）	通读自检、派生学生可读版任务、生成读者入口前页	自检报告 + 00-前言.md + 99-表现性任务.md + 交付摘要	否	eval 5

阶段 1–5 由主 skill textbook 调度，.progress.json 状态文件只由它读写——中断-续写机制本身由 eval 4 守着。阶段 0 不入调度链：textbook-init 只创建目录骨架就把你交给 textbook；不经 init 直接开写也可以，textbook 会自建默认目录。

快速开始

三个宿主都能用：Claude Code、Codex、WorkBuddy。

安装

复制下面对应你的智能体的那段话，粘贴给它就行——它会自己装完，你不用敲任何命令。

装到 Claude Code 👇

帮我安装 textbook-writer-skills 教材写作 skill 组合：

1. 把 https://github.com/cabbage2000-lab/textbook-writer-skills 克隆到一个临时目录
2. 确保 ~/.claude/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部 5 个子目录**
   复制进去，一个都不能少：textbook、textbook-outline、textbook-chapter、
   textbook-exercises、textbook-init
   - 这 5 个 skill 是一个整体组合，彼此以 ../<skill 名>/references/ 相对路径互引，
     漏装一个就会断链
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 删掉临时目录
4. 告诉我装到了哪里、5 个 skill 是不是都装齐了

装到 Codex 👇

帮我安装 textbook-writer-skills 教材写作 skill 组合：

1. 把 https://github.com/cabbage2000-lab/textbook-writer-skills 克隆到一个临时目录
2. 确保 ~/.codex/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部 5 个子目录**
   复制进去，一个都不能少：textbook、textbook-outline、textbook-chapter、
   textbook-exercises、textbook-init
   - 这 5 个 skill 是一个整体组合，彼此以 ../<skill 名>/references/ 相对路径互引，
     漏装一个就会断链
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 删掉临时目录
4. 告诉我装到了哪里、5 个 skill 是不是都装齐了

装到 WorkBuddy 👇

帮我安装 textbook-writer-skills 教材写作 skill 组合：

1. 把 https://github.com/cabbage2000-lab/textbook-writer-skills 克隆到一个临时目录
2. 确保 ~/.workbuddy/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部 5 个子目录**
   复制进去，一个都不能少：textbook、textbook-outline、textbook-chapter、
   textbook-exercises、textbook-init
   - 复制的是这 5 个子目录本身，别把整个 skills/ 目录整体套进去——WorkBuddy 会按
     目录层级给技能命名，多套一层技能名就变成 skills:textbook 了
   - 这 5 个 skill 是一个整体组合，彼此以 ../<skill 名>/references/ 相对路径互引，
     漏装一个就会断链
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 删掉临时目录
4. 告诉我装到了哪里、5 个 skill 是不是都装齐了

装完新开一个会话才会加载——已开的会话看不到新 skill。WorkBuddy 还可以在「技能」面板里核对是否装齐。

只想在单个项目里用？ 把提示词里的用户级路径换成该项目根目录下的项目级目录：Claude Code 用 .claude/skills/，Codex 用 .codex/skills/ 或 .agents/skills/，WorkBuddy 用 .codebuddy/skills/——注意不是 .workbuddy/，它的用户级目录叫 ~/.workbuddy/，项目级目录却沿用底层 CodeBuddy 内核的 .codebuddy/，这一处不对称容易写错。

用的是别的宿主？ 同一段提示词，把目标路径换成该宿主的 skills 目录即可。装错位置的表现是 skill 一个都不出现、且没有任何报错——各宿主的 skills 目录互不读取，几个宿主都用就各装一份。

能不能只装一个？ 不能。哪怕只想用 textbook-exercises 单独出题，它也要读 textbook-outline 的 Bloom 动词表和 textbook 的交接契约——5 个一起装是最低要求。

一点都不想装？ 用 Codex 或其他读 AGENTS.md 的宿主直接打开本仓库目录也能用：仓库根的 AGENTS.md 会把「写教材」一类请求路由到对应 skill，无需任何安装。

更喜欢自己敲命令？三个宿主都支持插件式一键安装

本仓库自身就是插件市场，插件形态多一个好处：能用一条命令更新。

Claude Code——在会话里依次执行：

/plugin marketplace add cabbage2000-lab/textbook-writer-skills   # 也可用本地仓库路径
/plugin install textbook-writer@textbook-writer-skills

WorkBuddy——同样在会话里执行（它读自己的 .codebuddy-plugin/ 清单）：

/plugin marketplace add cabbage2000-lab/textbook-writer-skills
/plugin install textbook-writer@textbook-writer-skills

Codex——在终端里执行：

codex plugin marketplace add cabbage2000-lab/textbook-writer-skills
codex plugin add textbook-writer@textbook-writer-skills

两条路装的是同一套 skill，别对同一个宿主两种都用——会装出两份。WorkBuddy 的插件清单格式已由作者在其他项目实测可用，本仓库按同一格式编写。

从 SkillHub 装（国内源，不用访问 GitHub）

5 个 skill 已上架 SkillHub，好处是全程不必访问 GitHub。先装一次它的 CLI：

curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
export PATH="$HOME/.local/bin:$PATH"          # 建议同时写进 ~/.zshrc

然后一次装齐 5 个，--dir 换成你宿主的 skills 目录（下面以 Claude Code 用户级为例）：

for s in textbook textbook-outline textbook-chapter textbook-exercises textbook-init; do
  skillhub install "$s" --dir ~/.claude/skills
done

Codex 换 ~/.codex/skills，WorkBuddy 换 ~/.workbuddy/skills；只在单个项目里用就换成对应的项目级目录（见上面那条注释）。装完同样要新开一个会话。

别加 --namespace。 加了会多套一层 @<作者>/ 目录，而宿主只扫 skills/*/SKILL.md 这一层——多一层就一个都发现不了，且没有任何报错。

5 个必须装进同一个 --dir。 它们靠 ../<skill 名>/references/ 互引，只有互为同级才解析得到；少装一个，用到它的那条引用就是死链。

更新：同一条命令加 --force 覆盖（不加会报 Target exists），或用 skillhub upgrade（不带 slug 则更新它记录过的全部 skill）。

和上面两条路选一条就行，别对同一个宿主混用——装的是同一套 skill，混用会装出两份。

上架的是与本仓库 skills/ 逐字一致的同一份内容（平台会额外塞一个记录版本号的 _meta.json）。当前上架版本 v0.6.2。

想在本仓库内开发或改着试跑，clone 后执行一次，把 skills/ 软链为项目级 skills 目录（.claude/ 已 gitignore，不入库）：

mkdir -p .claude && ln -s ../skills .claude/skills

第一次运行会发生什么

新开一个会话，输入：

用 textbook 写一本《线性代数入门》教材

1. skill 建立教材项目目录和进度文件 .progress.json；
2. 一轮提问确认教学定位：写给谁、多深、多大篇幅；
3. 产出 UbD 五件套，停在 ⏸ 等待确认——第一个 gate，可确认，也可提修改意见；
4. 确认后产出章节树和全书 Bloom 梯度报告——第二个 gate；
5. 之后逐章写作，每章独立落盘为一个 .md 文件——章首写明「读完本章你应该能……」、章末给一份自检清单，独立习题在章内只留题干，答案与验证记录集中进 98-参考答案.md，读者能先做后对；
6. 最后通读审核定稿，产出面向学生的综合任务与评分标准，并生成 00-前言.md——写给谁、怎么用这本书、带链接的目录，读者从这里进书。

中途任何时候中断，重新输入同一句话即可从断点续写。

怎么开口说：不用背 skill 名

用你自己的话说出你要做什么，宿主会匹配到对应的 skill；显式写出 skill 名（如 用 textbook-exercises 出几道题）也完全等价。这套工具适合「自己懂学科、想把知识写成体系化教材」的人：写技术讲义的开发者、把课堂笔记整理成教材的文理科教师和学生、做教学内容的创作者。skill 负责结构和纪律，学科知识的判断仍然在你。

你会这么说	落到	你会拿到
「写一本《线性代数入门》教材」	textbook	一个教材目录：00-前言.md（读者入口：前言 + 怎么用 + 带链接的目录）+ 00-教材设计.md + 逐章 NN-<章标题>.md + 98-参考答案.md + 术语表.md（术语 + 符号约定两节）+ 99-表现性任务.md + .progress.json