documentation-criteria

Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored. Use when deciding documentation scope, or when creating or reviewing a technical document.

Quality

86%

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

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-engineered decision-routing skill body: concrete tables and ordered steps make it highly actionable, and detail is properly deferred to one-level-deep template references. The main room for improvement is adding explicit validation/feedback guidance and trimming a few dense explanatory passages.

Suggestions

Add an explicit verification/feedback step to the build path (e.g., 'after selecting documents, confirm none overlap and that each ADR topic passed both filters before proceeding') to push workflow clarity toward 5.

Tighten the 'What Each Document Fixes' paragraphs by moving rationale ('An unfilled section becomes a guess...') into the relevant template, keeping only the routing rule in SKILL.md.

Consider a short worked example row in the Creation Decision Matrix mapping a concrete change to its document path, to make the decision even more copy-pasteable.

Dimension	Reasoning	Score
Conciseness	The prose is dense but earns its tokens — it encodes skill-specific routing logic (AC IDs as traceability keys, ADR durability filters) rather than explaining concepts Claude already knows, with only minor instances that could be tightened; a 5 would be leaner still.	4 / 5
Actionability	Concrete and executable for an instruction skill: explicit decision matrices, a structural-scale table with precise conditions, ordered build steps, and a storage table with copy-pasteable paths and naming conventions like '[feature-name]-prd.md'.	5 / 5
Workflow Clarity	A clear ordered sequence ('Build one path in this order: 1... 2... 3...') with gating checks (apply Choice then Durability filter; check existing ADRs first), but it lacks explicit error-recovery/feedback loops, so it stays at 4 rather than 5.	4 / 5
Progressive Disclosure	SKILL.md holds only routing decisions and points one level deep to six real template files in references/ (all verified present), clearly signaled in both the Storage Locations table and the References section — an appropriately split, easy-to-navigate structure.	5 / 5
	Total	18 / 20 Passed

Description

87%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-targeted description that clearly states both the capability (document routing and storage) and the trigger conditions. It is specific to a distinct niche with concrete natural-language triggers; only marginal gains remain in action coverage and synonym breadth.

Dimension	Reasoning	Score
Specificity	Names several concrete actions — 'Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored' plus 'creating or reviewing a technical document' — with only minor coverage gaps; not quite the exhaustive multi-action list of a 5.	4 / 5
Completeness	Explicitly answers both what ('Determines which ... a change requires, and where each is stored') and when ('Use when deciding documentation scope, or when creating or reviewing a technical document') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural terms a user would say appear — 'documentation scope', 'creating or reviewing a technical document', plus the document-type names (PRD, ADR, Design Doc) — but a few common phrasings/synonyms are missing, so it sits at 4 rather than 5.	4 / 5
Distinctiveness Conflict Risk	It carves a clear niche — documentation routing/decision across a named set of artifact types — with distinct triggers and minimal risk of firing for an unrelated skill.	5 / 5
	Total	18 / 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: shinpr/claude-code-workflows
Path: skills/documentation-criteria/SKILL.md
Commit: 9b7f687

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