simple-prose

Files (1)

• SKILL.md

SKILL.md (first lines)

# Simple prose

Write plain, front-loaded English that a reader understands the first time. Open the content up without dumbing it down: plain English carries complex ideas better, and specialists prefer it too. These rules are adapted from the GOV.UK writing guidelines and style guides (guidance.publishing.service.gov.uk).

## Keep the meaning

A rewrite changes the words, never the claims. This rule beats every other rule in this skill.

- Do not drop a qualifier, a hedge, a condition, an exception or a list item. Words like 'only', 'unless', 'usually' and 'may' are content, not clutter.
- Before you finish a rewrite, compare it with the source item by item. Count the list items in both. If the counts differ, point to where each missing item's content now lives.
- If plain wording would widen or narrow a claim, keep the precise wording and simplify around it.

## Structure

- Front-load everything. Put the most important point first in the document, in each section, in each paragraph and in each sentence, then taper down to detail.
- Keep one topic per paragraph and no more than 5 sentences per paragraph.
- Split any sentence longer than 25 words.
- Write headings that are descriptive, front-loaded and active. Do not write headings as questions. The text must still make sense with the headings removed.
- Use bullet lists and numbered steps to cut duplication and make lists easier to read.
- Do not use footnotes. If the information matters, put it in the body text. If not, cut it.
- Do not repeat yourself. Say each thing once, in the place the reader needs it.

## Voice and tone

- Use the active voice: say who does what. The passive is acceptable when the outcome matters more than the actor, or when it keeps the focus on the reader.
- Address the reader as 'you'. Use 'we' only after you have named the organisation or actor it stands for.
- Be specific and informative: give the number, the name, the date. Cut adjectives that only add emotion or spin.
- Do not write 'please' or 'please note'.
- In the third person, stay gender neutral: 'they', 'them', 'their'.

## Words

- Use everyday words: 'buy' not 'purchase', 'help' not 'assist' or 'facilitate', 'about' not 'approximately', 'use' not 'utilise' or 'leverage', 'work with' not 'collaborate' or 'liaise', 'start' not 'initiate', 'stop', 'solve' or 'deal with' not 'tackle' or 'combat'.
- Avoid metaphors and buzzwords: 'drive', 'going forward', 'key', 'robust', 'hub', 'ring fencing', 'in order to'. Replace each with what you actually mean.
- Specialist terms are fine when the reader needs them. Explain each one in plain English the first time you use it.
- Make requirements clear: 'must' for a hard or legal requirement, 'need to' for an administrative one, 'can' for something optional. Avoid 'you may be able to'.
- Contractions like 'you'll' are fine. Avoid negative contractions -- write 'cannot', not 'can't' -- and avoid 'should've', 'could've' and 'would've'.
- Use British English spelling: 'organise', 'behaviour', 'centre'. Do not respell identifiers, quoted text or proper nouns that use another spelling.

## Formatting

- Use sentence case everywhere, including headings and titles. Capitalise only proper nouns.
- Do not use bold or italics for emphasis. Bold only names an interface element in an instruction, for example: select Save. Use single quotation marks for the title of a document, scheme or publication.
- Bullet lists: use a lead-in line that ends in a colon, start each bullet lower case, keep at most one sentence per bullet, and put no 'and', 'or', semicolon or final full stop after bullets.
- Use numbered steps only for a sequence the reader follows in order. Each step is a full sentence and ends with a full stop.
- Do not use semicolons in running text. Split the sentence instead.
- Write 'for example', 'that is' and 'and so on' -- never 'eg', 'ie' or 'etc'.
- Write 'and', not '&'.
- Numbers: write 'one', then numerals from 2 up. Use a comma in numbers over 999 (9,000). Use % with numerals (50%). Spell out 'million' and 'billion' (£5 million). Spell out ordinals first to ninth, then 10th.
- Write ranges with 'to', not hyphens: 10 to 20, Monday to Friday, 4 to 8 June.
- Write dates as 4 June 2026 (no comma, no 'th') and times as 5:30pm, 10am to 11am, 'midday' and 'midnight'.
- Make link text descriptive and front-loaded so it works out of context. Never 'click here' or 'more'. Start link text with a verb when the link starts a task.
- Do not use FAQs: answer the reader's need in the content instead. Do not use block capitals.

## Before you finish

Check the result:

- the most important point comes first
- a non-specialist could understand every sentence on first read
- every qualifier, hedge, condition and list item from the source survives
- any words you can cut without losing meaning are cut

From cormacc/dotagents, MIT.

More from cormacc/dotagents