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

68%

Does it follow best practices?

Impact

96%

1.01x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./writing-clearly-and-concisely/SKILL.md

Quality

Content

72%Weight 40%Scale 1-3

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

The skill body is concise, actionable, and well-structured with a clear default reference, but it scores lower on workflow clarity (no validation loop in the subagent revision process) and progressive disclosure (the referenced section files are not present in the bundle).

Suggestions

Add a validation checkpoint to the Limited Context Strategy (e.g., 'Verify the returned revision applies the bolded rules before adopting it') to close the feedback-loop gap.

Ship the referenced bundle files (02-elementary-rules-of-usage.md, 03-elementary-principles-of-composition.md, 04-a-few-matters-of-form.md, 05-words-and-expressions-commonly-misused.md, signs-of-ai-writing.md) so the progressive-disclosure navigation resolves to real content.

Clarify the path convention for the references (the table uses bare filenames while the Bottom Line references an 'elements-of-style/' directory) so navigation is unambiguous.

Dimension	Reasoning	Score
Conciseness	The body is lean: rules are telegraphed as compact one-liners ('Omit needless words', 'Use active voice'), AI-pattern offenders are listed as terse bullets, and it assumes Claude knows what Strunk's rules mean rather than restating them.	3 / 3
Actionability	For an instruction-only skill, guidance is concrete and specific: bolded priority rules (e.g., 'Use active voice', 'Put statements in positive form'), a named anti-pattern vocabulary list, and a pointed default ('Most tasks need only 03-elementary-principles-of-composition.md') giving copy-paste-ready direction.	3 / 3
Workflow Clarity	The 'Limited Context Strategy' gives a clear 3-step sequence (draft → dispatch subagent with section file → return revision), but there is no validation/checkpoint step confirming the returned revision actually meets the rules before adopting it, which is a feedback-loop gap.	2 / 3
Progressive Disclosure	The body references files like '03-elementary-principles-of-composition.md' and 'elements-of-style/', but no references/, scripts/, or assets/ directories exist in the bundle, so the referenced paths cannot be resolved — the navigation points at missing material.	1 / 3
	Total	9 / 12 Passed

Description

65%Weight 40%Scale 1-3

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 has an explicit 'Use when' trigger clause and good natural keywords, but uses second-person voice and stays at a domain level rather than naming concrete actions, limiting specificity and distinctiveness.

Suggestions

Rewrite in third person (e.g., 'Applies Strunk's rules to prose humans will read') to avoid the second-person voice penalty.

Add concrete named actions (e.g., 'Drafts, copyedits, and tightens documentation, commit messages, error messages, and UI copy') to lift specificity from domain-level to concrete-actions.

Narrow the trigger list to more distinctive terms (e.g., 'when the user asks to tighten, shorten, or copyedit prose') to reduce overlap with general writing skills.

Dimension	Reasoning	Score
Specificity	Second-person voice ('Use when writing prose humans will read') is penalized by one level per the judging guidelines; the underlying actions (write/edit prose for humans) are domain-level rather than concrete named actions, so specificity falls from 2 to 1.	1 / 3
Completeness	Explicitly answers what (applies Strunk's rules for clearer writing) and when ('Use when writing prose humans will read' followed by enumerated triggers), satisfying both the what and when with an explicit trigger clause.	3 / 3
Trigger Term Quality	Strong natural terms users would say ('documentation', 'commit messages', 'error messages', 'UI text'), but missing common variations like 'README', 'comments', 'release notes', so coverage is good but not exhaustive — between 2 and 3.	2.5 / 3
Distinctiveness Conflict Risk	The prose-writing niche is distinct, but the trigger set ('explanations, reports, or UI text') overlaps broadly with general writing assistance skills, so it could still conflict with similar skills rather than having a sharply distinct trigger.	2 / 3
	Total	8.5 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: joshuadavidthomas/agent-skills
Path: writing-clearly-and-concisely/SKILL.md
Commit: d5d3760

Reviewed: 7 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.