name: writing-clearly
description: Apply Strunk's Elements of Style rules and AI writing anti-pattern detection to any prose. Use when writing documentation, commit messages, error messages, reports, UI text, or any content humans will read. Covers active voice, positive form, concrete language, omitting needless words, and detecting AI-generated writing patterns.
tags: [writing, clarity, style, prose]
Writing Clearly and Concisely
Write with clarity and force. Apply Strunk's timeless rules and avoid AI writing patterns.
When to Use
Whenever you write prose for humans:
- Documentation, README files, technical explanations
- Commit messages, pull request descriptions
- Error messages, UI copy, help text
- Reports, summaries, PRDs
- Any content that will be read by a person
The Key Rules (Strunk)
1. Use Active Voice
| Passive (avoid) |
Active (prefer) |
| "The config was updated by the script" |
"The script updated the config" |
| "Errors are logged by the middleware" |
"The middleware logs errors" |
| "It was decided that..." |
"We decided..." |
2. Put Statements in Positive Form
| Negative (avoid) |
Positive (prefer) |
| "did not remember" |
"forgot" |
| "did not have much confidence in" |
"distrusted" |
| "not important" |
"trivial" |
| "does not have" |
"lacks" |
3. Use Definite, Specific, Concrete Language
| Vague (avoid) |
Specific (prefer) |
| "A period of bad weather" |
"It rained for three days" |
| "The system performs well" |
"The API responds in <50ms at p99" |
| "Many users were affected" |
"2,400 users saw errors for 12 minutes" |
4. Omit Needless Words
| Wordy (avoid) |
Concise (prefer) |
| "the question as to whether" |
"whether" |
| "there is no doubt but that" |
"no doubt" / "doubtless" |
| "in order to" |
"to" |
| "the fact that" |
(omit, rephrase) |
| "at this point in time" |
"now" |
| "due to the fact that" |
"because" |
| "in the event that" |
"if" |
5. Keep Related Words Together
Bad: "The dog was found by the children playing in the yard."
Good: "The children playing in the yard found the dog."
6. Place Emphatic Words at End of Sentence
Weak: "Humanity has barely begun to explore space, which is vast."
Strong: "Humanity has barely begun to explore the vast reaches of space."
7. One Paragraph, One Topic
Each paragraph should develop one idea. The first sentence should state the topic.
8. Express Coordinate Ideas in Similar Form
Bad: "The team values speed, being reliable, and to have clear communication."
Good: "The team values speed, reliability, and clear communication."
AI Writing Patterns to Avoid
Inflated Language
| AI Pattern |
Human Alternative |
| pivotal, crucial, vital |
important |
| testament to |
shows, proves |
| groundbreaking, revolutionary |
new, significant |
| transformative |
changes |
| multifaceted |
complex |
| delve into |
explore, look at |
| leverage |
use |
| foster |
encourage, build |
| garner |
get, earn |
| realm |
area, field |
| tapestry |
(remove) |
| underscore |
emphasize, show |
| robust |
strong, reliable |
| seamless |
smooth |
Structural Patterns
| Pattern |
Fix |
| Rule of three everywhere |
Use the actual number of items |
| "Not only...but also..." |
Rephrase simply |
| Em dash in every paragraph |
One per paragraph max, zero is fine |
| Bold on every other phrase |
Sparingly, for genuinely important terms |
| Synonym cycling (platform/solution/system/framework) |
Repeat the same word for clarity |
| "From X to Y" false ranges |
Be specific or remove |
| Formulaic transitions (Furthermore, Moreover) |
Just start the next paragraph |
Communication Artifacts
Remove these completely:
- "I hope this helps!"
- "Let me know if you need anything else!"
- "That's a great question!"
- "As of my last update..."
- "It's important to note that..." (just state it)
- "It's worth mentioning that..." (just state it)
Hedging and Filler
| Remove |
Action |
| "It could potentially be argued that this might possibly..." |
Take a position or present evidence |
| "Arguably the best" |
"The best" or present data |
| Excessive qualifiers |
State things directly |
Copula Avoidance
AI avoids "is/are" by using "serves as", "stands as", "functions as":
AI: "The gateway serves as the primary entry point and functions as a security boundary."
Human: "The gateway is the entry point and security boundary."
Quick Checklist
When writing or editing prose:
Anti-Patterns
| Avoid |
Why |
Instead |
| Over-correcting to casual |
Loses professionalism |
Clear and direct, not chatty |
| Removing all structure |
Lists and headers help readability |
Keep structure, remove formulaic patterns |
| Adding forced personality |
Sounds worse than AI |
Let clarity be the personality |
| Sacrificing accuracy for brevity |
Meaning matters most |
Keep technical precision, cut fluff |
References
1---2name: writing-clearly3description: <!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->4---5<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->6---7name: writing-clearly8description: Apply Strunk's Elements of Style rules and AI writing anti-pattern detection to any prose. Use when writing documentation, commit messages, error messages, reports, UI text, or any content humans will read. Covers active voice, positive form, concrete language, omitting needless words, and detecting AI-generated writing patterns.9tags: [writing, clarity, style, prose]10---1112# Writing Clearly and Concisely1314Write with clarity and force. Apply Strunk's timeless rules and avoid AI writing patterns.1516## When to Use1718Whenever you write prose for humans:19- Documentation, README files, technical explanations20- Commit messages, pull request descriptions21- Error messages, UI copy, help text22- Reports, summaries, PRDs23- Any content that will be read by a person2425## The Key Rules (Strunk)2627### 1. Use Active Voice2829| Passive (avoid) | Active (prefer) |30|---|---|31| "The config was updated by the script" | "The script updated the config" |32| "Errors are logged by the middleware" | "The middleware logs errors" |33| "It was decided that..." | "We decided..." |3435### 2. Put Statements in Positive Form3637| Negative (avoid) | Positive (prefer) |38|---|---|39| "did not remember" | "forgot" |40| "did not have much confidence in" | "distrusted" |41| "not important" | "trivial" |42| "does not have" | "lacks" |4344### 3. Use Definite, Specific, Concrete Language4546| Vague (avoid) | Specific (prefer) |47|---|---|48| "A period of bad weather" | "It rained for three days" |49| "The system performs well" | "The API responds in <50ms at p99" |50| "Many users were affected" | "2,400 users saw errors for 12 minutes" |5152### 4. Omit Needless Words5354| Wordy (avoid) | Concise (prefer) |55|---|---|56| "the question as to whether" | "whether" |57| "there is no doubt but that" | "no doubt" / "doubtless" |58| "in order to" | "to" |59| "the fact that" | (omit, rephrase) |60| "at this point in time" | "now" |61| "due to the fact that" | "because" |62| "in the event that" | "if" |6364### 5. Keep Related Words Together6566**Bad**: "The dog was found by the children playing in the yard."67**Good**: "The children playing in the yard found the dog."6869### 6. Place Emphatic Words at End of Sentence7071**Weak**: "Humanity has barely begun to explore space, which is vast."72**Strong**: "Humanity has barely begun to explore the vast reaches of space."7374### 7. One Paragraph, One Topic7576Each paragraph should develop one idea. The first sentence should state the topic.7778### 8. Express Coordinate Ideas in Similar Form7980**Bad**: "The team values speed, being reliable, and to have clear communication."81**Good**: "The team values speed, reliability, and clear communication."8283## AI Writing Patterns to Avoid8485### Inflated Language8687| AI Pattern | Human Alternative |88|---|---|89| pivotal, crucial, vital | important |90| testament to | shows, proves |91| groundbreaking, revolutionary | new, significant |92| transformative | changes |93| multifaceted | complex |94| delve into | explore, look at |95| leverage | use |96| foster | encourage, build |97| garner | get, earn |98| realm | area, field |99| tapestry | (remove) |100| underscore | emphasize, show |101| robust | strong, reliable |102| seamless | smooth |103104### Structural Patterns105106| Pattern | Fix |107|---|---|108| Rule of three everywhere | Use the actual number of items |109| "Not only...but also..." | Rephrase simply |110| Em dash in every paragraph | One per paragraph max, zero is fine |111| Bold on every other phrase | Sparingly, for genuinely important terms |112| Synonym cycling (platform/solution/system/framework) | Repeat the same word for clarity |113| "From X to Y" false ranges | Be specific or remove |114| Formulaic transitions (Furthermore, Moreover) | Just start the next paragraph |115116### Communication Artifacts117118Remove these completely:119- "I hope this helps!"120- "Let me know if you need anything else!"121- "That's a great question!"122- "As of my last update..."123- "It's important to note that..." (just state it)124- "It's worth mentioning that..." (just state it)125126### Hedging and Filler127128| Remove | Action |129|---|---|130| "It could potentially be argued that this might possibly..." | Take a position or present evidence |131| "Arguably the best" | "The best" or present data |132| Excessive qualifiers | State things directly |133134### Copula Avoidance135136AI avoids "is/are" by using "serves as", "stands as", "functions as":137138**AI**: "The gateway serves as the primary entry point and functions as a security boundary."139**Human**: "The gateway is the entry point and security boundary."140141## Quick Checklist142143When writing or editing prose:144145- [ ] Active voice? (not "was done by")146- [ ] Positive form? (not "did not")147- [ ] Specific and concrete? (numbers, examples)148- [ ] No needless words? ("in order to" -> "to")149- [ ] No AI vocabulary? (delve, leverage, robust, seamless)150- [ ] No inflated significance? (groundbreaking, pivotal, testament)151- [ ] No filler phrases? ("it's important to note")152- [ ] No sycophantic tone? ("great question!")153- [ ] Related words together?154- [ ] Emphasis at end of sentence?155156## Anti-Patterns157158| Avoid | Why | Instead |159|---|---|---|160| Over-correcting to casual | Loses professionalism | Clear and direct, not chatty |161| Removing all structure | Lists and headers help readability | Keep structure, remove formulaic patterns |162| Adding forced personality | Sounds worse than AI | Let clarity be the personality |163| Sacrificing accuracy for brevity | Meaning matters most | Keep technical precision, cut fluff |164165## References166167- Based on [softaworks/agent-toolkit writing-clearly-and-concisely](https://github.com/softaworks/agent-toolkit/tree/main/skills/writing-clearly-and-concisely) (MIT License)168- William Strunk Jr., *The Elements of Style* (1918)169- Wikipedia [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) (WikiProject AI Cleanup)170171<!-- Source: .faos/custom/skills/documentation/writing-clearly/SKILL.md -->
frank-luongt