English | 日本語

Skills and tools for explaining concepts from an AI to a human.

Coding agents now write faster than people can understand what they wrote (Geoffrey Litt, Understanding is the new bottleneck). This repository is for writing, for one reader, only what that reader does not already know, with claims and figures checked by tools.

As a Claude Code plugin (this repository is itself a plugin marketplace; one plugin, explainer, contains three skills):

/plugin marketplace add mizchi/explainer
/plugin install explainer@explainer

From a shell: claude plugin marketplace add mizchi/explainer and claude plugin install explainer@explainer. To update an installed copy: claude plugin marketplace update explainer and then claude plugin update explainer@explainer. Changes are listed in CHANGELOG.md.

The skills can also be installed with npx skills or APM (checked with skills 1.7.0 and apm-cli 0.32.0; both put the three skills in .claude/skills/, byte-identical to this repository).

npx skills add mizchi/explainer --skill '*' -a claude-code   # --list to see the skills first
apm install mizchi/explainer --target claude

Install all three. explainer-book runs explainer's verify-doc.mjs from the sibling directory (../../explainer/scripts/).

Install the scripts' dependencies in the repository that holds the documents (npm i -D @mizchi/vlmkit @mizchi/vlmkit-anim marked playwright, Node 24+). Add mermaid if you use Mermaid figures, and @iconify-json/lucide @iconify-json/logos to use icons. first-reader needs only the Python 3 standard library.

first-reader is bundled from Shubhamsaboo/awesome-llm-apps (Apache-2.0; see skills/first-reader/LICENSE and NOTICE). feed.py counts words differently so that Japanese drafts can also be read one paragraph at a time.

persona ─→ question ─→ real artifacts (runnable examples, models) ─→ text + figures ─→ verify ─→ HTML
  │                          │                                          │               │
  questions + public info    paste outputs, never retype               vlmkit-anim     verify-doc.mjs
                                                                        fact sheets     (checks / figures / quotes / vlmkit)

• Persona (personas/): what the reader already knows, and where their understanding is shaky. It decides what to leave out.
• Skills (skills/explainer/): the procedure, writing style, how to choose a figure, how to verify.
• Verification: every quoted output is re-run from checks.json and compared with the text. Figures are checked against fact sheets with @mizchi/vlmkit-anim, and pages go through vlmkit check integrity / check a11y contrast.

ELI5 treats the reader as a type (age, job). This skill treats one real person as the reader, and checks what it writes with tools.

These are instructions actually given in the conversation that built this repository (excerpts, translated from Japanese; the originals are in README.ja.md), and the figures that came out. Every figure was either checked against a tool's output or passed figure-check.mjs, and was looked at and fixed by eye. The images are rebuilt with npm run readme:images. The figures themselves are in Japanese, the language of the documents.

As a test, build a persona of mizchi from public information, and write an explanation of formal methods that I can understand. I tried to write material on Z3 and TLA+, but lost confidence as I wrote it.

Actually run the induction check with Apalache as well, and verify it.

• A: all reachable states of Counter, generated from TLC's state graph by tlc-to-scene.mjs. The orange D D | 1 is the final state where one update was lost.
• B: for CounterAtomic, reachable states ⊂ NoLostUpdate ⊂ all states. The contents of the "reachable" box are checked against the states TLC enumerated. Red is the counterexample to induction (CTI) that Z3 found: an unreachable state that satisfies NoLostUpdate and leaves it in one step.
• C: which states each check looked at (hand-written SVG).
• Document: docs/formal-methods/README.md

I want to add a skill for making a substantial course that doesn't end as a short text. Like foo-book/01-quickstart.md.

• A: chapter dependency map, generated from book.json; the same data drives the check that no concept is used before it is introduced.
• B: triaging a counterexample to induction (CTI), in D2 + ELK.
• Book: docs/inductive-invariant-book/

Using TALA and D2, make a cheat sheet from samples that sorts out which drawing tool to use when.

• The same arch.d2 drawn by A: TALA, B: ELK, C: dagre.
• Without a direction, A put the entry points (browser, app) at the bottom. In B and C, lines cross the container titles (エッジ, サービス, データ).
• Cheat sheet: docs/figure-cheatsheet/README.md

Write down when to use Mermaid. Use Mermaid when it is enough; for other structured patterns consider D2; for free-form drawings D2 can't express, consider SVG or HTML.

• A: a figure Mermaid is enough for (a procedure with a back edge). No ✗ from the checks.
• B: in Mermaid, once a node inside a subgraph links to a node outside it, the subgraph's direction TB is ignored and everything goes into one row.
• C: the same links in D2 + TALA keep the inside vertical.

With D2 and Mermaid, when you actually render from the semantics, the result is sometimes clearly unnatural, or the arrows are hard to read. I want a flow that checks these visually and fixes them.

The edge sheet (made by figure-check.mjs): each arrow drawn in red in turn, with the others faded. The two framed in red failed the machine check "browser→CDN and browser→API Gateway run together for 222px": the split reads as an arrow between CDN and API Gateway.

Layout candidates (made by figure-variants.mjs): TALA seeds 1–6, ELK and dagre, sorted by penalty. Only seeds 6 and 5 have no ✗. You choose among those by eye and record why in a comment in the source.

I want to bring in an SVG icon set and be able to use it.

• icons.mjs searches the installed Iconify sets (Lucide line icons, ISC; logos of technologies, CC0), lays candidates out in one image to choose from, and writes the chosen icon next to the figure, recording its source and license in figures/icons/ICONS.md.
• A: D2 + ELK. Line icons inside the boxes, and logos (as shape: image, sized explicitly; unsized, the Postgres logo became the largest thing in the figure) for the products themselves.
• B: Mermaid. figure-check.mjs registers the installed sets with Mermaid, so lucide:user or logos:postgresql can be used directly.
• figure-check.mjs fails images that are not embedded in the figure (a missing file or wrong path) and D2 icons without a recorded source.

• Persona: personas/mizchi.md (built from public information; facts and guesses kept apart)
• Document: docs/formal-methods/README.md "Reading the green: what did Z3's and TLA+'s 'OK' actually guarantee?"

Building the persona showed the reader was not a beginner at formal methods. They already run about ten verifiers through agents. So the document is not a tool tutorial; it is limited to criteria for judging, yourself, what a checker's result guaranteed.

When one document is not enough, the explainer-book skill splits it into chapters.

• Book: docs/inductive-invariant-book/ "Finding inductive invariants yourself" (3 chapters)
  • 01-quickstart.md: show with Apalache's three checks that an invariant holds for any number of steps
  • 02-reading-cti.md: use TLC to tell whether a counterexample to induction (CTI) means a weak invariant or a bug
  • 03-strengthening.md: exercises in reading off the condition to add from a CTI
• Whole-book checks (verify-book.mjs): learning objectives matched to quizzes, no concept used before it is introduced, reading time per chapter, exercises whose starting point fails and whose answer passes, the chapter dependency map

• Document: docs/figure-cheatsheet/README.md "Which figure, with which tool"
• Mermaid when it is enough; D2 (TALA / ELK / dagre) for structures Mermaid can't handle; SVG / HTML for free-form figures that don't fit D2. vlmkit-anim for figures that copy a tool's output. Includes a comparison that draws the same samples with Mermaid and D2's three engines (samples/compare.mjs).
• Measured findings: the direction inside a container is ignored by Mermaid once inner nodes link outside, and always silently ignored by ELK and dagre; only TALA kept it. TALA's layout changes completely with the seed, and it slows down sharply as boxes are added.

npm install            # Node 24+ (required by vlmkit)
npm run setup:tla      # fetch TLC and Apalache into .tools/ (Java 17+)
npm run setup:d2       # fetch D2 (TALA / ELK) into .tools/, for hand-written D2 figures
npm run verify         # verify docs/formal-methods → verdict: VERIFIED
npm run build          # build docs/formal-methods/dist/index.html
npm run verify:book    # verify docs/inductive-invariant-book → book verdict: VERIFIED
npm run build:book     # build docs/inductive-invariant-book/dist/*.html
npm run verify:cheatsheet   # verify docs/figure-cheatsheet (re-runs the engine comparison, ~2 min)
npm run figure -- docs/formal-methods/figures/coverage.svg   # render and check one figure; look at the sheet it prints
npm run figure:variants -- docs/figure-cheatsheet/figures/arch.d2   # lay out D2 / Mermaid candidates with scores; compare and choose
npm run test:figures   # regression tests for figure-check
npm run readme:images  # rebuild the README images (docs/readme/*.png)
npm run icons -- search database --sheet /tmp/icons.png   # find icons and look at the candidates; then: npm run icons -- add lucide:database

evals/<case>/prompt.md and graders/*.md are cases for claude plugin eval. Each case runs with and without the plugin, and the score difference (Δ) is reported.

claude plugin eval . --trust-plugin --allow-tools Bash Write Edit Agent -j 4

The latest results, and caveats on reading them, are in evals/RESULTS.md (in Japanese). In the 2026-09-25 to 27 runs, using only graders that don't depend on a shell, the Δ values were:

Reporting code it could not run happened in 6 of 6 runs with the skill and 1 of 6 without. When the reader's information was given (in the request or in a persona file), skipping known material happened even without the skill. In that environment the shell did not work inside the eval sandbox, so graders that look at code execution were disabled.

Unit tests for the first-reader scripts: python3 tests/first-reader/test_first_reader.py and test_cjk.py.

MIT. skills/first-reader/ keeps the license of its source (Apache-2.0; see skills/first-reader/LICENSE and NOTICE). Icons placed in documents keep their sets' licenses (Lucide: ISC, logos: CC0; logos are their owners' trademarks), recorded per icon in figures/icons/ICONS.md.