Back to Documentation & Writing
writing-clearly-and-concisely
technical writingdocumentationclear communicationconcise writingenglish grammarprofessional writingcommit messagesUI text
Install this skill
npx skills add softaworks/agent-toolkitWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
This skill enforces precision and brevity in technical communication by applying the foundational principles of Strunk’s Elements of Style. It provides a structured framework for agents to audit prose, ensuring it remains direct, active, and free from the stylistic bloat common in machine-generated text. The agent acts as an automated editor, scanning documentation, commit logs, and UI strings to eliminate redundant phrasing, passive constructions, and buzzword-heavy jargon. By isolating specific stylistic rules—such as prioritizing topic sentences and placing emphatic words at the end of sentences—the agent transforms vague descriptions into concrete instructions. This approach replaces generic, puffy AI tendencies with a professional, human-readable tone. Use this toolkit to sharpen technical explanations and refine high-stakes copy, ensuring your writing conveys information efficiently without extraneous fluff or ambiguous descriptors.
When to Use This Skill
- •Refining technical documentation to be more readable for developers
- •Polishing commit messages for clarity and maintainability
- •Editing UI labels and help text to minimize ambiguity
- •Improving the focus and impact of project README files
- •Correcting draft reports to ensure a consistent, professional tense
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Edit this documentation to be more direct
- “Rewrite these release notes to sound less robotic
- “Check my draft against the principles of composition
- “Remove filler words and improve clarity in this snippet
- “Apply Strunk's rules to this paragraph
Pro Tips
- 💡**Iterative Refinement**: After initial generation, run the output through this skill again with a prompt like 'Review and refine for clarity and conciseness according to Strunk's principles.'
- 💡**Contextual Application**: When limited on context, focus the subagent on specific sections (e.g., 'copyedit this README section') to maximize impact without exhausting token limits.
- 💡**Read Aloud Check**: Instruct the agent to 'simulate reading this aloud to check for awkward phrasing or run-on sentences' before finalizing the output, mimicking a human review process.
What this skill does
- •Identifies and converts passive voice into active, direct statements
- •Prunes redundant adjectives and filler words to increase clarity
- •Applies Strunk-inspired grammatical rules for consistent punctuation
- •Filters out hallmark AI-generated vocabulary and cliches
- •Restructures paragraphs to ensure each focuses on a single topic
When not to use it
- ✕Creative writing where complex or poetic sentence structure is intentional
- ✕Legal or compliance documents that require specific, archaic jargon
Example workflow
- Provide the raw text draft to the agent
- Select the specific reference file from the toolkit corresponding to the editing goal
- Instruct the agent to perform an audit focusing on passive voice and word count
- Review the suggested revisions for adherence to stylistic constraints
- Commit the finalized, concise version to the project
Prerequisites
- –Access to the softaworks/agent-toolkit repository
- –A target text block to be audited
Pitfalls & limitations
- !Over-editing can sometimes remove necessary nuance in complex technical discussions
- !The agent may misinterpret domain-specific technical jargon as 'needless words'
- !Ignoring the specific context of the document may lead to overly rigid tone shifts
FAQ
Which reference file should I use for most editing tasks?
For the vast majority of documentation tasks, 03-elementary-principles-of-composition.md is sufficient as it covers active voice, concision, and paragraph structure.
How does this prevent 'AI-sounding' writing?
The skill specifically flags and removes common LLM tropes like 'leverage', 'vital', and 'seamless', forcing the output to remain grounded in concrete language.
Can I use this for non-technical writing?
Yes, the principles are based on universal stylistic rules that improve clarity in any form of prose intended for a human audience.
How it compares
Generic prompts often fail to remove specific AI patterns because the model favors its own training bias; this skill uses deterministic reference material to systematically override those biases.
📄 Full skill instructions — original source: softaworks/agent-toolkit
# 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 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:
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**:
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
The rules above are summarized from Strunk's original text. For complete explanations with examples:
| Section | File | ~Tokens |
|---------|------|---------|
| Grammar, punctuation, comma rules |
| Paragraph structure, active voice, concision |
| Headings, quotations, formatting |
| Word choice, common errors |
**Most tasks need only
## 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
## Bottom Line
Writing for humans? Load the relevant section from
## 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:
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**:
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
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.By Softaworks
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/writing-clearly-and-concisely/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/softaworks/agent-toolkit/writing-clearly-and-concisely/SKILL.md - Cursor:
~/.cursor/skills/softaworks/agent-toolkit/writing-clearly-and-concisely/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/softaworks/agent-toolkit/writing-clearly-and-concisely/SKILL.md
🚀 Install with CLI:npx skills add softaworks/agent-toolkit
Recommended Rules
View more rules →Go Web Development Expert
GoWeb DevelopmentGin
You are an expert in Go web development using standard library and frameworks like Gin, Echo, and Fiber. Key Principles: - Use standard net/http for ...
Go Microservices Architecture
GoMicroservicesArchitecture
You are an expert in designing and building microservices with Go. Key Principles: - Decouple services by domain - Design for failure - Use lightweig...
Go Testing & Benchmarking
GoTestingBenchmarking
You are an expert in Go testing, benchmarking, and quality assurance. Key Principles: - Test behavior, not implementation - Keep tests fast and relia...
Recommended Workflows
View more workflows →Create GitHub PR Template
GitGitHubTeam
--- description: Standardize pull request descriptions for better code reviews --- 1. **Create Template Directory**: - GitHub looks for templates ...
Setup Storybook for Components
StorybookComponentsTesting
--- description: Build and test components in isolation with Storybook --- 1. **Install Storybook**: - Initialize Storybook in your project. //...
Automatic commit message generator
GitAIAutomation
--- description: Automatic commit message generator and fast AI-powered commit for all current changes --- // turbo-all This workflow automatically ...
