| name | chapter-generation |
| description | Generate a complete learning chapter (Markdown + quiz.json + concepts.json) for one slot in a learning project outline. Use when the host prompts "请使用 chapter-generation skill 生成第 N 章" with chapter index/title/duration/concepts. Writes three files via the Write tool. Skill is read-only and self-contained — does not call other skills. |
Chapter Generation
Generate one chapter's full learning material: Markdown body, end-of-chapter quiz, and concept-dependency map.
When the host invokes this skill
The host's prompt will look like:
请使用 chapter-generation skill 生成第 N 章。
- chapter_index: 2
- chapter_title: "反向过程：去噪原理"
- duration_minutes: 25
- concepts: ["前向过程", "噪声调度", "反向去噪"]
- project_path: /path/to/project
- previous_chapters: ["为什么学这个", "前向过程：逐步加噪"]
Parse these into variables. chapter_index is 0-based; convert to 2-digit zero-padded (02) for filenames.
Workflow
- Onboard (only if you haven't already this session): use
project-onboarding skill to read the project state. Skip if the user just said "ok" to onboarding.
- Read the format spec at
{project_path}/.claude/skills/chapter-generation/references/content-format.md. This is the canonical chapter format — your Markdown and quiz.json MUST follow it.
- Check if the target file already exists: use
Glob for {project_path}/{NN}-*.md. If found, STOP — the chapter was already generated. Report this and exit.
- Write three files with the
Write tool, in this order:
{project_path}/{NN}-{title-slug}.md{project_path}/{NN}-{title-slug}.quiz.json{project_path}/{NN}-{title-slug}.concepts.json
- MUST verify every file you just wrote — see checklist below. If any item fails, fix the file and re-write before returning.
- Return a one-line text confirmation:
第 N 章已生成: {title}, {M} 个测验题, {K} 个概念
Chapter structure template (FOLLOW THIS)
Each chapter must follow this structure, inspired by the transformer example:
# {NN}: {title}
> 预计阅读时间：{duration} 分钟
> 本章目标：一句话说明本章解决什么问题
---
## 1.1 {first concept title}
### {concept} 的核心直觉
Open with a **real-life analogy** (1-2 sentences) that anyone can relate to.
Then transition into the technical explanation.
{1-2 paragraphs of technical content with inline math}
```{language}
# Code example that illustrates the concept
{a concrete metaphor or problem}
Extend the analogy into a concrete scenario that exposes the limitations
or tradeoffs of the current approach. Use a Mermaid diagram here.
[!concept]
{Concept name}
{1-2 sentence definition with the analogy woven in}
1.2 {next concept title}
{its core intuition}
...
{a concrete example}
对比 table (MUST use markdown tables for comparison):
| Feature | Approach A | Approach B | Why |
|---|
| ... | ✅ | ❌ | ... |
1.{N} 本章总结
Recap the chapter's arc (3-5 bullet points or short paragraphs).
End with a ONE-SENTENCE summary in a blockquote.
[!question]
{thought-provoking question that requires synthesis, not memorization}
[!answer]- 查看答案
{detailed explanation with reasoning}
[!quiz]
小测验
1. {question}
A. {option 1}
B. {option 2} ✓
C. {option 3}
D. {option 4}
2. {question}
...
[!answer]- 查看答案
1. B — {explanation}
2. A — {explanation}
预告：第 {N+1} 章
{tantalizing preview that transitions from what was just learned to what's next}
## MUST-VERIFY checklist (run before returning)
Run through this with `Read` after writing. If anything fails, rewrite the file.
**Markdown file (`.md`):**
**Structure:**
- [ ] Sections are NUMBERED (`1.1`, `1.2`, ...) and follow the template above
- [ ] Each major section starts with a **real-life analogy** (no jumps straight into math)
- [ ] Contains at least one **Mermaid diagram** illustrating key concepts
- [ ] Contains at least one **comparison table** with pros/cons
- [ ] Contains a **代码示例** (Python pseudocode or similar)
- [ ] Ends with "本章总结" + "预告：第 N+1 章"
- [ ] Has at least one `---` horizontal rule between major sections
**Learning elements:**
- [ ] Contains ≥ 2 `> [!concept]` cards (yellow background, hover popup)
- [ ] Contains ≥ 1 `> [!question]` block (with `> > [!answer]` inside) — must be **synthesis-level**, not trivial
- [ ] Contains ≥ 1 `> [!quiz]` block (inline self-check with at least 3 multiple-choice questions)
- [ ] Quiz questions test **understanding**, not fact recall (avoid "what is X" — prefer "why does X happen" / "which scenario best illustrates X")
**Formatting:**
- [ ] All math uses `$...$` or `$$...$$` (not raw `\(...\)`)
- [ ] All code blocks have a language tag (e.g. ` ```python `, not just ` ``` `)
- [ ] Tables use proper markdown table syntax with alignment markers (`:---:`, `:---`, `---:`)
**Callout exact format (see callout-format-spec.md):**
- [ ] `[!question]` without `-` (default expanded); `[!answer]-` with `-` (collapsible)
- [ ] Answer title is plain text `查看答案`, no `**` bold
- [ ] Answer content indented with `> > ` (two levels), no extra "**答案：**" title inside
- [ ] Empty line (`> > `) after `> > [!answer]- 查看答案` before content
- [ ] Quiz options use `**A.**` format, NOT `- A.` list format
- [ ] Quiz answer inside `> > [!answer]- 查看答案` can include "**答案：B**" to mark correct option
**quiz.json file:**
- [ ] Top-level has `questions` field (array, **not missing — this is the #1 cause of host-side errors**)
- [ ] `questions` has 3–5 entries
- [ ] Every question has: `id`, `qtype` (single/multiple/short), `question`, `options`, `correct`, `weak_concepts`
- [ ] `options` is `[]` for `short` questions, otherwise has 2–4 entries with `label` (A/B/C/D) and `text`
- [ ] `correct` is `"A"`-style string for single, `["A","C"]` array for multiple, `null` for short
- [ ] Top-level also has `chapter_file`, `chapter_title`, `generated_at` (ISO 8601)
- [ ] Wrap the whole file as valid JSON (last char is `}`, no trailing comma)
- [ ] **No unescaped ASCII `"` inside string values** — if you use Chinese quotes `""` inside the text, they must be `“` / `”` (curly quotes) or `\"` (escaped), NOT bare ASCII `"`. A bare `"` inside a JSON string will cause `expected ',' or '}'` at that line.
**concepts.json file — exact format expected by Rust parser:**
```json
{
"chapter": "00-生成模型与扩散模型.md", // ← THIS FIELD IS REQUIRED (exact filename)
"concepts": [ // ← 缺少 chapter 字段会使 Rust 解析失败
{ "id": "generative-models", "name": "生成模型", "depends_on": [] }
]
}
Filename slug rules
Convert the chapter title to a kebab-like slug:
- Keep ASCII alphanumerics and Chinese characters (
一-鿿)
- Replace everything else (spaces, punctuation, emoji) with
-
- Collapse repeated
-, trim leading/trailing -
- Examples:
注意力机制 → 注意力机制, Self-Attention 详解 → Self-Attention-详解, Why? → Why
Tool usage
- Write: only for the 3 output files
- Read: for the content-format reference and any existing chapter files (style consistency)
- Glob: to check file existence
- No Bash, no Edit during this skill
References (read when needed)
- content-format.md — full Markdown/quiz.json/concepts.json schema. READ THIS before writing.
- examples.md — worked example of a complete chapter + quiz.json + concepts.json. Read if you want a concrete template to mirror.
- callout-format-spec.md — EXACT format for
[!question], [!quiz], [!answer] callouts, including nesting, collapsible markers, and option formatting. Read this before writing the learning elements.
Style continuity
After onboarding or after writing chapter 1, re-read the most recent *.md file in the project. Match its:
- Heading style (e.g.,
## vs # for sections)
- Mermaid conventions (sequence vs flowchart)
- Voice (casual vs formal)
- Length per section
Inconsistent style between chapters is jarring. Consistency matters more than variety.
Failure modes
- API rate limit / timeout: stop, return what you wrote so far, let host decide to retry
- Write tool denied: usually means session has wrong permissions — abort and ask host to re-init session
- Format spec changes mid-session: read the spec again, don't cache
