mizchi / explainer

# 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):
 [code] 
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).
 [code] 
Install `explainer`, `explainer-book` and `first-reader` together: `explainer-book` runs `explainer`'s `verify-doc.mjs` from the sibling directory (`../../explainer/scripts/`).
| Skill | When to use it |
|---|---|
| `explainer` | A crash course for one reader. Claims and figures are checked with tools |
| `explainer-book` | A chaptered course. Checks learning objectives, concept order, reading time and exercises |
| `first-reader` | Has simulated readers read a draft one paragraph at a time before publishing. Reports where they drop off and what stays with them the next day. Does not rewrite |
| `d2-diagram` | A D2 diagram laid out by TALA, read in the terminal, and held to a fact sheet by `d2-facts.mjs` (what the picture draws, not what the text says) |
| `d2-slides` | A slide deck from one Markdown file with a D2 fence per figure, built to HTML and checked with vlmkit's gates |
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.
For documents in Japanese, also install yomiyasu (MIT): `verify-doc.mjs` then runs its linter over the prose and lists patterns common in AI-written Japanese (too much bold or bulleting, metaphorical verbs) as things to look at. It is not bundled (`npx skills add nanaism/yomiyasu`).
`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
 [code] 
- **Persona** (`personas/`): what the reader already knows, and where their understanding is shaky. It