Writing Clearly

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
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:

- [ ] Active voice? (not "was done by")
- [ ] Positive form? (not "did not")
- [ ] Specific and concrete? (numbers, examples)
- [ ] No needless words? ("in order to" -> "to")
- [ ] No AI vocabulary? (delve, leverage, robust, seamless)
- [ ] No inflated significance? (groundbreaking, pivotal, testament)
- [ ] No filler phrases? ("it's important to note")
- [ ] No sycophantic tone? ("great question!")
- [ ] Related words together?
- [ ] Emphasis at end of sentence?

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

- Based on [softaworks/agent-toolkit writing-clearly-and-concisely](https://github.com/softaworks/agent-toolkit/tree/main/skills/writing-clearly-and-concisely) (MIT License)
- William Strunk Jr., *The Elements of Style* (1918)
- Wikipedia [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) (WikiProject AI Cleanup)

<!-- Source: .faos/custom/skills/documentation/writing-clearly/SKILL.md -->