Clear writing

Rewrite prose so a smart reader who is new to the subject understands it on one read. Keep the author's voice and every fact.

A bad sentence, and why

Claude Code subagents and agent teams start with your MCP tools and the lead's permission mode, so a researcher meant only to read a folder can also rewrite it.

It assumes the reader knows "the lead", "permission mode" and "MCP tools". It packs three ideas into one sentence. And the point (an agent you meant only to read can also delete) comes last.

Rewritten:

When Claude Code starts a helper agent, the helper gets every tool and every permission you have. So an agent you asked only to read a folder can also rewrite it.

Rules

1. Say the point first. Each paragraph's first sentence is its point. A reader who reads only first sentences gets the piece.
2. One idea per sentence. Split at "so", "which", semicolons, dashes and parentheses when they start a second idea. Aim for under 20 words. Never go over 30.
3. Plain words. Write for someone who has used a chatbot but never read the docs. Prefer "use" to "leverage", "about" to "approximately", "can read" to "has read access", "folder" to "scope".
4. No undefined jargon. Explain a term a newcomer would not know in one short clause the first time, or replace it. For a developer audience, keep standard developer terms but still define the product's own.
5. Active voice, concrete subjects. "The server checks the token", not "the token is checked". Name who does what.
6. Cut filler. Delete "basically", "simply", "just", "really", "in order to", "it's worth noting", "note that", hedges and throat-clearing. Delete a sentence that repeats the one before it.
7. Concrete over abstract. Prefer an example ("an agent asked to summarise plans/ can delete plans/") to a category ("excessive privilege").
8. Keep the voice. Keep first person, the author's examples, jokes and opinions. Tighten them. Do not neutralise them.

Do not change

• Facts, numbers, dates, names, claims and recommendations. If you cannot tell what a sentence claims, leave it and flag it.
• Links and URLs, images and their alt text's meaning, code blocks, commands, config, and the facts in tables (cell wording may be tightened).
• Frontmatter. Headings' meaning (wording may be shortened).
• Notes in [square brackets] that read like the author's notes to themselves.

How to work

1. Read the whole piece first. Write down its point in one sentence.
2. Edit paragraph by paragraph: point first, then split, plain words, jargon, voice, filler.
3. Read it back as the newcomer. Any sentence you had to read twice gets another pass.
4. Check the "Do not change" list against the original: same links, images, code and facts.
5. Report the old and new word count, the worst sentence before and after, and any sentence you left because its claim was unclear.

Checklist

• Every paragraph opens with its point.
• No sentence over 30 words; most under 20.
• Every term a newcomer would stumble on is explained once or gone.
• No passive voice that hides who acts.
• No filler words from rule 6.
• Links, images, code, numbers and frontmatter unchanged.
• It still sounds like the author.