docs-that-work

Project documentation guidelines. Use when asked to "write documentation", "create a CLAUDE.md", "write a README", "document this project", "improve documentation", "add a Design Intent section", or when creating/updating CLAUDE.md or README.md files.

1.74x

Quality

86%

Does it follow best practices?

Impact

75%

1.74x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

86%Weight 40%Scale 1-5

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

A well-structured, actionable instruction-only skill that keeps the overview lean and pushes depth into real one-level-deep reference files. The only notable gaps are a duplicated Design Intent format block between the body and its reference, and the absence of an explicit feedback loop in the authoring workflow.

Suggestions

Replace the inlined Design Intent markdown block with a brief summary plus a pointer to references/design-intent.md to remove the duplication and tighten the body.

Add an explicit validate/confirm checkpoint to the Design Intent authoring flow (e.g. 'human confirms → section lands; otherwise mark unconfirmed') framed as a numbered sequence to push workflow clarity to the top anchor.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence (e.g. tight budgets like '~35 lines; Design Intent usually ~10 lines, 15 max; ≤70 combined ceiling'), but the full Design Intent markdown format block is duplicated here and in references/design-intent.md, a minor trim opportunity that keeps it just below the leanest anchor.	4 / 5
Actionability	Despite being instruction-only, guidance is concrete and copy-paste ready: a full Design Intent template, do/don't rules with named files, a Document Separation table, and specific line budgets — fully actionable with no pseudocode.	5 / 5
Workflow Clarity	Sequencing is clear (Discoverability Rule → CLAUDE.md → Design Intent → README) and the authoring protocol plus the 'never rewrite/delete a confirmed section without a human' guardrail act as checkpoints for the destructive case, but there is no explicit validate→fix→retry loop, so it stops just short of the top anchor.	4 / 5
Progressive Disclosure	A clear overview with one-level-deep, well-signaled references — 'See references/anti-patterns.md', 'See references/claude-md-guide.md', 'See references/design-intent.md' — and a closing Deep Dives table; all three referenced files exist in references/, matching the top anchor.	5 / 5
	Total	18 / 20 Passed

Description

86%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-triggered description with explicit 'Use when' guidance and natural quoted phrases including file extensions. The only weakness is that the 'what' half ('Project documentation guidelines') is generic and leans on the trigger list for concreteness.

Suggestions

Promote the concrete doc types into the capability clause, e.g. 'Write and maintain CLAUDE.md, README.md, and Design Intent sections' so the 'what' is as specific as the 'when'.

Dimension	Reasoning	Score
Specificity	The phrase 'Project documentation guidelines' names the domain but the 'what' is minimal and generic; the concrete doc types (CLAUDE.md, README, Design Intent) appear only in the trigger list rather than as stated capabilities, so it sits at the 'names domain and 1-2 concrete actions' anchor rather than the comprehensive level above.	3 / 5
Completeness	It explicitly answers both 'what' (Project documentation guidelines) and 'when' with a concrete 'Use when...' clause enumerating specific trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Natural user phrases are quoted directly — 'write documentation', 'create a CLAUDE.md', 'write a README', 'document this project', 'improve documentation', 'add a Design Intent section' — alongside file extensions (CLAUDE.md, README.md), giving comprehensive synonym and extension coverage.	5 / 5
Distinctiveness Conflict Risk	The CLAUDE.md/README/Design Intent triggers carve a fairly distinct niche, but 'Project documentation guidelines' as a category is broad enough to risk minor overlap with other doc-oriented skills, placing it just below the minimal-conflict anchor.	4 / 5
	Total	17 / 20 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: provectus/awos-recruitment
Path: registry/skills/docs-that-work/SKILL.md
Commit: 556fe34

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