explainer-book
1 本の速習資料では収まらない、章立ての学習資料（ -book/01-quickstart.md, 02-….md …）を、読み手のペルソナに合わせて設計・執筆・検証する。章ごとの学習目標と理解度チェックの対応、概念を導入より前に使わない順序、章の読了時間の予算、「未完成なら落ち、答えなら通る」演習、book.json から生成する章の依存図を、verify-book.mjs で検査し、各章の出力・図・HTML は explainer の verify-doc.mjs で検査する。Use when the user asks for a book, a tutorial series, a course, "学習資料", "チュートリアル", "ハンズオン", "本にまとめて", "章立てで", "01-quickstart から", or when an explainer crash course would exceed 20 minutes or needs exercises.
- Installs
- 492
- Last 24h
- +10
- Trending rank
- #8800
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/mizchi/explainer --skill explainer-book- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads explainer-book automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
explainer-book
explainer の本版。
1 本の速習資料（20 分以内・例 1 つずつ）で足りないとき、章に分けて、手を動かして身につける資料にする。
ペルソナ・図・検証の仕組みは explainer をそのまま使う。先に ../explainer/SKILL.md を読むこと。
このスキルが足すのは、本全体の設計と検査。
スクリプトは、このスキルのディレクトリ（以下 <skill>）の scripts/ にあります。
verify-book.mjs は、隣の explainer スキルの scripts/verify-doc.mjs を呼びます。2 つのスキルは同じ場所に入れてください。
依存の入れ方は explainer の「準備」と同じです。
いつ本にするか
次のどれかに当てはまったら本にする。1 つも当てはまらなければ、explainer の 1 本で書く。
- 読了が 20 分を超える
- 読み手が手を動かす演習が要る（読むだけでは「判定できる」ようにならない）
- 概念に順序がある（A を知らないと B が読めない）
構成
<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.*（生成）と各章の図
手順
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. 学習目標
目標は「読み終えたら、何を判定できるか」で書く。「〜を理解する」は検査できないので書かない。
- 悪い例：「CTI を理解する」
- 良い例：「CTI が出たとき、条件が弱すぎるだけか、性質が本当に破れるかを TLC で判定できる」
各目標には、理解度チェックの問いを 1 つ以上付ける（<!-- quiz: <目標id> -->）。
3. 概念の順序
- ペルソナが既に知っている概念は
assumedに書く。説明しない。 - それ以外の概念は、ちょうど 1 つの章が
introducesする。その章より前の章の本文に出てきたら、検証が落ちる。 - 章が前提にする概念は
requiresに書く。依存図の矢印になる。
4. 演習
演習の答えも実行して確かめる。答えが間違った演習は、間違いを教える。
| kind | 例 | 検査 |
|---|---|---|
write | 条件・関数・設定を書かせる | starter：出発点のまま実行すると落ちることを確かめる check。answer：答えで通ることを確かめる check |
check | 道具を回して判定させる | answer：判定の根拠になる出力を再生成する check |
- 答えは、演習と同じ節の
<details>に入れる。 - 演習の前に
<!-- exercise: <id> -->を置く。
5. 章を書く
explainer の文体に加えて、次を守る。
- 冒頭の引用ブロックに、所要時間・ゴール（その章の目標）・前提（前の章）を書く。
- 末尾で次の章へリンクする（
→ [02 …](02-….md)）。HTML では前後の章と目次へのナビが付く。 - 前の章の結果を使うときは、章番号で参照する（「1 章の 3 つの check」）。同じ説明を繰り返さない。
- 手で推論した結果（「この状態には着けない」「この順序で起きる」）は、道具の出力に置き換える。推論は外れる。
6. 検証
node <skill>/scripts/verify-book.mjs <book-dir> # 検査
node <skill>/scripts/verify-book.mjs <book-dir> --write # 依存図と SVG を作り直す
本全体の検査：
| 検査 | 落ちる条件 |
|---|---|
| chapters | 章ファイルがない。NN- の番号が book.json の順と違う。1 章が quickstart でない |
| objectives | quiz が付いていない目標がある。quiz が他の章の目標を名指ししている |
| concepts | 概念を導入より前の章で使っている。requires が導入されていない。introduces と宣言したのに本文に出てこない |
| budget | 本文の推定読了時間（500 字/分 + コード 15 行/分）が minutes を超える |
| exercises | 印がない。答えが <details> にない。check が checks.json にない。write 演習に落ちる starter がない |
| map | figures/book-map.* が book.json と一致しない。README に図がない |
そのあと、README と全章を verify-doc.mjs --pages に渡す。出力の引用、図、ページ間リンク、各ページの vlmkit ゲートを検査する。
book verdict: VERIFIED になるまで直す。
やってはいけないこと
- 章を増やして薄める。 1 章に目標がない、または理解度チェックが目標を問わないなら、その章は要らない。
- 演習の答えを走らせない。
- 前の章の説明を繰り返す。 章番号で参照する。
- 検証を通すために言い換える。 概念の検査に落ちたら、定義を前の章に移すか、章の順序を見直す。同義語に置き換えて逃げない。
ファイル
| パス | 内容 |
|---|---|
references/book-json.md | book.json の全フィールド |
scripts/verify-book.mjs | 本全体の検査 → verify-doc.mjs |
../explainer/scripts/build-html.mjs | 複数ページを HTML に（目次・前後の章へのナビつき） |
FAQ
What does the explainer-book skill do?
1 本の速習資料では収まらない、章立ての学習資料（ -book/01-quickstart.md, 02-….md …）を、読み手のペルソナに合わせて設計・執筆・検証する。章ごとの学習目標と理解度チェックの対応、概念を導入より前に使わない順序、章の読了時間の予算、「未完成なら落ち、答えなら通る」演習、book.json から生成する章の依存図を、verify-book.mjs で検査し、各章の出力・図・HTML は explainer の verify-doc.mjs で検査する。Use when the user asks for a book, a tutorial series, a course, "学習資料", "チュートリアル", "ハンズオン", "本にまとめて", "章立てで", "01-quickstart から", or when an explainer crash course would exceed 20 minutes or needs exercises.
How do I install explainer-book?
Run npx skills add https://github.com/mizchi/explainer --skill explainer-book in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/explainer-book/ (personal) or .claude/skills/explainer-book/ (project).
Which AI agents can use explainer-book?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is explainer-book safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains explainer-book?
It is published by mizchi in mizchi/explainer. It has 492 recorded installs.
More from mizchi/explainer
explainer
mizchi/explainer
特定の読み手に向けて、概念・PR・設計を「冗長にならない水準」の速習資料として説明し、図と主張を道具で検証する。読み手のペルソナ（既に知っていること・知らないこと・読み方）を質問と公開情報から作り、その差分だけを書く。図は Mermaid / D2 で描いて事実シートに照らし、本文に引用するコード・出力は再実行して照合し、HTML は vlmkit のゲートに通す。Use when the user says "explain this to me / to ", "速習資料", "解説ドキュメント", "この PR を理解したい", "わかるように説明して", "I can't keep up with what the agent wrote", "この PR を が理解できるように説明して", or when a reviewer asks what a change does. Use it even for a small diff or a chat-only answer whenever a named reader (a reviewer, an on-call engineer, a teammate, a PM) is given. Also when model or analysis results (diagnostics, metrics, charts) must be explained to someone who decides on them, e.g. "このモデルを本番に出してよいか が判断できるように". Also when the user wrote an explanation themselves and lost confidence in it.
first-reader
mizchi/explainer
Beta readers for any draft, run by simulating how a real reader experiences it, moment by moment. A skim gate, a no-lookahead timed read producing an attention transcript with quit points, a recall test of what a reader remembers the next day, and a trust ledger of the implied author. Use when the user asks for a beta read, beta readers, test readers, human review, reader review, to read something like a human, to be a first reader, whether a piece holds attention or will actually get read, for a quick read of whether a busy skimmer would even open a post, what readers will remember or take away tomorrow, where readers stop reading or bounce, or why a draft still feels off or hollow after anti-slop or humanizer edits. Final gate before publishing; reports where the reading broke; never rewrites.
d2-diagram
mizchi/explainer
Open the skill to read its SKILL.md instructions.
d2-slides
mizchi/explainer
Open the skill to read its SKILL.md instructions.
Popular education & science skills
teach
mattpocock/skills
Teach the user a new skill or concept, within this workspace.
scaffold-exercises
mattpocock/skills
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
paper-context-resolver
lllllllama/rigorpilot-skills
Rigor Paper Context helper for README-first deep learning repo reproduction. Use only when the README and repository files leave a narrow reproduction-critical gap and the task is to resolve a specific paper detail such as dataset split, preprocessing, evaluation protocol, checkpoint mapping, or runtime assumption from primary paper sources while recording conflicts. Do not use for general paper summary, repo scanning, environment setup, command execution, title-only paper lookup, or replacing README guidance by default.
caveman-learn
juliusbrussee/caveman
Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem.
gsap-plugins
greensock/gsap-skills
Official GSAP skill for GSAP plugins — registration, ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, SVG and physics plugins, CustomEase, EasePack, CustomWiggle, CustomBounce, GSDevTools. Use when the user asks about a GSAP plugin, scroll-to, flip animations, draggable, SVG drawing, or plugin registration.
teach-impeccable
pbakaus/impeccable
DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill.