d2-slides

explainer

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.

Install

As a Claude Code plugin (this repository is itself a plugin marketplace; one plugin, explainer, contains five 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 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 explainer, explainer-book and first-reader together: explainer-book runs explainer's verify-doc.mjs from the sibling directory (../../explainer/scripts/).

The last two came from mizchi/vlmkit. Figures are Mermaid or D2 text checked by figure-check.mjs; the animation package @mizchi/vlmkit-anim and its two skills were removed in 0.5 (see CHANGELOG).

Install the scripts' dependencies in the repository that holds the documents (npm i -D @mizchi/vlmkit marked playwright mermaid, Node 24+). Add the d2 CLI if you use D2 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.

What it does

persona ─→ question ─→ real artifacts (runnable examples, models) ─→ text + figures ─→ verify ─→ HTML
  │                          │                                          │               │
  questions + public info    paste outputs, never retype               Mermaid / D2    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 (Mermaid / D2 / SVG / HTML) are checked against fact sheets and for overlap, clipping and arrow readability by figure-check.mjs, 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.

Instructions, and the figures they produced

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.

1. A crash course on formal methods

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 as Mermaid by tlc-to-mermaid.mjs. The thick-bordered states are the ones the correct order and TLC's counterexample walk; 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

2. A chaptered course

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/

3. Which figure tool to use

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.

4. Render, look, and fix the layout

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.