technical-writing-clarity

Use this skill when writing documentation, READMEs, technical specs, runbooks, or any text that explains a system or process to other engineers. Apply before writing any developer-facing document.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

85%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 body is concise, well-organized, and provides a clear sequenced structure with verification and troubleshooting. Its only weak spot is actionability: the principles are stated abstractly without a brief worked example to make them immediately executable.

Suggestions

Add one short before/after example pair (e.g. a wall-of-text paragraph vs. a one-idea-per-paragraph rewrite) to lift actionability from abstract principles to concrete guidance.

Optionally show the recommended runbook structure applied to a single tiny worked example so the 1-5 sequence is demonstrated, not just listed.

Dimension	Reasoning	Score
Conciseness	The body is lean (~17 lines) with no padding and no explanation of concepts Claude already knows; every principle and line earns its place, matching the 'lean and efficient' anchor.	3 / 3
Actionability	Guidance is mostly concrete for an instruction-only skill (a worked contrast 'Run the script' not 'The script should be run', a numbered 1-5 structure, and named anti-patterns), but the principles themselves remain somewhat abstract ('Lead with the purpose', 'Concrete over abstract') without a short before/after example illustrating them, so it does not fully reach copy-paste-ready concreteness.	2 / 3
Workflow Clarity	The runbook/how-to structure is a clear numbered 1-5 sequence that includes a verification/expected-output step (4) and troubleshooting (5); as a simple skill with no destructive or batch operations, no validation checkpoint is required.	3 / 3
Progressive Disclosure	Under 50 lines with no external references needed and clearly organized into three labeled sections (Principles, Structure, Anti-patterns), which satisfies the simple-skill allowance for a top score.	3 / 3
	Total	11 / 12 Passed

Description

82%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 is strong: it has an explicit 'Use when' trigger, good natural keyword coverage, and answers both what and when. It loses points on specificity (genre list rather than distinct concrete actions, plus second-person voice) and is somewhat broad on distinctiveness.

Suggestions

Rephrase in third person and use concrete verbs, e.g. 'Drafts and structures developer-facing documentation, READMEs, technical specs, and runbooks. Apply before writing any document that explains a system or process to engineers.'

Add a couple of distinct concrete actions (e.g. 'outlines', 'edits for clarity', 'applies a runbook structure') to lift specificity toward a 3.

Dimension	Reasoning	Score
Specificity	Lists several concrete output types ('documentation, READMEs, technical specs, runbooks'), which is more than a single domain, but these are genres rather than distinct concrete actions like 'extract', 'fill', 'merge'; it does not reach the comprehensive multi-action level of a 3. Second-person imperative voice ('Use this skill', 'Apply before') also triggers the specificity penalty, capping it at 2.	2 / 3
Completeness	It answers both 'what' (writing developer-facing explanatory documents) and 'when' with an explicit trigger clause: 'Use this skill when writing...' plus 'Apply before writing any developer-facing document.'	3 / 3
Trigger Term Quality	Natural terms a user would actually say are well covered: 'documentation, READMEs, technical specs, runbooks, developer-facing document'. These match common user phrasings for this need.	3 / 3
Distinctiveness Conflict Risk	The engineer-facing technical-writing niche is somewhat specific, but 'documentation' and 'writing' are broad enough to overlap with general writing or doc-format skills, so it is not yet a clearly distinct, conflict-free niche.	2 / 3
	Total	10 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aiming-lab/MetaClaw
Path: memory_data/skills/technical-writing-clarity/SKILL.md
Commit: 922caf3

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