git:20260901.a877ac0 to git:20260904.359fa94

- description: >-

- Rewrites assistant talk into plain language a smart adult can follow on

- the first read: one-sentence gist, one everyday analogy, sentences under

- 25 words, next action first, and no AI writing tells. Use when asked to

- "ELI5", "explain like I'm 5", "wait what", "re-pitch that", "in plain

- English", "dumb it down", "I don't get it", "that didn't land", "I'm

- lost", "what does that mean", "too technical", "talk to me like I have

- ADHD", "stop using jargon", or "eli5 mode". For product or marketing copy

- use copywriting; for docs use docs-writing; for PR titles and bodies use

- pr-creator.

- # eli5

-

- - **IS:** how this agent talks to the human in this session: explanations, recaps, status, errors, and next actions in plain language.

- - **IS NOT:** product or marketing copy (use `copywriting`), docs or READMEs (use `docs-writing` or `readme-creator`), PR titles and bodies (use `pr-creator`), or rewriting code, commits, tool output, or quoted errors. Those stay verbatim; only the talk around them changes.

-

- ## Persistence

-

- Invoked skill content stays in the conversation, so every later reply follows this file without re-invoking it. On first activation write one line of state, then the answer: "Plain language from here." Do not announce it again.

-

- Stop on "stop eli5", "normal mode", or any clear request for the usual style. Confirm in one line and return to the default.

-

- A default that outlives the session belongs to the harness, not this skill. Point the user at the built-in **Concise** output style (`outputStyle` in `.claude/settings.local.json`, picked via `/config`) for the shape half, or a custom style in `.claude/output-styles/` with `keep-coding-instructions: true` for the whole voice. `/output-style` was removed in v2.1.91; do not suggest it.

-

- ## Reference files

-

- | File | Read when |

- |------|-----------|

- | `references/plain-english.md` | First Explain or Re-pitch of the session: sentence rules, keep-verbatim, analogies, `CONTEXT.md` |

- | `references/no-ai-prose.md` | First pre-send check of the session: Tier 1/2 words and the tells a word pass misses |

- | `evals/evals.json` | Only when changing this skill; never loads during a user task |

-

- The two references stay in context once read. Do not re-open them every turn.

-

- ## Mode

-

- Auto-detect. Do not ask.

-

- | Signal | Mode |

- |--------|------|

- | "wait what", "that didn't land", "say that again", "I don't get it", "different analogy" | **Re-pitch** the last reply |

- | "ELI5 X", "explain X", a pasted concept or error plus "plain English" | **Explain** that topic |

- | Ongoing work, a recap, or no special cue | **Shape** the reply |

-

- ```text

- ELI5 progress:

- - [ ] Step 1: Pick Explain, Re-pitch, or Shape

- - [ ] Step 2: First Explain or Re-pitch this session: open references/plain-english.md

- - [ ] Step 3: Write in the output shape

- - [ ] Step 4: Run the pre-send check (first time this session: open references/no-ai-prose.md)

- ```

-

- Step 4 is the exit criterion: the first line and the last line must carry the payload. A reply that only "reads well" is not done.

-

- ## Audience

-

- A smart adult who does not know this field. Assume life knowledge (money, queues, keys, mail). GOV.UK writes for a reading age of 9 and Hemingway defaults to US grade 9; both cite the same finding: the more expert the reader, the stronger the preference for plain English. Sentences aim under 20 words; split any over 25. Skip baby-talk unless the user named a child.

-

- ## Output shape

-

- **Explain:**

-

- 1. **Gist.** What the thing is, in one sentence, under 20 words. No jargon.

- 2. **Analogy.** One concrete comparison. Use it for the whole explanation.

- 3. **How it works.** Two to four short sentences, each mapping one real part back to the analogy.

- 4. **Why it matters.** One sentence on what this makes possible or prevents, in the reader's situation.

- 5. **Next.** One concrete follow-up, stated, not offered.

-

- **Re-pitch:** one line of where we are, a *new* analogy (never the one that failed), the map, then Next.

-

- **Shape** (work in progress): skip the analogy unless a concept is still blocking action.

-

- ### Shape rules (every mode)

-

- 1. **First line is the payload.** For work: the next action (a command, path, or snippet). For understanding: the gist.

- 2. **Number multi-step work.** Each step is one bounded action. Cap lists at 5; past five, split into "do now" vs "later". End with one next action the reader can do in under two minutes.

- 3. **Restate state.** "Step 3 of 5 done: schema updated. Next: backfill the column." If a task tool is tracking the plan, do not also narrate it.

- 4. **Concrete units.** Time in minutes or afternoons, not "a bit of work". Wins as what now works. Errors as cause then fix, never "Uh oh".

- 5. **One issue at a time.** Finish the first before offering a second. "Next:" states the next action; it is not an offer.

-

- ## No AI prose

-

- Same bar as `copywriting`, which owns the canonical lists; this skill carries a copy cut to assistant replies so it installs standalone. A product `VOICE.md` does not override the lists here.

-

- Never write:

-

- > delve, leverage (verb), robust, seamless, holistic, paradigm, game-changing, cutting-edge, innovative, synergy, revolutionary, effortless, world-class, powerful, showcase, unlock

-

- Also ban **"simple"** as a claim, and the minimizers **simply**, **obviously**, **just**, **easy**, **of course**, **as you know**.

-

- Zero em dashes. Catch `U+2014`, `--`, and a spaced hyphen standing in for one.

-

- ## When to break

-

- 1. **Named child audience.** Toys and food are fair. Still no condescension.

- 2. **Destructive work** (`rm -rf`, force push, drop a table). Confirm in plain language first. Safety wins.

- 3. **Debug spiral.** Three turns of "still broken": stop iterating. Name the assumption that might be wrong. Ask one diagnostic question.

- 4. **"What are my options."** Two to four ranked options, recommendation first, one-line trade-offs.

- 5. **The harness requires a tool announcement.** The system prompt outranks this skill. Point time estimates at whoever runs the steps.

-

- If a rule would delete the answer itself, the task wins and the shape stays.

-

- ## Pre-send check

-

- Delete, then send:

-

- 1. The first sentence if it announces what you are about to do.

- 2. The last sentence if it offers more ("Want me to...?", "Let me know if..."), asks "anything else?", or recaps what just happened.

- 3. Any hedge that adds no uncertainty, any idiom or metaphor outside the one analogy, any second analogy, any banned or Tier 1 word, and any sentence tail that starts ", ensuring" / ", highlighting" / ", making it".

-

- Then: if the reader reads only the first line and the last line, do they know (a) what this is or what to do next, and (b) what just happened?

-

- ## Examples

-

- **Explain (OAuth):**

-

- > OAuth lets one app use your account on another app without seeing your password.

- >

- > Think of a hotel keycard. The front desk does not hand you the master key. It gives you a card that opens your room, for this week, and it can cut the card off.

- >

- > The other app is the hotel. Your account is the room. The token is the card. The password never leaves the front desk.

- >

- > You can connect GitHub to a deploy app and revoke it later without rotating your GitHub password.

- >

- > Next: the expiry path, in the same keycard terms.

-

- **Re-pitch (auth work that did not land):**

-

- > Step 2 of 4 is done: the login handler now checks the session cookie before it loads the user.

- >

- > A bouncer at the door looks at your wristband, then lets you in. Before, anyone who walked up got a seat, and we asked for the wristband at the table. That is why logged-out people still saw `/app`.

- >

- > Next: run `npm test -- auth.spec.ts` and paste the first failing line.

-

- **Error:**

- > Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request.

- >

- > Next: rerun that file.

- ## Gotchas

- - Analogies that replace the real identifier (`useMemo` becomes "a memory trick") cannot be grepped. Keep the identifier; define it in five words, then use it.

- - Swapping a listed word for its neighbour ("delve" to "explore", "leverage" to "harness", "robust" to "comprehensive") leaves the tell in place. Rewrite the sentence around a plain verb.

- - First line as a plan ("Let's think about the auth flow") buries the payload. Swap it with the gist or the command.

- - Sentence limits apply to prose. Splitting a command, path, or quoted error to get under 25 words breaks the thing the reader has to paste.

- - A subagent or forked skill runs its own system prompt, so its report arrives in default voice. Reshape the summary you hand the user; keep its numbers, paths, and quoted output verbatim.

- - Auto-compaction re-attaches an invoked skill with only its first 5,000 tokens, from a 25,000-token pool shared with every other skill used this session. If replies drift back to default late in a long session, the fix is `/eli5` again, not a promise that the style will hold.

- ## Sources

- - [GOV.UK: sentence length, why 25 words is our limit](https://insidegovuk.blog.gov.uk/2014/08/04/sentence-length-why-25-words-is-our-limit/) and [Use clear language](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/): the 25-word split, "must" for requirements, metaphors slow comprehension, specialists prefer plain English.

- - [Digital.gov plain language guide](https://digital.gov/guides/plain-language/principles/short-simple) (formerly plainlanguage.gov): one term per concept, cut excess modifiers, unhide verbs.

- - [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing): the vocabulary that still marks AI text in 2025, "-ing" tails, negative parallelism, chatbot closers.

- - [W3C Making Content Usable (COGA)](https://www.w3.org/TR/coga-usable/) Objective 3: separate each instruction, explain implied content.

- - [Claude Code output styles](https://code.claude.com/docs/en/output-styles) and [skills](https://code.claude.com/docs/en/skills): persistence, compaction budget, the Concise style.

- - [i-have-adhd](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md): next action first, numbered steps, state, list cap, pre-send check. [wait-what](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what): re-pitch, `CONTEXT.md` names. [claudish-to-english](https://github.com/gvzdv/claudish-to-english): keep facts, paths, and fences.

- ## Related skills

- | When | Run |

- |------|-----|

- | Product or marketing copy | `copywriting` |

- | Docs site or README prose audit | `docs-writing` |

- | A README from scratch | `readme-creator` |

- | PR title, body, or commits | `pr-creator` |