writing-clearly-and-concisely
Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.
68
53%
Does it follow best practices?
Impact
94%
1.02xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-mikeastock/skills/writing-clearly-and-concisely/SKILL.mdQuality
Discovery
50%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description communicates a reasonable sense of what the skill does—applying Strunk-style writing principles to various prose types—but lacks concrete action verbs describing specific transformations and has no explicit 'Use when...' clause. The use of second person ('Makes your writing') is a minor voice issue, and the broad scope risks overlap with other writing/editing skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to improve, tighten, edit, or proofread any written text, or mentions Strunk, style rules, or concise writing.'
Replace vague outcome language ('clearer, stronger, more professional') with specific actions like 'eliminates unnecessary words, converts passive voice to active, enforces parallel structure, tightens sentences.'
Switch from second person ('Makes your writing') to third person ('Makes prose clearer') to align with expected voice conventions.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (writing improvement) and lists several content types (documentation, commit messages, error messages, etc.), but the actual actions are vague—'makes your writing clearer, stronger, and more professional' is aspirational rather than describing concrete actions like 'removes unnecessary words, converts passive voice to active voice, enforces parallel construction.' | 2 / 3 |
Completeness | The 'what' is partially addressed (apply Strunk's writing rules to prose), but there is no explicit 'Use when...' clause or equivalent trigger guidance. The list of content types implies when to use it, but this is not an explicit trigger statement, which caps this at 2 per the rubric guidelines. | 2 / 3 |
Trigger Term Quality | Includes some useful trigger terms like 'documentation', 'commit messages', 'error messages', 'UI text', and 'writing', but misses natural user phrases like 'edit my writing', 'improve this text', 'proofread', 'style guide', 'concise', or 'Strunk and White'. The term 'Strunk' alone may not be what users naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The reference to 'Strunk's timeless writing rules' provides some distinctiveness, but the broad scope ('ANY prose humans will read') could overlap with general editing, proofreading, or other writing improvement skills. It's somewhat specific but not clearly carved into a unique niche. | 2 / 3 |
Total | 8 / 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 good progressive disclosure, appropriately keeping the detailed style guide in a separate file. However, it lacks actionable examples—before/after demonstrations of applying the rules would significantly improve it. The content is moderately concise but has some redundancy between the overview, 'when to use' section, and 'bottom line.'
Suggestions
Add 1-2 concrete before/after examples showing how to apply key rules (e.g., active voice, omit needless words) to documentation or commit messages.
Remove the 'Bottom Line' section as it repeats the overview and 'When to Use' sections without adding new information.
Add a brief validation step to the workflow, such as 'After editing, verify each change against a specific rule number' to create a feedback loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient but has some unnecessary padding. The 'If you're writing sentences for a human to read, use this skill' line is redundant after the bullet list. The 'Bottom Line' section largely repeats the overview. The enumeration of all 18 rules is borderline—useful as a reference but takes space when the full guide is in elements-of-style.md. | 2 / 3 |
Actionability | Provides a concrete subagent strategy and references the external guide, but lacks executable examples. There are no before/after writing examples, no demonstration of how to apply the rules, and no concrete editing workflow beyond 'read the file and apply the rules.' The rule list is descriptive rather than instructive. | 2 / 3 |
Workflow Clarity | The limited context strategy provides a clear 3-step sequence, which is good. However, the primary workflow ('read elements-of-style.md and apply the rules') is vague with no validation or feedback loop. There's no step for reviewing edits against specific rules or checking quality of the revision. | 2 / 3 |
Progressive Disclosure | Good structure: concise overview in SKILL.md with clear signaling that the detailed content lives in elements-of-style.md. The token warning is helpful. References are one level deep and clearly signaled. The sections are well-organized for quick scanning. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
99da384
- 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.