docs-writer

Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. Use when creating docs, reviewing markdown files, writing READMEs, updating `/docs` directories, or when user says "write documentation", "review this doc", "improve this README", "create a guide", or "edit markdown". Do NOT use for code comments, inline JSDoc, or API reference generation.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

87%

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

The content is a lean, well-structured editorial workflow with concrete pointers and good progressive disclosure via a verified reference file. Its main weakness is that the verification feedback loop is present but not made explicit, leaving workflow clarity just short of the top anchor.

Suggestions

In Step 4, add an explicit validate->fix->retry loop, e.g. 'If links are broken or formatting is off, fix them and re-verify before finishing.'

Spell out the verification condition that gates completion (e.g. 'Only proceed to offer npm run format once all links resolve and content matches the code') so the checkpoint is unambiguous.

Make the link-verification step actionable by naming how to check links (e.g. grep for the link target or open the referenced path) rather than only stating 'verify the validity'.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-organized, assumes Claude's competence, and avoids explaining concepts Claude already knows; every step earns its place without padding or PDF-explainer-style background.	3 / 3
Actionability	Concrete guidance throughout: named paths (packages/, docs/, docs/sidebar.json), a real reference file (references/style-guide.md), named tools (replace, write_file), and a copy-ready command (npm run format). For an instruction-only skill this is specific and actionable.	3 / 3
Workflow Clarity	A clear four-step sequence with a dedicated verification step (re-read files, link verification) exists, but the error-recovery feedback loop (validate -> fix -> re-verify) is only implicit rather than explicitly stated, capping it below the top anchor.	2 / 3
Progressive Disclosure	SKILL.md is a concise overview that signals a single one-level-deep reference (references/style-guide.md, verified to exist) plus project files; content is appropriately split and easy to navigate, satisfying the simple-skill note.	3 / 3
	Total	11 / 12 Passed

Description

100%

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 across all dimensions: it states concrete capabilities, provides abundant natural trigger phrases, and answers both what and when with explicit exclusions. It is concise yet comprehensive with no fluff.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Write, review, and edit documentation files" — with explicit quality dimensions ("consistent structure, tone, and technical accuracy"), matching the anchor for listing multiple specific concrete actions.	3 / 3
Completeness	Clearly answers both what (write/review/edit documentation) and when (explicit "Use when..." clause with multiple triggers), and adds a "Do NOT use for..." exclusion, satisfying the top anchor for explicit triggers.	3 / 3
Trigger Term Quality	Excellent natural-language coverage with phrases users actually say ("write documentation", "review this doc", "improve this README", "create a guide", "edit markdown") plus variations like reviewing markdown files and writing READMEs.	3 / 3
Distinctiveness Conflict Risk	The documentation niche is distinct and the explicit exclusion ("Do NOT use for code comments, inline JSDoc, or API reference generation") sharply reduces conflict with code-oriented skills.	3 / 3
	Total	12 / 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: tech-leads-club/agent-skills
Commit: ec2d639

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