back
loading skill details...
Write clear, concise prose for humans — documentation, READMEs, API docs, commit messages, error messages, UI text, reports, and explanations. Combines Strunk's rules for clearer prose with technical documentation patterns, structure templates, and review checklists.
---
name: clear-writing
model: standard
version: 1.0.0
description: >
Write clear, concise prose for humans — documentation, READMEs, API docs, commit messages,
error messages, UI text, reports, and explanations. Combines Strunk's rules for clearer prose
with technical documentation patterns, structure templates, and review checklists.
tags: [writing, documentation, style, technical-writing, prose]
---
# Clear Writing
Write with clarity and force. This skill covers what to do (Strunk's rules), how to structure technical documentation (Divio patterns, templates), and what not to do (AI anti-patterns, doc anti-patterns).
## When to Use
Use this skill whenever you write prose for humans:
- Documentation, README files, technical explanations
- API documentation, endpoint references, integration guides
- Tutorials, how-to guides, architecture docs
- Commit messages, pull request descriptions
- Error messages, UI copy, help text, comments
- Reports, summaries, or any explanation
- Editing existing prose to improve clarity
**If you're writing sentences for a human to read, use this skill.**
## Limited Context Strategy
When context is tight:
1. Write your draft using judgment
2. Dispatch a subagent with your draft and the relevant reference file
3. Have the subagent copyedit and return the revision
Loading a single reference (~1,000–4,500 tokens) instead of the full skill 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**:
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**
### Reference Files
For complete explanations with examples:
| Section | File | ~Tokens |
|---------|------|---------|
| Grammar, punctuation, comma rules | `references/elements-of-style/02-elementary-rules-of-usage.md` | 2,500 |
| Paragraph structure, active voice, concision | `references/elements-of-style/03-elementary-principles-of-composition.md` | 4,500 |
| Headings, quotations, formatting | `references/elements-of-style/04-a-few-matters-of-form.md` | 1,000 |
| Word choice, common errors | `references/elements-of-style/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
- **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 `references/signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
## Document Types (Divio Framework)
| Type | Purpose | Structure |
|------|---------|-----------|
| README | First impression, project overview | Title, description, quick start, install, usage |
| Tutorial | Learning-oriented, guided experience | Numbered steps with expected outcomes |
| How-to Guide | Task-oriented, solve a specific problem | Problem statement → steps → result |
| Reference | Information-oriented, complete and accurate | Alphabetical or grouped, consistent format |
| Explanation | Understanding-oriented, context and rationale | Narrative prose, diagrams, history |
| Architecture Doc | System design, component relationships | Context → components → data flow → decisions |
| API Documentation | Endpoint contracts, integration guide | Endpoint → params → request → response → errors |
## Structure Patterns
### Inverted Pyramid
Lead with the most important information. Each subsequent section adds detail.
```
1. What it does (one sentence)
2. How to use it (quick start)
3. Configuration options
4. Advanced usage
5. Internals / implementation details
```
### Problem-Solution
```
1. Problem — what goes wrong, symptoms, error messages
2. Cause — why it happens (brief)
3. Solution — step-by-step fix
4. Prevention — how to avoid it in the future
```
### Sequential Steps
Every step is a single action with a verifiable outcome.
```
1. Step — one action, one verb
Expected result: what the reader should see
2. Step — next action
Expected result: confirmation of success
```
## Writing Rules
| Rule | Guideline | Example |
|------|-----------|---------|
| Short sentences | Keep under 25 words | "The server restarts automatically after config changes." |
| Active voice | Subject does the action | "The function returns a promise" not "A promise is returned" |
| Present tense | Describe current behavior | "This endpoint accepts JSON" not "will accept JSON" |
| One idea per paragraph | Each paragraph has one point | Split compound paragraphs at the topic shift |
| Define jargon on first use | Never assume vocabulary | "The ORM (Object-Relational Mapper) translates..." |
| Second person | Address the reader directly | "You can configure..." not "One can configure..." |
| Consistent terminology | Pick one term and stick with it | Don't alternate between "repo" and "repository" |
| Concrete over abstract | Specifics beat generalities | "Returns a 404 status code" not "Returns an error" |
## Code Examples in Documentation
Every code example must follow these rules:
1. **Complete and runnable** — copy-paste and execute without modification
2. **Annotated** — comments on the non-obvious parts, not the obvious ones
3. **Progressive complexity** — simplest case first, then advanced usage
4. **Language-tagged** — always specify the language in fenced code blocks
5. **Current** — examples must work with the documented version
6. **Minimal** — show only what is relevant; strip unrelated boilerplate
```python
# Good: complete, annotated, minimal
import httpx
# Create a client with a base URL to avoid repeating it
client = httpx.Client(base_url="https://api.example.com")
# Fetch a user by ID — returns a User dict or raises for 4xx/5xx
response = client.get("/users/42")
response.raise_for_status()
user = response.json()
print(user["name"]) # "Ada Lovelace"
```
## README Template
```markdown
# Project Name
One-line description of what this project does and who it is for.
## Quick Start
The fastest path from zero to working. Three commands or fewer.
## Installation
Prerequisites, system requirements, and step-by-step install.
## Usage
Common use cases with code examples. Cover the 80% case.
## API
Public API surface — functions, classes, CLI flags, endpoints.
## Configuration
Environment variables, config files, and their defaults.
## Contributing
How to set up the dev environment, run tests, and submit changes.
## License
License name and link to the full LICENSE file.
```
**README rules:**
- Keep the quick start under 60 seconds of reader time
- Include a badge row only if badges are kept current
- Link to deeper docs rather than bloating the README
- Update the README whenever the public interface changes
## API Documentation Pattern
Document every endpoint with this structure:
```markdown
### GET /users/:id
Retrieve a single user by their unique identifier.
**Authentication:** Bearer token required
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|--------|----------|----------------------|
| id | string | Yes | The user's unique ID |
**Response: 200 OK**
{json response example}
**Error Responses:**
| Status | Code | Description |
|--------|--------------|--------------------------|
| 401 | UNAUTHORIZED | Missing or invalid token |
| 404 | NOT_FOUND | User does not exist |
```
Always document errors with: HTTP status, machine-readable error code, human-readable message, and resolution steps.
## Audience Adaptation
| Audience | Context Level | Focus | Tone |
|----------|--------------|-------|------|
| Beginner | High — define terms, explain prerequisites | What and how, step by step | Encouraging, patient |
| Intermediate | Medium — assume basic knowledge | How and best practices | Direct, practical |
| Expert | Low — skip fundamentals | Why, edge cases, tradeoffs | Concise, precise |
**Rules:**
- State the assumed audience at the top of the document
- Link to prerequisite knowledge rather than re-explaining it
- Use expandable sections (`<details>`) for beginner context in expert docs
- Never mix audience levels in the same section
## Review Checklist
Before publishing any documentation:
- [ ] **Accurate** — all code examples run, all commands work, all links resolve
- [ ] **Complete** — covers setup, happy path, error cases, and cleanup
- [ ] **Consistent** — terminology, formatting, and voice match the rest of the docs
- [ ] **Readable** — passes a cold read by someone unfamiliar with the project
- [ ] **Scannable** — headings, tables, and lists allow skimming for answers
- [ ] **Examples work** — every code block tested against the current version
- [ ] **Links valid** — no broken internal or external links
- [ ] **Audience-appropriate** — context level matches the stated audience
- [ ] **Up to date** — no references to deprecated features or old versions
- [ ] **Spellchecked** — no typos, no inconsistent capitalization
## Documentation Anti-Patterns
| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Wall of text | Readers bounce | Break into sections with headings and lists |
| Outdated docs | Erodes trust | Tie doc updates to PR checklists; date-stamp pages |
| No examples | Readers can't apply abstract descriptions | Add code examples for every public function |
| Assumed knowledge | Excludes beginners | Define terms on first use, link to prerequisites |
| Copy-paste unfriendly | Code with `$` prompts or line numbers breaks when pasted | Provide clean, runnable code blocks |
| Screenshot-only instructions | Can't be searched, go stale, inaccessible | Pair screenshots with text and commands |
## NEVER Do
1. **NEVER publish docs without testing every code example** — broken examples destroy credibility faster than anything else
2. **NEVER write docs after the fact as an afterthought** — write docs alongside the code; if you cannot explain it, the design needs work
3. **NEVER use "simply", "just", or "obviously"** — these words shame readers who are struggling and add no information
4. **NEVER mix multiple audiences in one document** — write separate beginner and advanced guides, or use clear section boundaries
5. **NEVER leave placeholder text in published docs** — "TODO", "TBD", and "lorem ipsum" signal abandonment
6. **NEVER duplicate content across documents** — link to a single source of truth; duplicates inevitably drift apart
7. **NEVER omit the date or version** — readers must know if they are looking at current information
8. **NEVER use AI puffery words** — pivotal, crucial, seamless, robust, groundbreaking, tapestry, and their ilk add nothing and signal lazy writing
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs section with reference file tokens and external context requirements, expanded procedure into 8 numbered steps with inputs/outputs per step, formalized decision points for common documentation scenarios, documented output contract across readme, api docs, tutorials and general prose with file format and testing requirements, and added concrete outcome signals with red flags for failed documentation.
write with clarity and force. this skill teaches you what to do (strunk's rules), how to structure technical documentation (divio patterns, templates), and what not to do (ai anti-patterns, doc anti-patterns).
use this skill whenever you write prose for humans: documentation, readmes, api docs, tutorials, commit messages, error messages, ui copy, reports, or any explanation. the goal is to cut needless words, use active voice, choose concrete language, and structure information so readers find what they need without friction. apply this skill to documentation, readme files, technical explanations, api references, integration guides, how-to guides, architecture docs, commit messages, pull request descriptions, error messages, ui copy, help text, comments, reports, summaries, or any explanation intended for human consumption.
reference files (optional, for context-light editing):
references/elements-of-style/02-elementary-rules-of-usage.md (~2,500 tokens) - grammar, punctuation, comma rulesreferences/elements-of-style/03-elementary-principles-of-composition.md (~4,500 tokens) - paragraph structure, active voice, concision (use this one most often)references/elements-of-style/04-a-few-matters-of-form.md (~1,000 tokens) - headings, quotations, formattingreferences/elements-of-style/05-words-and-expressions-commonly-misused.md (~4,000 tokens) - word choice, common errorscontent to write or edit:
external context:
input: document type (readme, tutorial, how-to, reference, explanation, architecture doc, or api doc).
action: select the structure pattern for that type:
output: outline with sections and subsections ready to fill.
input: target audience (beginner, intermediate, or expert).
action: set context level accordingly:
state the assumed audience at the top of the document.
output: audience statement and tone/voice decision.
input: outline from step 1, audience from step 2, content to convey.
action: apply these 8 rules from strunk's elements of style:
keep sentences under 25 words. use present tense. address the reader directly in second person. define jargon on first use. pick one term and stick with it (don't alternate between "repo" and "repository").
output: draft prose with no puffery, no empty "-ing" phrases, no promotional adjectives.
input: draft from step 3, code samples, current version number.
action: for every code example, follow these 6 rules:
$ prompts or line numbers that break pasting.python, javascript, ```bash, etc.).test every code example against the current version before publishing. broken examples destroy credibility faster than anything else.
output: working code examples, properly tagged and annotated.
input: draft from steps 3-4.
action: scan for and eliminate:
output: clean prose, specific and direct, no fluff.
input: draft from step 5.
action: break up walls of text:
output: document with clear visual hierarchy.
input: complete draft from steps 1-6.
action: verify all items:
if the document cannot explain the code or feature in clear terms, the design itself may need work. write docs alongside code, not after the fact.
output: checked, tested, ready-to-publish documentation.
input: complete draft, single reference file (most often 03-elementary-principles-of-composition.md), copyedit instructions.
action: instead of loading the full skill, send the draft plus one reference file (~1,000-4,500 tokens) to a subagent. ask it to copyedit for active voice, concision, concrete language, and clarity. request specific revisions back.
output: copyedited revision.
if you have no target audience stated in the brief: do a cold read yourself or ask a peer who doesn't know the project. if they are confused about who the docs are for, state the audience explicitly in the document (e.g., "this guide assumes you have used rest apis before but not graphql").
if the document mixes audiences (e.g., beginners and experts in the same section):
split into separate sections with clear boundaries. use expandable <details> tags to tuck beginner context into expert docs without cluttering the main narrative.
if you have too many code examples for the space: show the simplest case first, then link to a separate "advanced examples" page or section. never cut working code to save space; instead, link or reference.
if documentation is outdated: do not publish it. update it first. tie doc updates to pr checklists so they stay current. date-stamp pages with version number and last-updated date so readers know whether they are looking at current information.
if you cannot easily explain a feature in clear language: the feature design may need work. write docs alongside code. if the feature is hard to document, it is probably hard to use.
if a term is ambiguous (e.g., "repo" vs. "repository"): pick one and stick with it across all docs. create a style guide or terminology glossary if multiple people write docs.
if you inherit docs full of placeholder text ("TODO", "TBD", lorem ipsum): they signal abandonment and erode trust. remove them or finish them before publishing.
if code examples are scattered across multiple docs with the same content: consolidate into a single source of truth and link to it everywhere. duplicated content inevitably drifts apart and becomes inconsistent.
readme:
api documentation:
tutorial or how-to guide:
explanation or architecture doc:
general:
python, bash, etc.).the docs work if:
red flags (stop and fix before publishing):