| name | eli-doc |
| description | Generates a plain-language glossary (ELI5.md) for the current codebase. Trigger when the user says "/eli-doc", "generate eli5 docs", "make a plain-language glossary", "explain this codebase simply", "create eli5 documentation", or "document this for beginners".
|
ELI5 Doc — Generate Plain-Language Codebase Glossary
Scan the current codebase and write ELI5.md — a plain-language guide to everything in it.
Steps
1. Discover the codebase
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" \
-o -name "*.rs" -o -name "*.rb" -o -name "*.java" -o -name "*.cs" \) \
-not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
-not -path "*/build/*" | head -60
Also check for: README.md, package.json, pyproject.toml, Cargo.toml, go.mod
to understand the project's purpose.
2. Check eli5 level
cat .claude/eli5-state.json 2>/dev/null || echo "none"
Default to eli-adult level for docs (smart non-expert reader) unless a different level
is currently active or the user specifies one.
3. Identify concepts to document
From the codebase, extract:
- What the project does (1-paragraph overview)
- Key concepts — domain terms, patterns, architectural decisions
- Main components — important files, classes, modules (top 10–15)
- How data flows — what comes in, what happens, what comes out
- Jargon the codebase uses — tech terms that appear frequently
4. Write ELI5.md
Use this structure:
# [Project Name] — Plain Language Guide
> Generated by eli5-mode. Level: [current level]. Updated: [date]
## What this project does
[2–3 sentences. Analogy-first. No jargon. What problem does it solve?]
## The big picture
[Optional: a flow diagram in words — "First X happens. Then Y. Finally Z."]
## Key concepts
### [Concept 1]
[Analogy-first explanation at the current level. 2–4 sentences.]
### [Concept 2]
[Same format]
[...continue for all key concepts...]
## Main files and what they do
| File | What it does (plain language) |
|---|---|
| `src/index.ts` | [plain description] |
| `src/auth.ts` | [plain description] |
## How data moves through the system
[Narrative walkthrough. Use concrete analogies. Walk through a typical request/action.]
## Words this project uses a lot
| Term | What it really means |
|---|---|
| [term] | [plain-language definition via analogy] |
5. Confirm
"Written ELI5.md — [N] concepts, [M] files documented at [level] level."
Team mode: /eli-doc --team
When --team is specified, produce a version designed to be committed to the repo as an onboarding artifact:
- Add a "New hire start here" section at the top with the 3 most important files to read first
- Include a "Gotchas" section: 3–5 things that trip up newcomers in this specific codebase
- Add a "Glossary" section: every domain-specific or project-specific term, plain-language only
- Output filename:
ELI5.md (same) — but add a header note: > Intended for new contributors. Keep this up to date.
- Suggest: "Commit this as
ELI5.md in the repo root — it'll be there for every new hire."
Important
- Stay at the eli5 level throughout. No technical jargon in the output.
- Accuracy matters: read actual files before describing them. Don't invent.
- If the codebase is large (>50 files), focus on the most-referenced files and entry points.
- Check
~/.claude/skills/eli5-mode/references/analogy-bank.md for ready-to-use analogies.
