joelio

plain-english

0
0
# Install this skill:
npx skills add joelio/plain-english --skill "plain-english"

Install specific skill from multi-skill repository

# Description

Use when writing or editing prose, documentation, policies, user-facing content, or any text that should be clear and accessible. Triggers include verbose drafts, jargon-heavy text, readability complaints, or requests to simplify writing.

# SKILL.md


name: plain-english
description: Use when writing or editing prose, documentation, policies, user-facing content, or any text that should be clear and accessible. Triggers include verbose drafts, jargon-heavy text, readability complaints, or requests to simplify writing.


Plain English

Write so your reader understands the first time they read it.

Core Rules

Sentences

  • Average 15-20 words. Hard ceiling: 25 words.
  • One idea per sentence. Break at natural clause boundaries.
  • Vary length to avoid monotony — but never exceed the ceiling.

Words

Prefer short, concrete, everyday words over formal or Latin-derived alternatives.

Instead of Use
utilise use
commence start, begin
terminate end, stop
purchase buy
ascertain find out
endeavour try
facilitate help
approximately about
in the event that if
prior to before
subsequent to after
in accordance with under, following
notwithstanding despite, even though
pursuant to under
in respect of about, for
additional more, extra
sufficient enough
regarding about
assist help
advise tell
obtain get
require need
demonstrate show
indicate show, say
forward send
in order to to
due to the fact that because
at this point in time now
it should be noted that (delete)
please find enclosed here is
I am writing to inform you (just say it)

Voice

  • Use active voice ~80% of the time: "The council revoked the licence" not "The licence was revoked by the council."
  • Passive is fine when the actor is unknown, unimportant, or when tact requires it.

Structure

  • Front-load: put the main point first — inverted pyramid.
  • One idea per paragraph. Max 3-5 sentences per paragraph.
  • Use headings that answer reader questions: "How to appeal a parking ticket" not "Appeals — general."
  • Use bullet points for 3+ items. Start each bullet with the same grammatical form.
  • Address the reader as "you." Use "we" for the organisation.

Kill These Patterns

Nominalisations — verbs turned into nouns:
- "make a decision" -> "decide"
- "conduct an investigation" -> "investigate"
- "provide assistance" -> "help"
- "give consideration to" -> "consider"

Hidden verbs:
- "conduct a review" -> "review"
- "carry out an assessment" -> "assess"
- "make an application" -> "apply"

Hedging piles:
- "may possibly be able to" -> "may"
- "it is recommended that consideration be given to" -> "we recommend"

Double negatives:
- "not uncommon" -> "common"
- "not dissimilar" -> "similar"
- "did not fail to" -> "did"

Redundancies:
- "absolutely essential" -> "essential"
- "completely finished" -> "finished"
- "future plans" -> "plans"
- "past history" -> "history"

Noun strings — break with prepositions:
- "school bus routing optimisation strategy" -> "strategy to optimise school-bus routes"

Readability Targets

Metric Target
Flesch Reading Ease 60-70 (general public)
Flesch-Kincaid Grade 8 or below
GOV.UK target reading age 9-11

Tools: Hemingway Editor, MS Word readability stats, readable.com.

Legal/Formal Distinctions (GOV.UK)

  • must = legal requirement, serious consequences
  • need to = administrative requirement, no criminal repercussions
  • should = recommendation
  • Avoid "shall" — it's ambiguous. Use "must" or "will."

Before/After Examples

Before: "Prior to the commencement of operations, an assessment of environmental impact shall be undertaken by the relevant authority."

After: "Before operations start, the authority will assess the environmental impact."

Before: "It has been brought to our attention by members of staff that the new policy is causing confusion regarding the implementation of the revised procedures."

After: "Staff say the new policy is confusing."

Before: "Should you require any further assistance, please do not hesitate to contact us."

After: "Contact us if you need help."

Quick Checklist

  • Average sentence 15-20 words, none over 25?
  • 80%+ active voice?
  • Everyday words — no jargon without explanation?
  • Flesch Reading Ease 60+?
  • Headings answer reader questions?
  • One idea per paragraph?
  • Lists for 3+ items?
  • Reader addressed as "you"?

Authoritative Sources

  • Plain English Campaign — plainenglish.co.uk
  • GOV.UK Content Design Guide
  • US Federal Plain Language Guidelines (Plain Writing Act 2010)
  • ISO 24495-1:2023 Plain language
  • Martin Cutts, Oxford Guide to Plain English, 5th ed.

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.