Explain how anything works like I'm 5 — built around cause and effect.
A Claude Code plugin that turns any "how does this work?" or "why does this happen?" question into a picture-first HTML explainer. Instead of a loose collection of analogies, it walks through the topic as one clear chain: this happens, so that happens, so that happens.
/eli5-flow explain what happens when a user enters a URL and a web page loads
/eli5-flow explain how rising interest rates relate to prices
By default the explainer assumes you know nothing about the topic. Add --for dev — or just ask for it in words, in any language — and it keeps the same chain, the same layout and the same number of cards, but uses the real terms instead of analogies:
/eli5-flow --for dev what happens in React when state changes and the screen updates
/eli5-flow explain the browser event loop for engineers
| default | --for dev |
|
|---|---|---|
| Words | everyday words, no jargon | DNS lookup, TCP handshake, reconciliation, commit |
| Pictures | a phone book, a letter | browser, server, DOM |
| Depth | why it happens | why it happens, and what actually does it |
| Easy to mix up | what a beginner gets wrong | what developers actually get wrong |
Simple explanations often fail in the same place: the steps are there, but the connections between them are missing. You understand each picture, yet you can't say why one leads to the next.
eli5-flow keeps the "big pictures, few words" spirit and adds strict rules for the links: every arrow states its reason, no step may be skipped, and each page shows what breaks if one link is removed.
Five topics with expert reference answers, explained by each tool, then graded by a separate Claude instance that was not told which tool wrote which page (the harness is in evals/):
| eli5-flow | eli5 | plain Claude, no plugin | |
|---|---|---|---|
| pages graded | 15 | 10 | 10 |
| key causal links covered | 98% | 94% | 100% |
| links judged truly causal | 98% | 90% | 99% |
| "but why?" gaps left | 5 | 11 | 1 |
| factual errors | 0 | 3 | 4 |
| pages showing what breaks | 15/15 | 1/10 | 2/10 |
| words per page | 573 | 285 | 1395 |
| cost per page | $1.99 | $1.29 | $1.20 |
Each tool wins something:
- Plain Claude is the most complete — and 2.4× longer. It covered every key link, but it also made the most factual errors, and a 1400-word page is an article, not a picture of a flow.
- eli5 is the shortest and cheapest. If you want one quick picture of a topic, that is exactly what it is for. It also leaves the most "but why?" gaps — twice as many as eli5-flow in half the pages.
- eli5-flow lands in between on length and first on accuracy. It was the only one with no factual errors, and the only one that reliably shows what happens when a link is removed.
Caveats worth reading: two runs per topic for the comparison columns, so the error counts are indicative, not settled. The rubric scores causal accuracy and counterfactuals — which is what eli5-flow optimizes for and not what plain eli5 aims at. Run it yourself with node evals/run.ts --arm eli5 --runs 2.
Each explainer is a single HTML page with six sections:
- The big picture — one sentence: "When ___ happens, in the end ___."
- Who's involved — the 2–5 characters or parts, introduced before they appear.
- The chain — 5–9 numbered steps. Every arrow carries a reason and a small tag:
trigger— what starts itneeds— a condition that must already be trueleads to— the normal mechanism
- Snap a link — "What if step N didn't happen?" Shows where the chain stops and how the ending changes. If nothing changes, that link wasn't important.
- Easy to mix up — common misunderstandings: "Looks like ___, but really ___."
- Say it in one breath — the whole chain in one line: "A, so B, so C, so D."
Example chain for how rising interest rates relate to prices:
[central bank raises rates] --trigger: banks follow the central bank's rate--> [loans get pricier]
--leads to: borrowing costs more, saving pays more--> [less money to spend]
--leads to: lighter wallets--> [people buy less]
--leads to: unsold goods cost shops money--> [shops raise prices more slowly]
--leads to: many shops at once--> [inflation cools down]
Snap a link: if costs keep rising and shops must raise prices anyway
→ price tags keep climbing even with fewer customers → inflation doesn't cool.
The explainer is written in whatever language you ask in.
In Claude Code:
/plugin marketplace add prgmr99/eli5-flow
/plugin install eli5-flow@eli5-flow
Or from your shell:
claude plugin marketplace add prgmr99/eli5-flow
claude plugin install eli5-flow@eli5-flowStart a new session after installing, then run /eli5-flow <topic>. Claude may also pick the skill up on its own when you ask why something happens or what leads to what.
claude plugin marketplace update eli5-flow
claude plugin update eli5-flow@eli5-flowclaude plugin uninstall eli5-flow@eli5-flow
claude plugin marketplace remove eli5-floweli5-flow/
├── .claude-plugin/
│ ├── plugin.json # plugin metadata
│ └── marketplace.json # makes this repo installable as a marketplace
├── .github/workflows/ # CI: typecheck, tests, manifest check
├── evals/ # reference answers, grader and comparison scripts
├── scripts/
│ ├── check-chain.ts # structural checker for generated explainers
│ └── check-plugin.ts # manifests and SKILL.md frontmatter
└── skills/
└── eli5-flow/
├── SKILL.md # the skill: chain rules, page structure, chain data
└── LAYOUT.md # full-width layout, spacing and connector rules
Try local changes without installing:
claude --plugin-dir ./Validate before pushing:
claude plugin validate --strict .claude-plugin/plugin.json
claude plugin validate --strict .claude-plugin/marketplace.json
claude plugin validate --strict skillsEvery explainer embeds its chain as JSON (<script type="application/json" id="eli5-flow-chain">). The checker (Node 22.18+, no dependencies) reads it and fails on structural problems:
- a step with no incoming or outgoing link (a jump or a dead end)
- an arrow without a reason or a cause kind (
trigger/needs/leads-to) - a backward arrow that isn't declared as a
reinforcing/balancingloop - a "snap a link" that names no real link, or whose ending doesn't change
- chain data that doesn't match the text on the page
node scripts/check-chain.ts path/to/explainer.html
npm test # unit tests for the checker and the scoring
npm run typecheck
npm run check:plugin # manifests agree, every SKILL.md has name and descriptionThe checker checks form, not truth: a chain can pass and still be wrong about what causes what. That is what the evaluation below is for. CI runs the type check, the unit tests and the manifest check on every push and pull request.
evals/references/*.json holds an expert reference per topic: the key causal links, the errors people actually make, and the simplifications that are fine. A run explains every topic, checks the structure, and then has a separate, isolated Claude grade each page against its reference — no tools, no user settings, and no clue which tool produced the page.
node evals/run.ts --runs 3 # this skill, every topic
node evals/run.ts --arm eli5 --runs 2 # compare against another skill
node evals/run.ts --arm plain --runs 2 # compare against no plugin at all
node evals/run.ts --resume evals/results/<dir> # retry only the runs that failed
node evals/compare.ts <before dir> <after dir> # accuracy and page complexity, side by side
node evals/compare-arms.ts <dir> <dir> <dir> # one table per toolScores are computed in code from the grader's per-item verdicts, so the thresholds are visible and adjustable in evals/judge.ts. Results land in evals/results/<timestamp>/ (git-ignored) with every page, transcript and verdict kept.
A run costs real money — roughly $2 per page generated plus $0.12 to grade it.
When releasing, bump version in both plugin.json and marketplace.json.
This project stands on the shoulders of two ELI5 skills. Thank you both for showing how much a small, well-aimed prompt can do.
- eli5 by Thariq Shihipar — the "big pictures, few words" HTML explainer in the Claude Code community marketplace. eli5-flow's picture-first format and its opening instruction are adapted from this plugin (MIT).
- ELI5 by Andrew Ou (@DreambigOu) — a skill that adapts explanations to any audience, from kids to managers. It is what got this project started, and its write-up, Building an ELI5 Skill for Claude, is well worth reading.
eli5-flow is an independent, unofficial project and is not affiliated with or endorsed by either author or by Anthropic.
MIT © prgmr99