Writing Clearly and Concisely
FreeEnhance your writing for better clarity and professionalism.
Free · Opens the source repo
What Writing Clearly and Concisely does
The 'Writing Clearly and Concisely' skill is designed to improve the quality of prose intended for human readers. By leveraging the principles outlined in William Strunk Jr.'s The Elements of Style, this skill provides guidance on how to write with clarity and precision. It is particularly useful for developers and designers who need to produce documentation, commit messages, error messages, and other forms of technical writing. The skill emphasizes the importance of using active voice, concrete language, and concise expression to convey information effectively.
This skill is structured around a series of reference files that cover essential rules of grammar, composition, and common pitfalls in writing. Users can load specific sections based on their immediate needs, allowing for focused editing and improvement of their drafts. For instance, the section on elementary principles of composition is especially relevant for most writing tasks, as it addresses key aspects such as paragraph structure and the avoidance of unnecessary words. In addition, the skill provides insights into common AI writing patterns that should be avoided to maintain a human touch in writing.
By using this skill, writers can enhance their documentation and communication efforts, ensuring that their messages are clear and professional. Whether you are drafting a technical report or writing UI text, applying these principles can significantly improve readability and user understanding. This skill is a valuable resource for anyone looking to refine their writing skills and produce high-quality content that resonates with readers.
When to use it
Use this skill whenever you are writing text intended for human readers, such as documentation, error messages, or UI copy.
When not to use it
This skill may not be suitable for creative writing or contexts where stylistic flair is prioritized over clarity.
What you can build with it
Improving Technical Documentation
Utilize the skill to refine technical documentation, ensuring clarity and ease of understanding for users.
Crafting Effective Commit Messages
Apply the principles to write clear and concise commit messages that accurately reflect code changes.
Enhancing UI Text
Use the skill to edit and improve UI copy, making it more user-friendly and straightforward.
How to install Writing Clearly and Concisely
View source1. Install with the skills CLI
npx skills add davila7/claude-code-templates/writing-clearly-and-concisely --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by davila7Writing 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 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.
Limited Context Strategy
When context is tight:
- Write your draft using judgment
- Dispatch a subagent with your draft and the relevant section file
- 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):
- Form possessive singular by adding 's
- Use comma after each term in series except last
- Enclose parenthetic expressions between commas
- Comma before conjunction introducing co-ordinate clause
- Don't join independent clauses by comma
- Don't break sentences in two
- Participial phrase at beginning refers to grammatical subject
Elementary Principles of Composition:
- One paragraph per topic
- Begin paragraph with topic sentence
- Use active voice
- Put statements in positive form
- Use definite, specific, concrete language
- Omit needless words
- Avoid succession of loose sentences
- Express co-ordinate ideas in similar form
- Keep related words together
- Keep to one tense in summaries
- 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
- 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.
Frequently asked questions about Writing Clearly and Concisely
Similar skills
Supabase Docs Authoring
Streamline your Supabase documentation process.
Docs Writer
Streamline your documentation process with precision.
Clinical Case Report
Generate structured medical case presentations.
CrossFrame Suite
Streamline complex workflows for Chinese structural analysis.
Em Dash Expert
Master the em dash for clear, precise writing.
Nature Statistics Reporting
Enhance manuscript statistics for high-impact journal submissions.