CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is documentation-criteria in shinpr/claude-code-workflows

SKILL.md
Quality
Evals
Security

Quality

Content

71%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 routing skill: decision criteria are concrete and sequenced, and detail is properly pushed into six real, one-level-deep template references. The main weakness is token efficiency — several rules are stated twice and the prose is denser than the content requires — and a worked example would strengthen actionability.

Suggestions

State the ADR floor rule ('A qualifying ADR decision point sets the floor to Medium') and the Medium-vs-Large boundary once, in the Structural Scale section, instead of repeating them in Creation Decision Matrix and after the scale table.

Tighten the long multi-clause sentences in 'What Each Document Fixes' (e.g., the PRD paragraph's precondition aside) to short criterion statements; the routing rule survives without the rationale padding.

Add a short worked example walking one sample change through Structural Scale, the ADR filters, and the resulting document set, to make the decision path fully executable.

DimensionReasoningScore

Conciseness

The body avoids generic concept explanations, but it is redundant and could be tightened: 'A qualifying ADR decision point sets the floor to Medium' is stated in both the Creation Decision Matrix and Structural Scale sections, the Medium/Large boundary is restated after the table, and long multi-clause sentences (e.g., the PRD paragraph) pad the routing rules. Fits 'mostly efficient but could be tightened' rather than the minor-trim level of 4.

3 / 5

Actionability

Concrete, executable decision machinery: a Creation Decision Matrix with scales and base documents, a numbered build order, Structural Scale conditions, a two-part ADR filter with an explicit qualifying-choices list and exclusions, and a storage table with paths and naming conventions. As an instruction-only skill the guidance is actionable; the gap keeping it from 5 is the absence of a worked example classifying a sample change through the rules.

4 / 5

Workflow Clarity

The sequence is explicit ('Build one path in this order: 1. Select the base path from Structural Scale. 2. Insert an applicable UI Spec immediately before the Design Doc. 3. ...insert an ADR batch') with checkpoints such as 'check existing ADRs first' and 'Continue after PRD approval'. This is a decision skill, not a destructive or batch operation, so no validation cap applies; it stays at 4 because there is no final step verifying the resulting document set before proceeding.

4 / 5

Progressive Disclosure

The body is a true overview that explicitly delegates per-document content to templates ('What to write inside one is defined by its template'), and all six referenced files (prd/adr/ui-spec/design/plan/task templates) exist in references/ exactly as linked, one level deep. References are well signaled in the Storage Locations table and the References section, matching the clear-overview anchor.

5 / 5

Total

16

/

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 description: it states a concrete routing capability over five named document types, gives storage guidance, and includes an explicit 'Use when' clause with natural trigger phrases. Minor room to add synonymous phrasing users might use, but conflict risk and completeness are excellent.

DimensionReasoningScore

Specificity

Enumerates all five document types ('PRD, ADR, UI Spec, Design Doc, and Work Plan') and two concrete actions (determines which a change requires, where each is stored), matching the 'several specific actions; minor gaps' anchor. Not 5 because the action set is narrow — routing and storage — without touching authoring or review depth.

4 / 5

Completeness

Explicitly answers 'what' ('Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored') and 'when' with a concrete 'Use when' clause covering both deciding scope and creating/reviewing a document. This matches the anchor-5 example structure; it is above 4 because the trigger guidance is already explicit and specific.

5 / 5

Trigger Term Quality

Names the exact artifacts users mention ('PRD, ADR, UI Spec, Design Doc, Work Plan') plus natural phrases like 'deciding documentation scope' and 'creating or reviewing a technical document'. A few common variations (e.g., 'requirements doc', 'spec', 'write an ADR') are missing, so it fits anchor 4 rather than the comprehensive-synonym coverage of 5.

4 / 5

Distinctiveness Conflict Risk

The five named document types form a clear niche with distinct triggers, so it is unlikely to fire for unrelated skills. Only trivial overlap with a generic technical-writing skill exists, fitting the 'clear niche with distinct triggers' anchor.

5 / 5

Total

18

/

20

Passed

Validation

100%

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

dev-workflows-frontend/skills/documentation-criteria/SKILL.md

Reviewed

Table of Contents

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.