eli5

---
name: eli5
description: "Explain unfamiliar mechanisms in plain language; create or maintain self-contained HTML learning pages with visual models, quizzes, explain-back checks, flashcards, and optional interaction; or produce a decision brief when the user must choose among options. Use for ELI5 or visual explanations, durable learning pages, quizzes, review of earlier concepts, and decision briefs. Give single facts and ordinary quick explanations inline without files. A named audience alone does not imply a decision brief."
---

# eli5

Build understanding at the lowest useful rung, then let the learner test and reconstruct
the same mental model. Preserve truth: simplify structure and vocabulary, never the
load-bearing mechanism.

## Path and workspace invariant

Let `[skill-dir]` mean the directory containing this `SKILL.md`. Resolve every bundled
`scripts/...`, `assets/...`, and `references/...` path from `[skill-dir]`. Keep the shell
working directory at the user's target workspace so relative page and ledger paths bind
to that workspace. Never change into `[skill-dir]` merely to run a bundled helper.

## Choose the deliverable

Decide from what the reader must do after the explanation:

- **Answer one fact or understand it now** → explain inline. No file and no ledger write.
- **Retain, practise, revisit, or interact with one mechanism** → learning page.
- **Choose among options under constraints** → decision brief. Read
  `references/brief.md`; audience role or age is not enough.

Do not silently turn a conversational explanation into file creation or publication. When
the request is ambiguous, prefer inline. Ask only when the difference changes a named
decision, an external action, or the requested deliverable.

## The explanation contract

> If a sentence only makes sense to someone who already knows the topic, it is not ELI5.

Replace jargon until the mechanism is visible. Reintroduce real names at the next level.
If level 1 intentionally bends the truth, level 3 must name the debt and give the real
boundary. An analogy is optional: use one only when it maps at least three useful parts,
and state where it breaks.

## Workflow — inline

1. Pin the concept in one sentence using words the reader already has.
2. Show the pressure that made the mechanism necessary, then its smallest causal shape.
3. Use one compact example or diagram only when it reduces cognitive load.
4. Stop when the request is answered. Do not manufacture modes, files, or review state.

For code or repository topics, inspect the actual implementation first and cite concrete
file anchors. If history cannot establish why a tradeoff was made, say so.

## Workflow — learning page

The canonical local HTML file is the source of truth. Default location:
`.eli5/pages/[concept-id].html`; the default ledger is `.eli5/ledger.json`. Respect a
user-specified location. Publishing is optional and requires an explicit request.

1. **Reuse before creating.** Run `python3 "[skill-dir]/scripts/ledger.py" --ledger
   .eli5/ledger.json list --json` and find a close title or source match. Update the
   stored `path` when a concept already exists; do not create an orphan page.
2. **Ground the concept.** Read source material needed for accuracy. For repo-specific
   topics, inspect code and relevant history rather than inferring from names.
3. **Choose the real shape.** Read `references/page-spec.md`; use the smallest diagram
   form that preserves the causal structure. A custom form is allowed when the catalog
   does not fit.
4. **Write the explanation.** Read `references/explain-craft.md` and
   `references/budgets.json`. Fill all three levels as rewrites of the same mechanism.
5. **Build the page.** Read `references/modes.md` and start from `assets/template.html`.
   ELI5, Quiz, Explain Back, and Flashcards are required. Interact is conditional on a
   genuine input-to-outcome dynamic. Localize all visible controls to the reader's
   language and set `data-lang`.
6. **Validate.** Run `python3 "[skill-dir]/scripts/lint_page.py" [page]`. Fix every
   FAIL. Then run `python3 "[skill-dir]/scripts/smoke_templates.py"` when the shared
   template or machinery changed. If browser inspection is available, check one desktop
   and one mobile viewport in a bounded pass; confirm keyboard access and no horizontal
   body scroll.
7. **Record.** Run `python3 "[skill-dir]/scripts/ledger.py" --ledger .eli5/ledger.json
   add --title "[concept]" --path "[page]"` and include `--source` when applicable. The
   local path is required; a published URL is optional metadata.
8. **Hand back the result.** Return one line plus a clickable local file link. Do not
   duplicate the full explanation in chat.

If the user explicitly asks to publish, keep the local canonical file unchanged, record
the resulting URL, and report the external mutation. Never treat permission to explain as
permission to publish.

Use a host-specific publication workflow. First inspect the target host's document and
isolation contract. If it accepts complete HTML, publish an unchanged copy of the
canonical document. If it accepts content only, adapt a separate copy for that verified
host and scope its CSS and JavaScript to the host-provided container; do not use a generic
document-to-fragment transform. Keep the canonical document unchanged in either case.

This avoids two failures that can pass a static review: nesting a complete document puts
its title and character-encoding declaration inside the host body, while stripping the
wrapper without scoping leaks `body`/`:root` styles and document-level keyboard handling
into the host. Per-host verification is required for either path.

## Follow-up requests

Read `references/state.md` before changing review state.

| User says | Action |
|---|---|
| "quiz me on X" / "考考我" | Find X in the ledger, reuse its stored path, and open or update the same page with Quiz selected. If it is missing, say so and build only if the user wants a page. |
| "I got Y wrong" | `ledger.py review --id X --fail --shaky "Y"`; rewrite the weak explanation on the same local page. |
| "5/5" or another score | `ledger.py review --id X --asked 5 --correct 5`; record only a score the user actually reported. |
| "go deeper" / "第二层" | Update the same page's next level; preserve the concept ID and local path. |
| "what should I review" / "复习" | `ledger.py due --json`; build one mixed local review page from the canonical page data. |
| repeated misses | `ledger.py weak --json`; rewrite points with repeated hits before asking them again. |

Never infer a pass from `--shaky`, an unscored flashcard session, or silence. Updating
review content changes `contentVersion` so stale browser state cannot corrupt the page.

## Decision brief

Use a brief only when the reader faces an actual choice. Read `references/brief.md` and
start from `assets/brief-template.html`. A brief is a canonical local HTML file too, but
it has no quiz, learning state, or ledger entry.

## Do not use a learning page when

- The answer is a single fact, yes/no, or a short definition.
- The user asks for precise expert-level treatment rather than simplification.
- The user asks you to perform work; perform it instead of wrapping it in an explainer.
- The user did not request a durable, visual, interactive, quiz, or review artifact.

## Reference index

| File | Read it when |
|---|---|
| `references/explain-craft.md` | Writing explanation prose, analogies, or depth levels |
| `references/page-spec.md` | Choosing and drawing the visual shape |
| `references/modes.md` | Building or switching learning modes |
| `references/state.md` | Reading or mutating the ledger and review schedule |
| `references/budgets.json` | Tuning or debugging language-aware budgets |
| `references/brief.md` | A reader must choose among options |
| `assets/template.html` | Starting or updating a learning page |
| `assets/brief-template.html` | Starting a decision brief |
| `scripts/ledger.py` | Ledger CLI and migration behavior |
| `scripts/lint_page.py` | Page validation and budget calibration |
| `scripts/smoke_templates.py` | Shared template and JavaScript smoke check |
| `scripts/run_evals.py` | Behavioral evaluation after changing this skill |

## Changing this skill

Run deterministic checks first:

```bash
python3 -m unittest discover -s tests -v
ruff check --no-cache scripts tests
```

`tests/test_skill_contract.py` validates this file's own frontmatter and behavioural
promises, so the suite is self-contained and needs no sibling skill installed.

Behavioral comparison operates on complete skill directories, not isolated entrypoints:

```bash
python3 "[skill-dir]/scripts/run_evals.py" --a /path/to/old/eli5 --b "[skill-dir]" --case static-concept
```

The eval runner auto-detects an installed Codex or Claude CLI; `--provider` overrides the
choice. Each candidate skill is staged in a disposable case workspace before the host
runs. A full sweep may consume model quota, so run it only when authorized; `--dry-run`
validates plumbing without model calls.