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.
80
69%
Does it follow best practices?
Impact
96%
1.01xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/writing-clearly-and-concisely/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description with a clear 'Use when' clause and good trigger term coverage across multiple content types. Its main weakness is that the actual capabilities are described abstractly ('Applies Strunk's timeless rules') rather than listing specific concrete actions the skill performs. The broad scope also creates some risk of overlap with other writing-related skills.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Eliminates passive voice, cuts unnecessary words, tightens sentence structure, enforces parallel construction.'
Sharpen distinctiveness by clarifying what differentiates this from general editing or style guide skills—e.g., 'Focuses on conciseness and clarity per Elements of Style, not tone or brand voice.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (prose writing) and lists several types of content (documentation, commit messages, error messages, etc.), but the actual actions are vague—'Applies Strunk's timeless rules' doesn't specify concrete actions like 'removes passive voice, eliminates unnecessary words, tightens sentence structure.' | 2 / 3 |
Completeness | Explicitly answers both 'what' (applies Strunk's rules for clearer, stronger, more professional writing) and 'when' (opens with 'Use when writing prose humans will read' followed by specific content types). The 'Use when...' clause is present and clear. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would actually say: 'documentation', 'commit messages', 'error messages', 'explanations', 'reports', 'UI text', 'writing', 'prose'. These cover a good range of common variations. | 3 / 3 |
Distinctiveness Conflict Risk | While 'Strunk's rules' provides some distinctiveness, the broad scope of 'writing prose humans will read' could overlap with other writing, editing, or style guide skills. The niche is somewhat defined but not sharply bounded. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is well-structured with strong progressive disclosure and a clear reference architecture pointing to supporting files. Its main weaknesses are the lack of concrete before/after examples demonstrating the rules in action, and some verbosity in framing sections that could be tightened. The content would benefit significantly from showing rather than telling—a quick transformation example would make the guidance immediately actionable.
Suggestions
Add 1-2 concrete before/after examples showing a sentence transformed by applying key rules (e.g., active voice, omitting needless words, avoiding AI puffery)
Trim the 'When to Use This Skill' section—the bullet list of contexts is obvious and the bold summary restates what the bullets already say
Add an explicit edit workflow: draft → identify violations → revise → re-check, especially for the common case of editing existing text
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but includes some unnecessary framing ('William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly') and the 'When to Use This Skill' section over-explains with a bullet list of obvious contexts plus a bold summary line. The enumerated rules list is borderline—useful as a reference but takes significant space for content that could be more compressed. | 2 / 3 |
Actionability | Provides concrete lists of what to avoid and references to follow, plus a subagent dispatch strategy, but lacks executable examples. No before/after writing samples, no concrete demonstration of applying the rules to actual text. The guidance is specific in what to avoid but doesn't show how to transform bad prose into good prose. | 2 / 3 |
Workflow Clarity | The 'Limited Context Strategy' provides a clear 3-step workflow for subagent dispatch, which is good. However, the overall writing workflow is implicit—there's no clear sequence for 'draft → check against rules → revise → verify.' For a skill about editing prose, a more explicit edit-validate loop would strengthen this. | 2 / 3 |
Progressive Disclosure | Excellent structure with a clear overview, well-organized reference table showing file names and token costs, and explicit guidance on which file to load for most tasks. References are one level deep and clearly signaled with a table format. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- softaworks/agent-toolkit
- Commit
3027f20
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.