recipe-update-doc

Update existing design documents (Design Doc / PRD / ADR) with review

Quality

81%

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

96%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.

The content is a tightly written orchestrator workflow with concrete subagent invocation blocks, explicit review/approval gates, and robust feedback loops for destructive document updates. Its only gap is that everything is inlined in one file with no local bundle references.

Dimension	Reasoning	Score
Conciseness	The body is dense, purposeful orchestration logic with no concept padding and no over-explanation; every gate, table, and prompt template earns its place, matching the 'lean and efficient' anchor.	5 / 5
Actionability	Provides copy-paste-ready subagent invocation blocks with exact fields, decision tables mapping situations to actions, declared serialization, and verbatim prompt templates covering each document type.	5 / 5
Workflow Clarity	A clear six-step sequence with explicit validation checkpoints (Review Resolution Gate, Final Approval stop), feedback loops (review->revise->re-review with prior_feedback, design-sync conflict->return to Step 4), and a completion checklist.	5 / 5
Progressive Disclosure	Single self-contained file with well-organized sections and clearly signaled one-level-deep references to external skills; scored 4 rather than 5 because no bundle files exist and the inlined prompt templates add bulk that could be factored out.	4 / 5
	Total	19 / 20 Passed

Description

66%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.

The description clearly states what the skill does and names the three target document types, giving it solid specificity and distinctiveness. Its main weakness is the absence of an explicit 'Use when...' trigger clause, which caps completeness.

Suggestions

Add an explicit trigger clause, e.g. 'Use when updating an existing Design Doc, PRD, or ADR that has already been reviewed.'

Include natural synonyms such as 'product requirements document' and 'architecture decision record' alongside PRD/ADR.

Optionally state the distinguishing condition versus sibling skills, e.g. 'for existing documents only — new-doc creation is out of scope.'

Dimension	Reasoning	Score
Specificity	Names the design-doc domain and enumerates three concrete artifact types (Design Doc / PRD / ADR) plus the update-with-review action; falls short of 5 only because it lists two actions rather than multiple distinct ones.	4 / 5
Completeness	Has a clear 'what' (update existing design documents with review) but no explicit 'Use when...' trigger clause; per the judging guideline a missing explicit trigger caps completeness at 3.	3 / 5
Trigger Term Quality	Includes natural terms 'design documents', 'Design Doc', 'PRD', and 'ADR' that users would say; missing common synonyms and expansions like 'product requirements' or 'architecture decision record', so not a 5.	4 / 5
Distinctiveness Conflict Risk	Scoped narrowly to existing design documents of three named types with a review step, giving a distinct niche and low overlap risk; not a 5 because the phrasing lacks explicit triggers that fully separate it from sibling doc skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: shinpr/claude-code-workflows
Path: skills/recipe-update-doc/SKILL.md
Commit: 83cf695

Reviewed: about 23 hours 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.