recipe-plan
Create work plan from design document and obtain plan approval
52
41%
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-plan/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 conveys a basic idea of the skill's purpose—creating a work plan from a design document and getting approval—but it is too terse and lacks explicit trigger guidance. It would benefit from listing concrete actions, specifying the types of design documents or plan formats involved, and adding a clear 'Use when...' clause to help Claude distinguish this skill from other planning-related skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user provides a design document, technical spec, or architecture doc and asks for a work plan, task breakdown, or implementation plan.'
List more specific concrete actions, such as 'Parses design documents to extract requirements, generates a phased work plan with tasks and milestones, and submits the plan for stakeholder approval.'
Include natural trigger term variations like 'implementation plan', 'task breakdown', 'project plan', 'spec', 'technical design doc', 'sign-off' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names a domain (work planning from design documents) and two actions (create work plan, obtain plan approval), but lacks detail on what these actions concretely entail—e.g., how the plan is structured, what approval means, or what outputs are produced. | 2 / 3 |
Completeness | Describes what the skill does (create work plan, obtain approval) but provides no explicit 'Use when...' clause or 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 fairly thin, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'work plan', 'design document', and 'plan approval' that users might naturally say, but misses common variations such as 'implementation plan', 'project plan', 'spec', 'technical design', 'task breakdown', or 'sign-off'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'design document' and 'work plan' provides some specificity, but 'work plan' and 'plan approval' are broad enough to potentially overlap with generic project management or planning skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a moderately well-structured orchestration skill that clearly defines a three-step planning workflow with appropriate delegation to sub-agents. Its main weaknesses are the lack of error handling/validation feedback loops (e.g., what if plan approval is rejected?), some redundancy between sections, and incomplete standalone actionability due to heavy reliance on external skill references without clear links.
Suggestions
Add explicit error recovery steps: what to do if no design documents exist (beyond 'notify user'), if the acceptance-test-generator fails, or if the work plan is rejected during approval.
Consolidate references to external skills into a single 'Related Skills' or 'Dependencies' section with clear file path links rather than scattering them throughout the document.
Remove the 'Scope Boundaries' section or merge it into the execution process, as it largely duplicates information already conveyed by the steps and completion response.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill has some redundancy—repeating references to 'subagents-orchestration-guide skill' multiple times and restating scope boundaries that overlap with the execution process. The 'Orchestrator Definition' section explains concepts that could be more tightly integrated, but overall it's not excessively verbose. | 2 / 3 |
Actionability | The skill provides concrete steps and specific sub-agent invocation parameters (subagent_type, prompt templates), which is helpful. However, key details are incomplete—the ls command is shown but the actual Agent tool invocation syntax is only partially specified, and several steps defer to external skills without providing enough standalone guidance to be fully executable. | 2 / 3 |
Workflow Clarity | The three-step process is clearly sequenced and includes a user confirmation checkpoint at Step 2 and an approval gate at Step 3. However, there are no explicit validation or error recovery steps—what happens if design documents don't exist is mentioned but not handled with a feedback loop, and there's no guidance on what to do if the work-planner sub-agent fails or the plan is rejected. | 2 / 3 |
Progressive Disclosure | The skill references external skills (subagents-orchestration-guide, acceptance-test-generator, work-planner) but doesn't provide clear navigational links to them. The content is reasonably structured with sections, but the scope boundaries section largely duplicates information found in the execution process, and references to external skills are scattered rather than consolidated. | 2 / 3 |
Total | 8 / 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.