explainer-book

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

Design, write, and validate chapter-based learning materials (<topic>-book/01-quickstart.md, 02-….md …) that cannot fit into a single quick-study guide, tailored to the reader persona. verify-book.mjs checks the mapping between per-chapter learning objectives and comprehension checks, the ordering that prevents concepts from being used before they are introduced, chapter reading-time budgets, exercises that “fail when incomplete and pass with the answer,” and the chapter dependency graph generated from book.json; explainer’s verify-doc.mjs checks each chapter’s outputs, diagrams, and HTML. Use when the user asks for a book, a tutorial series, a course, “learning materials,” “tutorial,” “hands-on,” “turn it into a book,” “organize it into chapters,” “start with 01-quickstart,” or when an explainer crash course would exceed ~20 minutes or needs exercises.

3installs

Sourcemizchi/explainer

Added on2026-10-01

NPX Install

npx skill4agent add mizchi/explainer explainer-book

SKILL.md Content (Chinese)

View Translation Comparison →

explainer-book

The book edition of

explainer

. When a single quick-study guide (within 20 minutes, one example at a time) is not enough, divide the material into chapters and make it something readers learn by doing.

Use the persona, diagram, and validation mechanisms from

explainer

unchanged. Read

../explainer/SKILL.md

first. This skill adds whole-book design and validation.

The scripts are located in this skill’s directory (below

<skill>

), under

scripts/

.

verify-book.mjs

calls the adjacent

explainer

skill’s

scripts/verify-doc.mjs

. Place the two skills in the same location. Set up dependencies in the same way as the “Setup” section of

explainer

.

When to make a book

Make it a book if any of the following applies. If none applies, write it as a single

explainer

document.

Reading takes more than 20 minutes
Readers need hands-on exercises (reading alone does not enable them to “make a determination”)
Concepts have a dependency order (B cannot be understood without A)

Structure

<topic>-book/
  README.md            目次：想定読者、章ごとの「読み終えたらできること」、章の依存図、再現方法
  book.json            章の順序・学習目標・導入する概念・演習（references/book-json.md）
  01-quickstart.md     最初の章は必ず quickstart：理論の前に、動く結果に着く
  02-….md              concept：1 章 1 つの判定を身につける
  03-….md              practice：演習が中心
  checks.json          本文の出力と演習の答えを再生成するコマンド（explainer と同じ形式）
  examples/            章で使うコード・モデル。演習の出発点と答えを別ファイルにする
  figures/             book-map.*（生成）と各章の図

Procedure

1. ペルソナ     explainer と同じ。「怪しいところ」から、本全体の問いを 1 つ決める
2. 目標を並べる  問いに答えるために読み手ができるべき判定を 3〜6 個。1 章に 1〜2 個
3. 概念の順序   各判定に要る概念を書き出し、どの章で導入するかを決める（book.json introduces / requires）
4. 実物を先に   各章の例と演習を作り、走らせる。演習は「出発点で落ちる」「答えで通る」を両方確かめる
5. 章を書く     explainer の writing.md の型。章の冒頭に所要時間とゴール、末尾に理解度チェック
6. 検証         node <skill>/scripts/verify-book.mjs <book-dir> [--write]
7. 読ませる     first-reader で、少なくとも 01-quickstart と演習の章を、ペルソナ本人に読ませる（explainer の手順 8）
8. 渡す         dist/index.html と、各章の 1 行要約。未検証の点を明記

2. Learning objectives

Write each objective in terms of “what the reader can determine after finishing.” Do not write “understand …,” because it cannot be assessed.

Bad example: “Understand CTI”
Good example: “When CTI appears, use TLC to determine whether the conditions are merely too weak or whether the property is actually violated”

Attach at least one comprehension-check question to every objective (

<!-- quiz: <objective-id> -->

).

3. Concept order

Put concepts the persona already knows in
```
assumed
```
. Do not explain them.
For every other concept, exactly one chapter
```
introduces
```
it. If it appears in the body of an earlier chapter, validation fails.
Put concepts that a chapter depends on in
```
requires
```
. These become arrows in the dependency graph.

4. Exercises

Run the exercise answers as well and verify them. An exercise with an incorrect answer teaches the mistake.

kind	Example	Check
`write`	Have the reader write conditions, functions, or configuration	`starter` : A check that confirms the starting point fails when run unchanged. `answer` : A check that confirms it passes with the answer
`check`	Have the reader run a tool to make a determination	`answer` : A check that regenerates the output supporting the determination

Put the answer in a
```
<details>
```
element in the same section as the exercise.
Place
```

```
before the exercise.

5. Writing chapters

In addition to the

explainer

style, follow these rules:

In the opening block quote, include the estimated time required, the goal (the chapter’s objectives), and the prerequisites (previous chapters).
At the end, link to the next chapter (
```
→ [02 …](02-….md)
```
). In HTML, navigation to the previous and next chapters and to the table of contents is added.
When using a result from a previous chapter, refer to it by chapter number (“the three checks in Chapter 1”). Do not repeat the same explanation.
Replace results derived through manual reasoning (“this state is unreachable,” “this happens in this order”) with tool output. Manual reasoning can be wrong.

6. Validation

node <skill>/scripts/verify-book.mjs <book-dir>           # 検査
node <skill>/scripts/verify-book.mjs <book-dir> --write   # 依存図と SVG を作り直す

The whole-book checks are:

Check	Failure condition
chapters	A chapter file is missing. The `NN-` number does not match the order in book.json. Chapter 1 is not quickstart.
objectives	An objective has no quiz. A quiz explicitly refers to an objective in a different chapter.
concepts	A concept is used in a chapter before it is introduced. A `requires` concept has not been introduced. A concept declared in `introduces` does not appear in the body.
budget	The estimated body reading time (500 characters/min + 15 lines of code/min) exceeds `minutes` .
exercises	A marker is missing. The answer is not in `<details>` . A check is missing from checks.json. A `write` exercise has no failing starter.
map	`figures/book-map.*` does not match book.json. README has no diagram.

Afterward, pass the README and every chapter to

verify-doc.mjs --pages

. It checks output quotations, diagrams, links between pages, and the vlmkit gate for every page.

Keep fixing the material until it displays

book verdict: VERIFIED

.

Things not to do

Add chapters and dilute the material. If a chapter has no objective, or its comprehension check does not ask about the objective, the chapter is unnecessary.
Do not run the exercise answers.
Do not repeat the previous chapter’s explanation. Refer to it by chapter number.
Do not reword things merely to pass validation. If a concept check fails, move the definition to an earlier chapter or revise the chapter order. Do not evade the check with synonyms.

Files

Path	Contents
`references/book-json.md`	All fields of book.json
`scripts/verify-book.mjs`	Whole-book validation → verify-doc.mjs
`../explainer/scripts/build-html.mjs`	Builds multiple pages into HTML, with a table of contents and previous/next chapter navigation

explainer-book

NPX Install

Tags

SKILL.md Content (Chinese)

explainer-book

When to make a book

Structure

Procedure

2. Learning objectives

3. Concept order

4. Exercises

5. Writing chapters

6. Validation

Things not to do

Files