recipe-update-doc
Update existing design documents (Design Doc / PRD / ADR) with review
56
47%
Does it follow best practices?
Impact
Pending
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 specific types of design documents—but is too terse and lacks explicit trigger guidance. It doesn't explain what 'update with review' means concretely, and the absence of a 'Use when...' clause makes it difficult for Claude to reliably select this skill over similar document-related skills.
Suggestions
Add a 'Use when...' clause specifying triggers, e.g., 'Use when the user wants to revise, update, or incorporate feedback into an existing Design Doc, PRD, or ADR.'
Expand the specific actions described, e.g., 'Incorporates review feedback, updates sections, resolves comments, and tracks changes in existing design documents.'
Include natural keyword variations such as 'product requirements document', 'architecture decision record', 'revise', 'edit design doc', to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (design documents) and a single action (update with review), and lists specific document types (Design Doc, PRD, ADR), but doesn't describe what 'update with review' concretely entails—e.g., incorporating feedback, revising sections, tracking changes. | 2 / 3 |
Completeness | It partially answers 'what' (update design documents with review) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also weak, so this scores a 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 such as 'product requirements document', 'architecture decision record', 'revise', 'edit', or 'update document'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of specific document types (Design Doc, PRD, ADR) and the 'update' action provides some distinctiveness, but it could overlap with skills for creating these documents or general document editing skills. The lack of explicit trigger boundaries increases conflict risk. | 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—explicit stop points, revision loops with caps, and clear error handling. Its main weaknesses are moderate verbosity (some redundancy between the overview and execution flow) and actionability that relies heavily on external sub-agent definitions without providing fully self-contained executable examples. Progressive disclosure is adequate but could benefit from clearer linking to referenced skills.
Suggestions
Consolidate the workflow overview diagram and execution flow to reduce redundancy—consider removing the ASCII diagram since the steps already convey the sequence clearly.
Add direct file path links to referenced skills (e.g., subagents-orchestration-guide) rather than just naming them, so navigation is one-click.
Make sub-agent invocation templates more concrete by showing the exact tool call syntax expected (e.g., actual Agent tool parameters) rather than pseudo-YAML prompts.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably structured but includes some redundancy—the workflow overview diagram partially duplicates the execution flow, and some tables restate information that could be more compact. The orchestrator definition section repeats concepts from a referenced guide. | 2 / 3 |
Actionability | The skill provides concrete sub-agent invocation templates and decision tables, which is good. However, the prompts are pseudo-templates rather than fully executable commands, and the actual mechanics of 'Agent tool' invocation and TaskCreate registration are left to external references without concrete examples here. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced with explicit [Stop] markers as validation checkpoints, a revision loop with a max iteration cap (2 rejections → human review), error handling table, and clear decision flows at each step. The feedback loop for review rejection is well-defined. | 3 / 3 |
Progressive Disclosure | The skill references external skills (subagents-orchestration-guide, recipe-design, recipe-plan, recipe-task) and sub-agents appropriately, but all content is inline in a single file that runs fairly long. The layer detection logic and ADR guidance could potentially be split out, and references to external skills lack direct links. | 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
2e719be
- 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.