Refactor high-complexity React components in Dify frontend. Use when `pnpm analyze-component...
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.