explainer
Human understanding is the bottleneck.
Agents write quickly, but readers cannot keep up.
This skill delivers only the delta relative to what is already in the reader's head, through verified claims and diagrams.
There are two differences from ELI5.
- Treat the reader as one real persona, not a type such as “5-year-old” or “manager”. Do not write about what they already know.
- Check claims with tools. Replace “I wrote this myself and no longer feel confident about it” with the green light from a passing check.
If reading takes more than 20 minutes, exercises are required, or concepts have a sequence, use the
chapter structure.
Preparation (first time only)
The scripts are in this skill's directory (referred to below as
), under
.
Install the dependencies in the repository where the material will live. Node 24 or later is required.
sh
npm i -D @mizchi/vlmkit @mizchi/vlmkit-anim marked playwright
When using Mermaid diagrams (
), also install
. When using icons, also install
and
.
When covering examples of formal methods, also install TLC (Java 11+), Apalache (Java 17+), and
.
looks for
(
) and
(
) in the repository's
directory.
Procedure
1. Persona Read personas/<id>.md at the repository root. If it does not exist, create a provisional file before asking questions
2. Narrow the question Write 1–3 questions describing what the reader should be able to determine after finishing
3. Determine the delta Do not write anything listed under the persona's “Knows”. Center the body on the “Unsure” items
4. Build real artifacts For every claim, first create and run an executable example (code, model, or command)
5. Write Follow the pattern in references/writing.md. Paste outputs; do not retype them
6. Diagrams Follow references/figures.md. Create the fact sheet (*.expect.json) first and the diagram second
7. Verify Run node <skill>/scripts/verify-doc.mjs <doc-dir> until the result is VERIFIED
8. Reader test Use the first-reader skill with the persona as the reader. See where they drop off and what remains the next day
9. Deliver Provide the HTML (dist/index.html) and a summary. Mark anything that could not be verified as “Unverified”
1. Persona
Create it using the template in
. There are two sources of information.
- Questions: If you can ask the person, ask up to five questions. “What are you using now?” “Where did you get stuck?” “How much time do you have to read?” “What form of explanation do you prefer (code first or diagrams first)?” “What do you want to determine after reading this?”
- Public information: GitHub repositories, blogs, and conference presentations. Attach a URL to every claim and separate facts from inferences.
The persona file must be written before waiting for an answer. For a new reader, create
at the repository root before asking any questions—not inside the material's directory, so it can be reused for future material.
Even if asking a question pauses the response, create the file first.
Write everything established by the request under “Facts,” everything else under “Inferences,” and list the questions under “Unconfirmed.”
- If you can ask the person, ask the questions and pause. When the answers arrive, rewrite the inferences in the file as facts and continue.
- If no answer can be obtained—such as during a non-interactive run, when the person cannot be contacted, or when there is no time—continue with the inferences as they are.
At the beginning of the material, state your assumptions and the questions you want to confirm under “Intended Reader.”
- Do not put background information that is not in the request—such as years of experience, tools currently used, or the person's difficulties—under “Facts.”
When asking a new reader and pausing for their response, use the following format.
Before writing the response, use Write to create
; do not ask the questions without first invoking the tool.
<Reader>'s persona has been saved provisionally at personas/<id>.md (only facts established by the request were recorded as facts, and everything else as inferences).
Please confirm <N> points that could change the content of the material.
1. <Question whose answer could change the main focus of the material>
2. …
If there is no answer, I will proceed with the following assumptions: <assumption in 1–2 lines>
Even when proceeding on the basis of inferences, briefly include the same two items in the response: the assumptions and the questions for the person. If you only write them to the file, they will not reach the reader.
The most important field is “Unsure.”
Being able to use a tool and being able to interpret the meaning of its result are different things.
Find that difference and make it the core of the material.
2–3. Questions and the Delta
Give the material a title in the form of the reader's question, such as “What do OK results from Z3 and TLA+ actually guarantee?”
There is only one test for excessive length.
Remove any explanation listed under the persona's “Knows” section.
If the persona already uses the tool, do not include its introduction, installation instructions, or general theory.
4. Build the Real Artifact First
Write claims from the results of running something. Never do it in the other order.
- Code behavior → the smallest runnable example and its output
- “It breaks under this condition” → a model that produces a counterexample (Z3, TLC, etc.) and a test that reproduces that counterexample as a real artifact
- Structure → an import graph or state graph emitted by a tool, which becomes the fact sheet
If a claim cannot be checked by execution, write “Unverified” in the body. Do not include it in a diagram.
5. Writing
Follow
. The main points are:
- Begin with “Intended Reader” and “Omitted.” The reader should be able to determine in 10 seconds whether the material is for them.
- Put an “At a Glance” table at the beginning. The body then expands each row of the table.
- Keep each paragraph to one or two sentences and each section to one example.
- Put
<!-- output: <check-name> -->
- End with a comprehension check of three to five questions, with the answers in . If the reader cannot answer, that section has not communicated its content.
6. Diagrams
Follow
. Create a diagram only in these cases:
- There are four or more elements and relationships between them
- There is a temporal sequence
- There is a containment relationship
Create diagrams as vlmkit-anim scenes (JSON). If there is no applicable kind for a conceptual diagram, use Mermaid if Mermaid is sufficient, D2 if more structure is needed, or write SVG / HTML directly for a free-form diagram that D2 cannot represent. Render and check each one with
, then visually review the resulting sheet and edge sheet, with one arrow highlighted at a time. Because D2 and Mermaid determine the layout automatically, if the result looks unnatural, use
scripts/figure-variants.mjs
to compare candidates and choose again; see “Hand-drawn Diagrams” in
.
Use
to find icons such as databases, servers, and product logos, and place them beside the diagram. Icons can be used with D2, Mermaid, or SVG. See “Icons” in
.
There are three checks for a vlmkit-anim diagram.
- : Compare it with the fact sheet. The fact sheet is generated from tool output such as a TLC state graph or import graph.
- : Check for overlaps and overflow.
- : Emit an SVG and inspect it visually once.
7. Verification
In
, define the commands that regenerate the outputs quoted in the body and the expected lines.
node <skill>/scripts/verify-doc.mjs <doc-dir> # Check
node <skill>/scripts/verify-doc.mjs <doc-dir> --write # Redraw the diagram SVGs
- Whether the expected lines appear in order in the output of each command in
- Diagrams: whether
vlmkit-anim check --expect
- Body content: whether quoted and content matches the real artifacts and whether images exist
- HTML: on the version with expanded, using the strict mode, and
For each failed line, report what failed, where it failed, and how to fix it on one line.
Fix the issue and rerun the checks until the verdict is
.
The limit is five rounds. If a claim still does not pass, remove it from the body or mark it as “Unverified.”
8. Reader Testing (first-reader)
What
guarantees is only that the claims are
correct.
Whether the reader can
finish the material and still remember it the next day must be tested with the bundled
skill.
- Reader roles:
- Sympathetic role: the person in . Use “Already Knows” as the priors and “How They Read” as the patience budget.
- Skeptical role: assign the role from the context in which the material will be delivered, such as a PR review or a link in Slack.
- Intended gist: the material's “At a Glance” table and the persona's questions from step 2.
- Judgment: If a recall answer differs from the intended gist, that section has not communicated its content.
If the skim gate does not pass, or both readers drop out during the first half, treat it as a structural problem. Fix the structure before making line-level edits.
- The writer (this skill) makes the fixes: first-reader does not rewrite the material. After receiving the reader's testimony, the explainer decides where and how to fix it.
After making fixes, rerun and use in first-reader to have the same reader read it again.
- Caution: The writer has already read the entire draft. The reader must always be a fresh subagent, following the first-reader procedure.
The way counts trust signals is designed for English and will produce almost no signals for Japanese material. For Japanese, judge the trust ledger through your own read-through.
is created next to the material. Do not manage it with Git.
9. Delivery
- In chat, provide a three-to-five-line summary and . Also include the verification result: whether it is VERIFIED and what, if anything, remains unverified.
- In a PR, describe the diff using the same format and attach the diagram's SVG. Put the comprehension check at the end of the PR body.
When Explaining a PR
Ask “What will change if this PR is merged?” and “What could break?”
Order the explanation by the flow of the explanation, not by file order; this is a literate diff.
There are two real artifacts.
- The change map produced by
vlmkit-anim pr --base origin/main
- The smallest example whose behavior changes before and after the change, selected from the added or modified tests
Things Not to Do
- Do not retype outputs. Paste them. The validation script will compare them.
- Do not draw diagrams from memory. Create the fact sheet first. If the diagram conflicts with the fact sheet, the diagram is wrong.
- Do not explain what the reader already knows. Remove anything listed under the persona's “Knows” section.
- Do not overstate a green result. When saying “the check passed,” state which check passed and the scope in which it passed.
Files
| Path | Contents |
|---|
| Persona template and instructions for creating one |
| Material structure, style, and instructions for creating comprehension checks |
| Mapping from questions to diagram types, fact-sheet creation, and the vlmkit-anim workflow |
| Verification of checks, diagrams, quotations, and HTML |
| README.md → self-contained HTML with SVGs inlined |
| Renders and checks manually written SVG / HTML / D2 / Mermaid diagrams for overlaps, overflow, border or line intersections with text, text that is too small, and fact-sheet consistency; also produces sheets for visual review |
scripts/figure-arrows.mjs
| Checks arrow readability, including two arrows running alongside or overlapping each other, arrows piercing a box, crossings, detours, and reversed direction; also creates sheets with one edge highlighted at a time. Used by figure-check |
scripts/figure-variants.mjs
| Renders and scores layout candidates for D2 / Mermaid using TALA seeds, ELK, dagre, and orientation |
| Finds icons in the Iconify sets lucide and logos, arranges candidates on one sheet, places an icon beside a diagram, and records its source in ICONS.md |
| Converts a TLC state graph and counterexample into a vlmkit-anim state-machine scene and fact sheet |