simple-writing
Skill3 starsChanged 43 days agoMITView on GitHub
Rewrites text so a reader with no context, no patience and no technical background gets it on the first read. Two levels: plain language (default) and easy read (maximum simplicity, for readers who struggle with text). Use when a message must land with non-technical users - client emails, release notes for non-developers, instructions for support or admin staff, in-app copy, error messages, onboarding docs - or when asked to \"make this simpler\", \"explain it like they have no idea\", \"lenguaje simple\", \"lectura fácil\", \"escríbelo para que lo entiendan\", \"hazlo más corto y claro\". Works in English and Spanish.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- samirpatil2000/skillstheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- samirpatil2000/skills★ 17same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- best-promptingSkill
- create-skillsSkill
- krug-usability-testingSkill
- microcopySkill
- ousterhout-software-designSkill
- research-firstSkill
- test-auditSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
When unsure, ask which one.
- Distinctive: line 28
One idea per sentence: If a sentence has an "and" joining two ideas, split it.
- Distinctive: line 32
Keep a technical term only if the reader already uses it, and then explain it once.
- Distinctive: line 50
Don't sound like you are talking down: Never write "this is very easy", "as we already explained", "just do X".
- Distinctive: line 101
After (answer first, steps, reason last):
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Simple writing
You turn text into something a tired, distracted, non-expert reader understands on the first read. Not shorter for its own sake: shorter to be understood.
Two levels. Pick one before writing:
| Level | For | Sentence length | Look |
| Plain language (default) | Any non-technical reader: clients, staff, users | 15-20 words average | Normal prose, short paragraphs |
| Easy read | Readers who struggle with text, high stress, or a second language | One idea per sentence, ideally one line | Lots of white space, headings, numbered steps |
When unsure, ask which one. If you can't ask, write plain language and offer the easy read version.
The rules
Both levels share these. Easy read applies them harder.
- Answer first. The thing the reader has to do goes in the first paragraph. Reasons, context and caveats go after. Most "confusing" text is just a good answer buried under background.
- One idea per sentence. If a sentence has an "and" joining two ideas, split it.
- Short sentences. Plain language: 15-20 words on average. Easy read: under 15, and each sentence starts on its own line.
- Everyday words. Say send not submit, change not modify, fix not remediate. Keep a technical term only if the reader already uses it, and then explain it once.
- Active voice, real subject. "You change the RUT", not "the RUT must be changed". The reader must know who does what.
- Present tense. "The email arrives" beats "the email will have been sent".
- Say it positively. "Reply to us" beats "do not fail to notify us". Never stack two negatives.
- Steps as a numbered list. Anything the reader must do becomes 1, 2, 3 - one action per step, in the order they happen.
- Repeat what matters. Repeating the key action at the end is not redundancy, it is how it sticks.
- No irony, no metaphor, no idioms. They are the first thing to break for a stressed or non-native reader.
- Concrete over abstract. "Next Tuesday" beats "in the coming days". "The green button that says Send" beats "the corresponding control".
- Numbers as digits. "3 points", not "three points".
What NOT to do
- Don't sound like you are talking down. Never write "this is very easy", "as we already explained", "just do X". Simple wording, adult tone. If the text implies the reader is slow, it has failed even if every sentence is short.
- Don't delete the information. Simplifying is re-ordering and re-wording, not dropping the parts that are inconvenient. If something matters legally or operationally, it stays - moved to its own short sentence, in plain words.
- Don't lead with the refusal or the constraint. "We can't do X, because..." reads as we won't help. Lead with what now happens instead, then the reason. This is the single most common failure when replying to a client request.
- Don't invent certainty. Simple does not mean absolute. If something is not decided, say "we don't know yet" in short words.
How to rewrite
- Read the original and write down the one action the reader has to take. If there is no action, write down the one fact they must remember. Everything else is support.
- Draft the answer-first opening: what happens now, or what they must do.
- Break every sentence to one idea. Cut every word that carries nothing: "in order to" → "to", "at this point in time" → "now", "we would like to inform you that" → delete.
- Turn the how-to into numbered steps.
- Move reasons to the end, in one or two short sentences. Reasons are read last and only by some people, which is fine.
- Reread as the reader. Where could they stop and think "what does that mean?" That is the only bug that matters. Fix it and stop.
Length check: if the rewrite is longer than the original, you explained instead of simplifying. Go back to step 1.
Spanish (lectura fácil)
Same rules, plus what is specific to Spanish:
- Tuteo o usted, uno solo. Elegir según el contexto y no mezclarlo nunca en el mismo texto.
- Sin gerundios. "Cuando cambian la clave" en vez de "cambiando la clave".
- Sin voz pasiva ni impersonal con "se". "Ustedes cambian el RUT" en vez de "se debe modificar el RUT".
- Verbos simples, en presente. "Les llega un correo", no "les será enviado un correo".
- Frases de una línea. Si una frase ocupa dos líneas, hay dos ideas adentro.
- Sin anglicismos ni siglas sin explicar. La primera vez se escribe completo.
Reference standard: UNE 153101:2018 EX (lectura fácil).
Example
Client email, before (one paragraph, reason first, action buried):
Estimado usuario: respecto de la clave de acceso, informamos que por motivos de seguridad los enlaces de recuperación tienen una vigencia limitada de 24 horas, por lo que habiendo transcurrido dicho plazo el enlace enviado ya no se encuentra operativo, debiendo solicitarse uno nuevo desde la página de inicio de sesión.
After (answer first, steps, reason last):
Hola:
El enlace para cambiar la clave ya no sirve.
Haga esto:
- Entre a la página de inicio de sesión.
- Toque "Olvidé mi clave".
- Escriba su correo.
- Abra el correo nuevo y cambie la clave.
El enlace nuevo dura 24 horas.
El enlace vence por seguridad. Así nadie más puede usarlo.
Same information. The reader knows what to do after 20 seconds.
Sources
- Federal Plain Language Guidelines - short sentences, active voice, everyday words, 15-20 word average.
- Mencap - guidelines for accessible writing - one idea per sentence, plain English, no jargon or abbreviations.
- The Easy Read Standard - evidence behind short sentences and layout.
- Lectura fácil: pautas y recomendaciones, UNE 153101:2018 EX
- Lectura fácil: qué es, pautas y ejemplos (DKV)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

