|
| 1 | +--- |
| 2 | +name: writing-clearly-and-concisely |
| 3 | +description: |
| 4 | + Apply Strunk's timeless writing rules to ANY prose humans will |
| 5 | + read—documentation, commit messages, error messages, explanations, reports, or |
| 6 | + UI text. Makes your writing clearer, stronger, and more professional. |
| 7 | +--- |
| 8 | + |
| 9 | +# Writing Clearly and Concisely |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +William Strunk Jr.'s _The Elements of Style_ (1918) teaches you to write clearly |
| 14 | +and cut ruthlessly. |
| 15 | + |
| 16 | +**WARNING:** `elements-of-style.md` consumes ~12,000 tokens. Read it only when |
| 17 | +writing or editing prose. |
| 18 | + |
| 19 | +## When to Use This Skill |
| 20 | + |
| 21 | +Use this skill whenever you write prose for humans: |
| 22 | + |
| 23 | +- Documentation, README files, technical explanations |
| 24 | +- Commit messages, pull request descriptions |
| 25 | +- Error messages, UI copy, help text, comments |
| 26 | +- Reports, summaries, or any explanation |
| 27 | +- Editing to improve clarity |
| 28 | + |
| 29 | +**If you're writing sentences for a human to read, use this skill.** |
| 30 | + |
| 31 | +## Limited Context Strategy |
| 32 | + |
| 33 | +When context is tight: |
| 34 | + |
| 35 | +1. Write your draft using judgment |
| 36 | +2. Dispatch a subagent with your draft and `elements-of-style.md` |
| 37 | +3. Have the subagent copyedit and return the revision |
| 38 | + |
| 39 | +## All Rules |
| 40 | + |
| 41 | +### Elementary Rules of Usage (Grammar/Punctuation) |
| 42 | + |
| 43 | +1. Form possessive singular by adding 's |
| 44 | +2. Use comma after each term in series except last |
| 45 | +3. Enclose parenthetic expressions between commas |
| 46 | +4. Comma before conjunction introducing co-ordinate clause |
| 47 | +5. Don't join independent clauses by comma |
| 48 | +6. Don't break sentences in two |
| 49 | +7. Participial phrase at beginning refers to grammatical subject |
| 50 | + |
| 51 | +### Elementary Principles of Composition |
| 52 | + |
| 53 | +8. One paragraph per topic |
| 54 | +9. Begin paragraph with topic sentence |
| 55 | +10. **Use active voice** |
| 56 | +11. **Put statements in positive form** |
| 57 | +12. **Use definite, specific, concrete language** |
| 58 | +13. **Omit needless words** |
| 59 | +14. Avoid succession of loose sentences |
| 60 | +15. Express co-ordinate ideas in similar form |
| 61 | +16. **Keep related words together** |
| 62 | +17. Keep to one tense in summaries |
| 63 | +18. **Place emphatic words at end of sentence** |
| 64 | + |
| 65 | +### Section V: Words and Expressions Commonly Misused |
| 66 | + |
| 67 | +Alphabetical reference for usage questions |
| 68 | + |
| 69 | +## Bottom Line |
| 70 | + |
| 71 | +Writing for humans? Read `elements-of-style.md` and apply the rules. Low on |
| 72 | +tokens? Dispatch a subagent to copyedit with the guide. |
0 commit comments