| name | writing-clearly-and-concisely |
| description | Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional. |
| when_to_use | When writing or editing any text for humans—docs, commits, errors, UI copy, comments, reports, explanations. If a human will read it, apply these rules. |
| version | 1.0.0 |
| languages | all |
Writing Clearly and Concisely
Announce at start: "I'm using the writing-clearly-and-concisely skill to improve this writing."
Overview
William Strunk Jr.'s The Elements of Style (1918) teaches clear, concise writing.
Core Principle: ALL writing for humans is prose. Apply these rules to code comments, documentation, commit messages, error messages, UI text, and any explanation.
WARNING: elements-of-style.md consumes ~12,000 tokens. Read it only when writing or editing prose.
When to Use This Skill
Use this skill for ALL writing humans will read:
Code & Development
- Commit messages and PR descriptions
- Code comments explaining logic
- API documentation
- README files and guides
- Error messages and logging
Technical Writing
- Architecture docs
- Design proposals
- Technical specifications
- Internal documentation
- External user guides
Communication
- Reports and summaries
- Explanations to teammates
- UI copy and help text
- Email and messages
- Any written explanation
If a human will read it, it's prose. Apply these rules.
Common Rationalizations (Don't Accept These)
| Excuse | Reality |
|---|---|
| "Write quickly" → skip editing | Clarity ALWAYS worth the time |
| "Just internal docs" | Internal docs need clarity MORE, not less |
| "Technical writing ≠ prose" | ALL writing for humans is prose |
| "Not formal prose" | Formality ≠ clarity; informal needs clarity too |
| "Clarity isn't critical here" | This is NEVER true. Clarity is always critical. |
| "Good enough for now" | Poor writing wastes readers' time forever |
| "Too simple to need editing" | Simple writing often has the most unnecessary words |
When you hear these rationalizations, STOP and apply the rules anyway.
Limited Context Strategy
When context is tight:
- Write your draft using judgment
- Dispatch a subagent with your draft and
elements-of-style.md - Have the subagent copyedit and return the revision
All Rules (Quick Reference)
Elementary Rules of Usage (Grammar/Punctuation)
- Form possessive singular by adding 's
- Use comma after each term in series except last
- Enclose parenthetic expressions between commas
- Comma before conjunction introducing co-ordinate clause
- Don't join independent clauses by comma
- Don't break sentences in two
- Participial phrase at beginning refers to grammatical subject
Elementary Principles of Composition
- One paragraph per topic
- Begin paragraph with topic sentence
- Use active voice
- Put statements in positive form
- Use definite, specific, concrete language
- Omit needless words
- Avoid succession of loose sentences
- Express co-ordinate ideas in similar form
- Keep related words together
- Keep to one tense in summaries
- Place emphatic words at end of sentence
Section V: Words and Expressions Commonly Misused
Alphabetical reference for usage questions
Most Critical Rules (Apply These First)
Rule 10: Use Active Voice
❌ "The bug was fixed by the team" ✅ "The team fixed the bug"
❌ "Errors are handled by the system" ✅ "The system handles errors"
Rule 11: Put Statements in Positive Form
❌ "The feature is not very necessary" ✅ "The feature is unnecessary"
❌ "Did not remember" ✅ "Forgot"
Rule 13: Omit Needless Words
❌ "In my opinion, I think that..." ✅ (just make the statement)
❌ "at this point in time" ✅ "now"
❌ "allows users to be able to" ✅ "lets users"
Rule 12: Use Definite, Specific, Concrete Language
❌ "handled appropriately" ✅ "logged to stderr"
❌ "The system processes data" ✅ "The parser extracts JSON fields"
Systematic Application Process
- Write - Get ideas down first
- Review for passive voice - Convert to active (Rule 10)
- Review for negative forms - Convert to positive (Rule 11)
- Review for vague language - Make specific (Rule 12)
- Cut ruthlessly - Remove needless words (Rule 13)
- Check word order - Keep related words together (Rule 16)
Apply ALL rules systematically. Don't stop after "good enough."
Under Pressure
Time pressure or "quick docs" requests don't justify skipping these rules.
Why:
- Bad writing wastes EVERY reader's time
- Editing takes seconds; reading bad docs wastes minutes per person
- Multiply by number of readers → clarity is always worth it
When told "write quickly":
- Write the draft
- Apply rules (takes 30 seconds)
- Deliver clear result
Don't ask permission to edit. Just do it.
For Different Contexts
Commit Messages
- Subject: Omit needless words, active voice, specific
- Body: One paragraph per topic, active voice, concrete language
- Example: ❌ "Added feature that allows users to be able to search"
- Example: ✅ "feat: add history search"
Error Messages
- Active voice ("File exceeds limit" not "limit was exceeded")
- Specific ("File exceeds 10MB limit" not "file is too large")
- Positive form when possible
- Omit needless words
Documentation
- Use active voice throughout
- Be specific: actual commands, actual values, actual behavior
- One topic per paragraph
- Cut relentlessly
Code Comments
- Explain WHY, not WHAT (code shows what)
- Be specific about intent
- Active voice: "Handles edge case" not "Edge case is handled"
- Omit needless words: "// Cache for performance" not "// This variable stores a cache for performance reasons"
Bottom Line
Writing for humans? Read elements-of-style.md and apply the rules.
Low on tokens? Dispatch a subagent to copyedit with the guide.
Under pressure? Apply rules anyway. Clarity is always worth 30 seconds.
Don't accept rationalizations. All writing for humans deserves clarity.