writing-clearly-and-concisely

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.

Writing Clearly and Concisely

Overview

William Strunk Jr.'s The Elements of Style (1918) teaches you to write clearly and cut ruthlessly.

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 whenever you write prose for humans:

• Documentation, README files, technical explanations
• Commit messages, pull request descriptions
• Error messages, UI copy, help text, comments
• Reports, summaries, or any explanation
• Editing to improve clarity

If you're writing sentences for a human to read, use this skill.

Structure Principles

BLUF (Bottom Line Up Front)

U.S. military communication standard: put your conclusion first, then explain.

The rule: Your first sentence answers what you need and by when. The reader can act without reading further.

Structure:

1. BLUF statement (1-2 sentences): the decision, action, or key point
2. Supporting context: only what's needed to understand or act

Test: Can someone act on your message after reading only the first sentence?

Before: "I've been working on the marketing materials for the conference. The design team worked hard on the layout. Could you take a look when you get a chance?"

After: "I need you to approve the attached flyer by noon Friday. It's for the August conference."

Skip BLUF when:

• Delivering bad news (empathy first)
• Skeptical audience (persuade before concluding)
• Technical topics requiring foundation (explain concepts first—see below)

See: https://en.wikipedia.org/wiki/BLUF_(communication)

Explain Concepts Before Using Them

Information must be disclosed in the correct order. Never reference a term, concept, or acronym before you've defined it. If you use it, the reader must already understand it.

Limited Context Strategy

When context is tight:

1. Write your draft using judgment
2. Dispatch a subagent with your draft and elements-of-style.md
3. Have the subagent copyedit and return the revision

If you REALLY REALLY need to preserve context, you can skip the full elements-of-style.md and instead use Orwell's rules:

• Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
• Never use a long word where a short one will do.
• If it is possible to cut a word out, always cut it out.
• Never use the passive where you can use the active.
• Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
• Break any of these rules sooner than say anything outright barbarous.

All Rules

Elementary Rules of Usage (Grammar/Punctuation)

1. Form possessive singular by adding 's
2. Use comma after each term in series except last
3. Enclose parenthetic expressions between commas
4. Comma before conjunction introducing co-ordinate clause
5. Don't join independent clauses by comma
6. Don't break sentences in two
7. Participial phrase at beginning refers to grammatical subject

Elementary Principles of Composition

8. One paragraph per topic
9. Begin paragraph with topic sentence
10. Use active voice
11. Put statements in positive form
12. Use definite, specific, concrete language
13. Omit needless words
14. Avoid succession of loose sentences
15. Express co-ordinate ideas in similar form
16. Keep related words together
17. Keep to one tense in summaries
18. Place emphatic words at end of sentence

Section V: Words and Expressions Commonly Misused

Alphabetical reference for usage questions

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.