writing-clearly-and-concisely

---
name: writing-clearly-and-concisely
description:
  Apply whenever writing content a human will read — emails, documents, reports, documentation, messages, UI copy,
  commit messages, explanations, or any other prose. Applies Strunk's timeless rules for clearer, stronger, more
  professional writing.
---

# Writing Clearly and Concisely

## Overview

Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).

## When to Use This Skill

Use this skill whenever you write content a human will read:

- Emails, messages, and any direct communication
- Documents, reports, summaries, proposals
- Documentation, README files, technical explanations
- Commit messages, pull request descriptions
- Error messages, UI copy, help text, comments
- Any other prose meant for human eyes

**If a human will read it, this skill applies — no exceptions.**

## Limited Context Strategy

When context is tight:

1. Write your draft using judgment
2. Dispatch a subagent with your draft and the relevant section file
3. Have the subagent copyedit and return the revision

Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.

## Elements of Style

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

### 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**:

1. One paragraph per topic
2. Begin paragraph with topic sentence
3. **Use active voice**
4. **Put statements in positive form**
5. **Use definite, specific, concrete language**
6. **Omit needless words**
7. Avoid succession of loose sentences
8. Express co-ordinate ideas in similar form
9. **Keep related words together**
10. Keep to one tense in summaries
11. **Place emphatic words at end of sentence**

### Reference Files

The rules above are summarized from Strunk's original text. For complete explanations with examples:

| Section                                      | File                                           | ~Tokens |
| -------------------------------------------- | ---------------------------------------------- | ------- |
| Grammar, punctuation, comma rules            | `02-elementary-rules-of-usage.md`              | 2,500   |
| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md`   | 4,500   |
| Headings, quotations, formatting             | `04-a-few-matters-of-form.md`                  | 1,000   |
| Word choice, common errors                   | `05-words-and-expressions-commonly-misused.md` | 4,000   |

**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete
language, and omitting needless words.

## AI Writing Patterns to Avoid

LLMs regress to statistical means, producing generic, puffy prose. Avoid:

- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
- **Em dashes:** never use em dashes (— or --); restructure the sentence instead
- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word

Be specific, not grandiose. Say what it actually does.

For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this
guide to detect AI-generated submissions — their patterns are well-documented and field-tested.

## Bottom Line

Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks,
`03-elementary-principles-of-composition.md` covers what matters most.

More agent context in JanDeDobbeleer/oh-my-posh

12 other files this repository gives its agents.