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

89%

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

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 routing skill: concrete decision matrices, operationalizable filters, and exact storage conventions make the guidance directly executable, while per-document detail is properly pushed into verified one-level-deep template references. The only weaknesses are mild — some convoluted prose and restated rules that could be tightened, and no final verification step in the decision workflow.

DimensionReasoningScore

Conciseness

Every section carries repository-specific decision rules with no generic padding (it defines each document's role rather than explaining what a PRD is). Minor trimming is possible — the Structural Scale conditions are restated below the table and several sentences are convoluted ('a precondition held outside the repository change ... appears in it only when the user's wording raises it') — which keeps it below the lean 5 anchor but well above anchor 3.

4 / 5

Actionability

Fully executable guidance for an instruction-only skill: exact paths and naming patterns ('docs/adr/', 'ADR-[4-digits]-[title].md', 'YYYYMMDD-{type}-{description}.md'), an ordered build procedure ('1. Select the base path ... 2. Insert an applicable UI Spec ... 3. ... ADR batch'), and two operationalizable ADR filters with concrete qualifying and non-qualifying examples.

5 / 5

Workflow Clarity

The creation sequence is clearly ordered with an explicit gate ('Continue after PRD approval') and a defined filter application order ('Apply the Choice filter, then the Durability filter'). It stops short of the 5 anchor because there is no verification checkpoint for confirming the selected document set before proceeding.

4 / 5

Progressive Disclosure

The body holds only the routing decision ('What to write inside one is defined by its template') and delegates per-document content to six clearly signaled, one-level-deep references, all of which exist in references/. This matches the clear-overview anchor with easy navigation.

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 description: it states a precise routing capability over five named artifacts, gives exact storage responsibility, and includes an explicit 'Use when' clause with natural trigger phrases. Third-person, concise, and clearly distinguishable from related skills.

DimensionReasoningScore

Specificity

Enumerates all five concrete artifacts ('PRD, ADR, UI Spec, Design Doc, and Work Plan') and two specific actions ('Determines which ... a change requires, and where each is stored'), matching the several-specific-actions anchor with only minor coverage gaps (just two verbs versus the multi-action 5 anchor).

4 / 5

Completeness

Explicitly answers both what ('Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan 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, matching the 5 anchor.

5 / 5

Trigger Term Quality

Good natural keywords: the five document-type names users would actually say plus 'deciding documentation scope' and 'creating or reviewing a technical document'. A few natural synonyms are missing (e.g., 'spec', 'requirements doc'), keeping it below the comprehensive 5 anchor.

4 / 5

Distinctiveness Conflict Risk

Clear niche — documentation routing across five named document types — with distinct triggers and minimal overlap risk with generic writing or document skills. Uses third person ('Determines'), so no voice penalty applies.

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-skills/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.