recipe-update-doc
Update existing design documents (Design Doc / PRD / ADR) with review
45
47%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/recipe-update-doc/SKILL.mdQuality
Discovery
32%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 identifies a reasonable niche (updating existing design documents) and includes some useful acronyms as trigger terms, but it lacks concrete detail about what the update/review process involves. The absence of an explicit 'Use when...' clause significantly weakens its ability to guide skill selection, and the actions described are too vague to fully distinguish this skill from related document-editing skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to revise, update, or incorporate feedback into an existing Design Doc, PRD, or ADR.'
Expand the acronyms at least once (e.g., 'Product Requirements Document (PRD)', 'Architecture Decision Record (ADR)') to improve trigger term coverage for users who use the full names.
Describe specific actions more concretely, e.g., 'Incorporates review feedback, updates sections, tracks changes, and ensures consistency in existing design documents.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (design documents) and a specific action (update with review), and lists document types (Design Doc, PRD, ADR), but doesn't describe what 'update' or 'review' concretely entails (e.g., adding sections, incorporating feedback, tracking changes). | 2 / 3 |
Completeness | Describes what it does (update existing design documents with review) but has no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric should cap completeness at 2, and the 'what' itself is also quite thin, bringing it to 1. | 1 / 3 |
Trigger Term Quality | Includes useful trigger terms like 'Design Doc', 'PRD', 'ADR', and 'review', which users might naturally say. However, it misses common variations like 'product requirements document', 'architecture decision record', 'revise', 'edit', or 'modify'. | 2 / 3 |
Distinctiveness Conflict Risk | Specifying 'existing' documents and 'update' helps distinguish it from a skill that creates new design documents, and the document types (PRD, ADR) add some specificity. However, it could still overlap with general document editing or creation skills without clearer boundaries. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured orchestration skill with strong workflow clarity—clear sequencing, explicit stop points, revision loops with caps, and comprehensive error handling. Its main weaknesses are moderate verbosity (some redundancy between the overview and execution flow) and the fact that actionability is limited to orchestration templates rather than concrete executable examples. The lack of bundle files makes it impossible to verify the referenced sub-agents and skills exist.
Suggestions
Consolidate the 'Workflow Overview' diagram and 'Execution Flow' sections to reduce redundancy—the diagram could be removed since the steps are clearly laid out below.
Trim the 'Orchestrator Definition' section, which restates generic orchestration patterns that could be assumed from the referenced subagents-orchestration-guide skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably structured but includes some redundancy—the workflow overview diagram partially duplicates the execution flow, and some explanations (like the orchestrator definition) could be tighter. The tables and decision flows are efficient, but the overall document could be trimmed by ~20%. | 2 / 3 |
Actionability | The skill provides structured sub-agent invocation templates with specific prompts and clear decision tables, which is good. However, the guidance is largely procedural/orchestration-level rather than executable code—the sub-agent prompts are templates with placeholders, and the actual update logic is delegated entirely to other agents without concrete examples of what the updates look like. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced with explicit [Stop] markers at each quality gate, a well-defined revision loop with a max iteration cap (2 rejections → human review), clear error handling table, and a completion checklist. The feedback loop for review rejection is explicitly defined with retry limits. | 3 / 3 |
Progressive Disclosure | The skill references multiple sub-agents (technical-designer, document-reviewer, code-verifier, design-sync, prd-creator) and a 'subagents-orchestration-guide' skill but no bundle files are provided to verify these exist. The content is reasonably organized with sections, but all content is inline in a single file with no references to supporting documentation for the sub-agents or their capabilities. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- shinpr/claude-code-workflows
- Commit
adf2e4d
- 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.