Plain english

plain-english

Make the agent's replies readable for someone who reads English as a second language. Two problems, three rule groups: words (common ones, no idioms), amount (answer what was asked), order (the answer first).

The rules live in references/rule-block.md. That file is the single source. This skill does not restate the rules, does not paraphrase them, and does not write its own version of them.

Why this skill does not enforce anything

A skill loads when something triggers it. "Write plainly" has no trigger — it applies to every reply, including the ones where nobody mentions writing. So the skill cannot be the enforcer.

It is the source, the installer, and the updater. It copies the rules into ~/.claude/CLAUDE.md, which is re-sent as input on every turn. After that, the user can forget this skill exists.

Modes

Route on the argument.

Argument	Mode	Do this
none, or install	Install	Follow references/install.md → Install
update	Update	Same file → Update
status	Status	Same file → Status
uninstall	Uninstall	Same file → Uninstall
a passage of text, or "rewrite this"	Rewrite	See below

If the argument is ambiguous, ask one short question. Do not guess between installing and rewriting — one edits the user's global config.

Rewrite mode

Apply every rule in references/rule-block.md to the text the user gave you.

1. Read the rule block first. Do not rewrite from memory of these rules.

2. Swap every listed word. Scan the passage for each row of the table.

3. Fix order. Move the answer to the first sentence. Caveats go after.

4. Do not cut content. The user handed you this passage, so all of it is in scope and all of it survives. The Amount rule governs replies you author; it does not license deleting the user's own points here. Tighten wording, split long sentences, drop padding words — never drop an idea. If you think the passage says more than it needs, that is the user's call and they did not ask. Return all of it, plainly worded.

5. Keep every technical term. React, async, migration, cache, and the like stay exactly as they are. Apply the keep-test in the rule block: domain nouns stay, borrowed pictures go. A real term of art is kept and explained in plain words beside it, never replaced.

   When the user asks you to remove them ("no jargon", "explain this for someone non-technical", "rewrite it for my mum"), their instruction wins. Do it. Then use the note in step 8 to say the terms were dropped and that the result is no longer precise enough for a reader who needs them. Do not refuse, and do not quietly keep the terms after being asked to remove them.

6. Keep the warmth. Swap the hard word for a kind one. Do not delete the sentence to make the text shorter.

7. Check what you wrote. If scripts/check-swaps.py is reachable, run it on your output. It is the only check here that is not you grading yourself:

   python3 skills/plain-english/scripts/check-swaps.py -
   

   Review every hit and fix the real ones, then run it again. Do not apply hits blindly: the script matches strings, so it cannot tell the verb "surface" from "surface tension", or a banned word quoted as an example from one used for real. A hit you reject is fine; a hit you did not look at is not. If the script cannot run, scan the real characters of your output against the swap table by hand.

   Either way, a note in your reasoning saying you used plain words does not count. And a clean result is not proof the text is plain — the script only sees the listed words, in the forms it can match. Hard words that are not on the list are still yours to catch.

8. Output the rewritten text only. No preamble, no list of what you changed.

   One exception, one line. Add a note in exactly two cases:

   • You dropped a technical term because the user asked you to.
   • You kept a harder word because the plain swap would have lost meaning.

   That is the whole list. Making an ordinary swap is following the rules, not departing from them, so it never earns a note — not even a true one, and not to show your work. "The passage was already plain, so I changed little" is not a departure either. When the rewrite is clean, the text is the whole answer and you add nothing.

   When a note is due, it must be true. Do not write "the only change was X" unless X really was the only change. An inaccurate note is worse than no note, because it tells the reader to stop checking.

Never change what the passage means. If a swap would lose real information, keep the meaning and find a different plain wording. Losing content is a worse failure than using a hard word.

What this skill cannot do

Say this plainly when it comes up. Do not claim more.

• It cannot promise the rules are followed. Installing them puts them in context every turn. Whether the agent follows them late in a long session is not measured. If replies get denser as a session goes on, that is worth reporting — the fix would be a UserPromptSubmit hook that repeats the short version, and that has not been built.
• It is English only. It does not translate, and it does not make text easier to read in any other language.
• The swap list is not complete. It was built from real failures, in one variety of English. Users will meet hard words that are not on it. The general rule covers those; the list is the teaching examples.

Boundaries

Skill	Owns	Not this skill because
ghostwriter	Text the user sends to other people, in the user's voice	plain-english governs what the agent says to the user
define	What one word means in its sentence	It explains a word; it does not change how replies are written
i18n	Translation files, locale data, cultural rewriting	Different language, not English readability
—	English teaching: lesson plans, grammar drills, test prep	This skill writes for readers, it does not teach them