writing-clearly-and-concisely
Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
- Installs
- 4.3K
- Last 24h
- —
- Trending rank
- —
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/softaworks/agent-toolkit --skill writing-clearly-and-concisely- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads writing-clearly-and-concisely automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
- 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.
FAQ
What does the writing-clearly-and-concisely skill do?
Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
How do I install writing-clearly-and-concisely?
Run npx skills add https://github.com/softaworks/agent-toolkit --skill writing-clearly-and-concisely in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/writing-clearly-and-concisely/ (personal) or .claude/skills/writing-clearly-and-concisely/ (project).
Which AI agents can use writing-clearly-and-concisely?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is writing-clearly-and-concisely safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains writing-clearly-and-concisely?
It is published by softaworks in softaworks/agent-toolkit. It has 4,321 recorded installs.
More from softaworks/agent-toolkit
mermaid-diagrams
softaworks/agent-toolkit
Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.
humanizer
softaworks/agent-toolkit
Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases. Credits: Original skill by @blader - https://github.com/blader/humanizer
database-schema-designer
softaworks/agent-toolkit
Design robust, scalable database schemas for SQL and NoSQL databases. Provides normalization guidelines, indexing strategies, migration patterns, constraint design, and performance optimization. Ensures data integrity, query performance, and maintainable data models.
qa-test-planner
softaworks/agent-toolkit
Generate comprehensive test plans, manual test cases, regression test suites, and bug reports for QA engineers. Includes Figma MCP integration for design validation.
skill-judge
softaworks/agent-toolkit
Evaluate Agent Skill design quality against official specifications and best practices. Use when reviewing, auditing, or improving SKILL.md files and skill packages. Provides multi-dimensional scoring and actionable improvement suggestions.
c4-architecture
softaworks/agent-toolkit
Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.