Pages you can decide from.
A Claude Code plugin that turns what your agent did into one page you can read in minutes:
the answer first, a picture in every chapter, one question when you must decide, and checked before it reaches you.
See live examples · Install · What it makes · Roadmap · Changelog
Agents write more than anyone can read: long summaries, plans, diffs and status reports. When you have to approve something or choose between options, a wall of text costs attention you may not have, especially with ADHD or a short working memory.
Every page this plugin makes has the same shape:
- The answer, in one sentence, right under the title.
- At most three facts to keep in your head.
- At a glance: the page's own picture on the first screen, such as a status board, the steps of a procedure or the options side by side.
- One idea per chapter, each with a picture, each closing with one line to remember.
- A recap, and one question only when a decision is needed, with the recommended choice marked and what happens if you do nothing.
- Checked before you see it. A checker script runs on every page and the agent fixes each failure first: answer length, at most three keep facts, a picture per chapter, text contrast of 4.5 to 1 in light and dark, status colours that always carry a glyph, diagram labels readable on a phone, and the rules of each page type. In Claude Code a hook runs it at the end of every turn that wrote a page, so it cannot be skipped.
- The reader is in control. One Reading tools button holds skim mode, one chapter at a time, a reading ruler, text size, dark or light and keyboard shortcuts. Each chapter can be read aloud, and a link resumes where you left off. Nothing moves unless you ask.
- Answer by tapping. A decision page can end in tap-to-answer fields, and a ballot puts one decision per card, pictured or in words, with a Pick all ★ button and warning chips such as "Can't undo". You copy every answer back to the agent in one paste, and a gather page collects answers from several readers, which a merge tool combines.
- One file, offline, private. Each page is a single HTML file. No server, no account, no tracking. It works on a phone and prints cleanly.
Every kind of page the plugin makes has a working example. Open one, tap its answers, switch it to dark, or read it on your phone. All of them are on the examples page, grouped by the job you have.
 Decision Three rulings, answered by tapping |  Ballot Four decisions on one phone screen |  Compare Three options against five criteria |
 Spec Approve or hold one feature |  Playbook A plan for one risky change |  Status Where a release stands, and its blocker |
 Portfolio Six projects, the urgent ones first |  Roadmap This plugin's now, next and later |  Release What shipped in 1.8.0 and 1.8.1 |
 Incident What broke, why, and what stops a repeat |  Handover Work in flight, claims kept apart |  Explainer Why every page opens with the answer |
 Teach A system in layers, for a newcomer |  Tour How to read a page, on real screens |  Research Findings and how sure each one is |
 Field guide A reference to look things up in |  Atlas How this repository fits together |  Runbook A release in 11 checked steps |
 Pull request A change, before you read the diff |  Questionnaire Six questions, answers in one paste |  Public The site home: promises, with proof |
Examples about the notes app use made-up data. The plugin's own pages (release, pull request, runbook, explainer, tour, atlas, roadmap) use real facts from this repository. Every page passes the plugin's checker. The gallery shows each building block on its own.
In Claude Code:
/plugin marketplace add ariasr47/html-explainer-skill
/plugin install html-explainer@html-explainer-skill
Restart Claude Code, then ask: "Make an html explainer for this spec."
Node 18 or newer runs the checker; nothing else installs. The install guide covers installing from a shell, setting it up for a whole team, updating, other agents such as Codex, Cursor, Gemini CLI and Copilot, and what to do when a skill does not start.
Ask in plain words. The agent picks the page type, writes the page from the template, runs the checker, saves it under docs/explainers/ and gives you the link.
| When you need to | Ask it like this | Page types |
|---|---|---|
| Decide | "Make an html explainer for the three decisions you need from me." | decision, compare |
| Know where things stand | "Explain where we are with the project as an html explainer." | status, release, incident, pr, portfolio |
| Approve a plan | "Turn this spec into an html explainer I can approve." | spec, roadmap, research, playbook |
| Hand over or teach | "Write a handover page for whoever picks this up." | handover, teach, tour |
| Look things up | "Make a field guide to this field that I can search later." | field-guide |
| Follow a procedure | "Make a runbook page for the release steps." | runbook |
| Tell customers | "Explain to customers what happens to the file they upload." | public |
| Ask a group | "Make a page that asks my team these questions and collects their answers." | gather (11 modes, including ballot) |
| Map a codebase | "Write a backend architecture atlas for this repository." | atlas |
To call a skill directly, type /html-explainer:html-explainer <topic>, /html-explainer:explainer-gather <topic> or /html-explainer:explainer-atlas <layer>.
To bring a page made with an older release up to the current design, ask: "Upgrade this page to the current html-explainer design." The agent runs upgrade.mjs, which keeps your content and saves a backup.
Seventeen page types, each with its own chapters, required components and checker rules
| Type | When |
|---|---|
| decision | You must rule on options a session poses. |
| status | You need to know where things stand and what comes next. |
| spec | You must approve a feature before it is built. |
| release | You need to know what shipped and what to do differently now. |
| research | You need findings and how far to trust each one. |
| handover | A session or a person takes over work in progress. |
| portfolio | You own several projects and need all of them at once. |
| public | The reader is a customer who needs to know what the product does for them. |
| teach | A newcomer must learn one system well enough to work with it. |
| incident | Something broke: what happened, why, what is fixed, and what stops a repeat. |
| pr | A reviewer must understand a pull request before reading its diff. |
| runbook | Someone follows a procedure and must know after each step whether it worked. |
| compare | You choose between options measured on the same few criteria. |
| roadmap | What is under way now, next and later, and what depends on what. |
| tour | How a product works, step by step, on its real screens. |
| playbook | You rule on a plan for one risky, multi-step change. |
| field-guide | You need to get oriented in a whole field once, then look things up. |
Full definitions: skills/html-explainer/references/types.md.
Eleven ways to ask and collect with explainer-gather
collect, confirm, choose, ballot, prioritise, annotate, check, protocol, pilot, readout and recurring. Answers save in the reader's browser until they copy them as Markdown or JSON or download a file. merge.html combines any number of copies, grouped by question, and exports Markdown, JSON or CSV. Details: references/modes.md.
Architecture atlases with explainer-atlas
A folder with index.html, atlas.css and atlas.js that maps one layer of a codebase: backend, frontend, data, infrastructure or the whole system. Every claim that names code carries a file and line anchor, current, dormant and target states stay visually apart, and anchors.mjs confirms each anchor exists at the recorded revision.
Japanese pages
With <html lang="ja"> the template switches to BIZ UDPGothic, a looser line height, strict line breaking and no italics, and the checker counts characters instead of words. translate.mjs turns a finished English page into a Japanese one with the same layout and question ids, so answers in both languages merge.
Cool fog paper, deep navy ink, one cobalt for "you are here", four meaning colours (green done, amber caution, red blocked, purple your choice), and yellow for anything you are asked to remember. Colour is never the only signal. Lexend for headings, Atkinson Hyperlegible Next for body text, 18 px base, 62-character lines, left aligned. Dark mode follows your system. The full system is in references/design-system.md.
| Path | What it holds |
|---|---|
skills/html-explainer/ |
The core skill: template, gallery, checker, page types and writing rules |
skills/explainer-gather/ |
Pages that ask and collect, the merge tool and the ballot example |
skills/explainer-atlas/ |
Architecture atlases and the anchor checker |
docs/ |
The public site, the install guide, screenshots and planning history |
.claude-plugin/ |
Plugin and marketplace manifests |
tools/check-repo.mjs |
The checks CI runs on every change |
Each skill folder is self-contained in the Agent Skills layout. CONTRIBUTING.md explains how to change the design, run the checks and release.
Next: the skill starts reliably when asked, pages get tested with outside readers, and the plugin gets its final name and a directory listing. See ROADMAP.md.
If you try a page, say how it went, especially if you or your reader has ADHD. That feedback decides what gets built.
MIT. Fonts load from Google Fonts under the SIL Open Font License and are optional; pages fall back to system fonts.