Follow concise writing principles: express clearly, cut decisively.
When to use
Use this skill when writing the following reader-facing text:
- Documentation, READMEs, and technical notes
- Commit messages and merge request descriptions
- Error messages, interface copy, help text, and comments
- Reports, summaries, and other explanatory text
- Editing tasks aimed at improving clarity
Use this skill whenever text needs to be read by a person.
Writing rules
All reader-facing text must follow these rules:
- Prefer short, direct sentences.
- Use the active voice unless the passive voice is clearly clearer.
- State things in the affirmative.
- Use precise, concrete, verifiable words.
- Delete useless words.
- Keep related words close together.
- Put conclusions first; when emphasis is needed, put the key point at the end of the sentence.
- Express only one topic per paragraph.
- Avoid stock phrases, repetition, excessive hedging, and promotional language.
- Use vague qualifiers such as "probably," "maybe," and "basically" only when the uncertainty is genuinely meaningful.
- Do not write long openings or metadiscourse.
- Delete sentences that do not affect the meaning.
Before outputting the final content, silently rewrite it once to further improve concision and clarity.
Prohibited writing
- Do not open with empty responses such as "OK," "Of course," or "That's a great question."
- Do not explain obvious steps.
- Do not restate the user's request unless needed to remove ambiguity.
- Do not use long lists when short paragraphs suffice.
- Do not use promotional, sentimental, or flattering language.