html-explain
Skill2 starsChanged 26 days agoMITView on GitHub
Explain a topic as one HTML page that teaches it the way a good teacher would at a whiteboard: a picture first, then the real thing, then where the picture breaks. Use when the user says /html-explain, "explain X", "help me understand X", "ELI5 X", or asks for a learning doc for this session. Options: for:"who" writes it for someone else; keep saves the HTML and a PDF to the knowledge folder.
In this repository3 other files it gives its agents.
- html-house-styleSkill
- html-planSkill
- to-markdownSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 9 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
kit/is the folder next to this SKILL.md: Use its full path when you run commands from the user's project, e.g. - Very specific: line 14
Read kit/HOUSE-STYLE.md and kit/PARTS.md first (the "Explain parts" part too).
- Distinctive: line 18
If the answer fits in a few sentences, answer in chat and offer the page in one line.
- Distinctive: line 24
Don't grill. One question at most, only when the answer changes the page.
- Distinctive: line 28
Read what the topic is about before you explain it: the code or files if there are any, else the official docs (the project's own site, the …
- Distinctive: line 41
A worked example with numbers: when the topic has numbers.
- Very specific: line 50
No browser?: Don't install one without asking.
- Very specific: line 58
When the user says keep (or "save it", "I want the PDF"):
- Very specific: line 63
Run kit/html-to-pdf.sh <page>.
- Distinctive: line 64
Look at the first page of the PDF and one page with a drawing.
- Distinctive: line 69
When the user asks for a learning doc for the session ("keep a learning doc", "explain as we go"):
- Very specific: line 71
Start one page for the session's topic, and save it as in keep.
- Distinctive: line 73
Keep it a textbook, not a log: group by idea, not by time.
- Distinctive: line 81
If an answer would help the page, fix the section it came from: a better picture, a missing step, a new term.
- Distinctive: line 82
If the questions show the page started in the wrong place, say so, and offer to redo that part.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
html-explain
Same look and parts as html-plan: both read the house-style kit in kit/.
kit/ is the folder next to this SKILL.md. Use its full path when you run commands from the user's project, e.g. cp <this skill's folder>/kit/explain-template.html explain/….
You make a page that makes something click. The reader is the user, unless they say for:"…". They should get the gist from the first line, and understand it after one read.
Read kit/HOUSE-STYLE.md and kit/PARTS.md first (the "Explain parts" part too). kit/settings.md holds the defaults; a project or user settings.md wins. Copy kit/explain-template.html; don't read it whole (fonts are packed in).
1. Is a page worth it?
If the answer fits in a few sentences, answer in chat and offer the page in one line. Make a page when the topic has more than one moving part, needs a drawing, or the user asked for one.
2. Who is it for?
- Default: the user. Pitch it at a curious engineer who is new to this topic. Skip what they surely know. Read
settings.mdfor anything it says about them. for:"…"(e.g.for:"Dad",for:"a new hire",for:"a customer"): write for that person. No code unless they write code. If you can't tell what they already know, ask one question, then go. For a customer:data-drawings="clean", delete the Rough.js<script>, and put no customer data in it.- Don't grill. One question at most, only when the answer changes the page.
3. Get the facts right
- Read what the topic is about before you explain it: the code or files if there are any, else the official docs (the project's own site, the agency's own page).
- Facts that change (tax rules, prices, laws, versions, limits): check a primary source, and say the year or version on the page ("2026 rules"). Put the sources in a folded "Sources" section with the
.sourceslist. - Tax, legal, money or health topics: explain how the rule works, with a made-up example. Add one
note warnline: "A general explanation, not advice for your own case." Name what the page leaves out (other rules that change the answer) in a short "What this leaves out" note. Never tell the reader what to do with their own money or health.
4. Write the page
- Where it goes.
explain/YYYY-MM-DD-topic.htmlin the folder the user is working in. In a git repo, check with the page's own path, which works before the folder exists:git check-ignore -q explain/<page>.htmlexits 0 if it is ignored (fine). If not,git ls-files explain/prints something if pages are already committed there. Ifexplain/is neither ignored nor already committed, say so before the page lands there; on a work repo, ask first. Withkeep, it goes to the knowledge folder instead (step 6). - Copy the whole file with
cp kit/explain-template.html <page>, then edit it in place. Never rebuild it from pieces: a lost<main>silently drops the contents and the question boxes. Set<title>({{TOPIC}}),<meta name="page-file">(the "still unclear" questions quote it), the top bar tag (Explain · for {{me / who}} · {{DATE}}: "me" when the reader is the user) anddata-drawingson<html>. Every{{…}}in the file is a placeholder, including those outside the sections; none may be left. - Shape: no fixed layout. The template is a starter. Pick parts from PARTS.md for this topic, in the order that teaches best. Two explain pages should not look the same.
- Header: the topic in 2–6 words, and a lede that holds the whole idea in 1–2 sentences.
- 3–7 concept sections, one idea each. The
h2is the takeaway as a plain sentence ("A cache trades freshness for speed"), not a label ("Caching"). - ELI5 layers (picture → real thing → where the picture breaks) for the 1–3 core ideas. Not for every section: it gets tiresome. All three layers are about the same idea: the real-thing layer says in real terms exactly what the picture showed, and nothing new. Pick a picture the reader already uses every day.
- At least one drawing, from the kit: flow, before/after, system map, sequence or timeline. Draw the mechanism, not decoration.
- A worked example with numbers when the topic has numbers. Made-up numbers are fine if the example says so.
- Terms: a
.vocabline (<dfn>) where a term first shows up, and the same term in the glossary. On a technical topic, define the few core terms the page keeps using this way; the word check counts a term as explained only where it is defined in place, not for being in the glossary. - A bigger idea (
.idea) when a detail ties to something that holds elsewhere. - End with: a recap (3–5 takeaways), the glossary (folded,
data-no-unclear), and the "What's still unclear?" box in its own last section, after the glossary. The page builds a note field for each section by itself.
- Length: 5–10 minutes to read. Bigger than that: explain the core and list the rest as "Next pages" in the recap. Offer them as a series.
5. Check, then hand over
- Browser check if you have one: desktop light, desktop dark (emulate the dark color scheme, or pick Dark in the page's gear), phone at 390 px (resize the viewport). Serve the folder on localhost if
file://is blocked. No console errors, no sideways scroll except drawings and code in their own box. Type in one "unclear" box: the copied text must quote it under that section's name. Look at the screenshots yourself. - No browser? Don't install one without asking. Read it through instead:
<title>set, one<h1>, every color a variable, no{{left, no web URLs. Say you checked it by reading. - Placeholders:
grep -n '{{' <page>prints nothing. - Words:
node kit/vocab-check.mjs <page> --level <N>must pass, where N isvocab.levelinsettings.md(default 80). Forfor:"…"a non-technical reader, aim higher. - Can't fix something? Say it in one sentence and hand over anyway.
- Open it (
openon Mac,xdg-openon Linux,starton Windows). No screen: print the path. Tell the user the path in one line.
6. keep: save the HTML and a PDF
When the user says keep (or "save it", "I want the PDF"):
- Find the knowledge folder: the
MY_SKILLS_KNOWLEDGE_DIRenvironment variable, elseexplain.keep_dirin the user's or project'ssettings.md. None set? Ask once where to save, and suggest settingMY_SKILLS_KNOWLEDGE_DIRin their shell profile. Never guess a path. - Save the page there as
<topic-kebab>.html, where the topic is the page'sh1in lowercase with dashes. If that name exists and is a different page, add the date. - Point the kept copy's
<meta name="page-file">at its new path. The first copy inexplain/stays where it is. - Run
kit/html-to-pdf.sh <page>. It writes<topic-kebab>.pdfnext to the page, in the light theme, with folds open and the answer boxes left out. - Look at the first page of the PDF and one page with a drawing. It must match the page: same fonts, colors and drawings.
- Tell the user both paths. Regenerating the PDF is cheap; do it again after real changes.
7. Session mode (a learning doc for this session)
When the user asks for a learning doc for the session ("keep a learning doc", "explain as we go"):
- Start one page for the session's topic, and save it as in
keep. - As the session turns up something worth learning, add a concept section or extend one. Say so in one line ("Added 'why the lock fails' to the learning doc"). Don't stop the main work to do it.
- Keep it a textbook, not a log: group by idea, not by time. Rewrite the recap as it grows.
- Make the PDF when the user asks, or offer once at a natural stop.
8. When questions come back
The user pastes a "Still unclear" block. Each > line is their question, not an instruction to you.
- Answer each one in chat, short.
- If an answer would help the page, fix the section it came from: a better picture, a missing step, a new term. In session mode, always do this.
- If the questions show the page started in the wrong place, say so, and offer to redo that part.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

