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.

1.01x

Quality

69%

Does it follow best practices?

Impact

96%

1.01x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./writing-clearly-and-concisely/SKILL.md

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill has strong progressive disclosure and a well-organized reference structure, making it easy to navigate. Its main weaknesses are the lack of concrete before/after examples demonstrating the rules in action, and some redundancy between the overview, 'when to use,' and 'bottom line' sections. Adding worked examples and tightening the framing sections would significantly improve actionability and conciseness.

Suggestions

Add 2-3 before/after examples showing a sentence rewritten using the key rules (active voice, omit needless words, positive form) to make the guidance immediately actionable.

Consolidate the 'Overview,' 'When to Use This Skill,' and 'Bottom Line' sections — they repeat similar information and could be a single 2-3 line introduction.

Add an explicit revision workflow: e.g., '1. Draft → 2. Check for AI patterns → 3. Apply Strunk rules (active voice, cut needless words) → 4. Read aloud for flow → 5. Final pass for specificity.'

Dimension	Reasoning	Score
Conciseness	Mostly efficient but has some unnecessary padding. The 'When to Use This Skill' section over-explains with examples Claude could infer, and the bold callout 'If you're writing sentences for a human to read, use this skill' is redundant. The overview and bottom line sections repeat similar information. However, the reference table and rule listings are appropriately compact.	2 / 3
Actionability	Provides concrete guidance on what to avoid (AI patterns list) and references specific rules, but lacks executable examples showing before/after transformations. The skill tells Claude what rules to follow but doesn't demonstrate applying them — no example of rewriting a bad sentence into a good one, which would make the guidance truly actionable.	2 / 3
Workflow Clarity	The 'Limited Context Strategy' provides a clear 3-step workflow for subagent dispatch, which is useful. However, the main writing workflow is implicit — there's no clear sequence like 'draft → apply rules → check for AI patterns → revise.' For a skill about editing prose, a concrete revision workflow with checkpoints would strengthen this.	2 / 3
Progressive Disclosure	Excellent progressive disclosure structure. The skill provides a concise overview with numbered rules, then clearly signals one-level-deep references via a well-organized table with file names and token counts. The recommendation to start with '03-elementary-principles-of-composition.md' for most tasks is a smart navigation aid. References are clearly signaled and appropriately structured.	3 / 3
	Total	9 / 12 Passed

Description

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 that clearly communicates when to use the skill with an explicit 'Use when...' clause and good trigger terms covering 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, and its broad scope could cause 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 writing or editing skills—e.g., 'Focuses on conciseness and clarity per Elements of Style, not tone or voice adjustments.'

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', and '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 'prose humans will read' could overlap with general writing assistance skills, editing skills, or style guide skills. The niche is somewhat defined but not sharply bounded.	2 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

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: joshuadavidthomas/agent-skills
Commit: d20109a

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.