recipe-design
Execute from requirement analysis to design document creation
36
32%
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-design/SKILL.mdQuality
Discovery
14%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is too vague and incomplete to effectively guide skill selection. It lacks specific concrete actions, has no 'Use when...' clause, and is not distinctive enough to avoid conflicts with other documentation or planning-related skills. The description reads more like a phase label than a functional skill description.
Suggestions
Add a 'Use when...' clause with explicit trigger terms, e.g., 'Use when the user asks for requirements analysis, creating design documents, writing technical specifications, or converting requirements into architecture docs.'
List specific concrete actions the skill performs, e.g., 'Gathers and structures functional requirements, creates system design documents, generates UML diagrams, produces API specifications, and writes technical architecture docs.'
Include common user-facing keywords and file types, e.g., 'requirements doc, design spec, technical specification, architecture document, .docx, PRD, SRS'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'requirement analysis' and 'design document creation' without specifying concrete actions. It doesn't list what specific tasks are performed during these phases. | 1 / 3 |
Completeness | The description weakly addresses 'what' (execute from requirement analysis to design document creation) but completely lacks a 'when' clause or any explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'requirement analysis' and 'design document' that users might mention, but misses common variations such as 'spec', 'requirements gathering', 'technical design', 'architecture document', or file formats. | 2 / 3 |
Distinctiveness Conflict Risk | Very generic phrasing that could overlap with many skills related to documentation, project planning, software engineering, or requirements management. There are no distinct triggers to differentiate it. | 1 / 3 |
Total | 5 / 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 skill provides a reasonable orchestration framework for a design phase workflow with clear sequencing and scope boundaries. However, it lacks concrete execution examples (how to actually invoke sub-agents), explicit error recovery loops at quality gates, and the referenced supporting materials are absent. The content would benefit significantly from executable call examples and explicit feedback loops when validation fails.
Suggestions
Add concrete sub-agent invocation examples showing exact call syntax, input parameters, and expected output format — don't just reference 'Call Examples' in another file
Add explicit error recovery paths at each quality gate (e.g., 'If document-reviewer finds issues: fix in technical-designer → re-run code-verifier → re-submit to document-reviewer')
Include or bundle the referenced 'subagents-orchestration-guide' content, or at minimum inline the critical call patterns needed for codebase-analyzer and code-verifier
Provide a concrete example of the dialogue phase showing sample user responses and how they map to requirement-analyzer inputs
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is moderately efficient but includes some redundancy — the critical note about not skipping steps, the repeated references to 'subagents-orchestration-guide skill', and the dialogue questions could be tightened. Some sections like 'Scope Boundaries' restate what's already clear from the workflow. | 2 / 3 |
Actionability | The skill provides a clear sequence of sub-agent invocations and a checklist, but lacks concrete examples of how to invoke each sub-agent (no actual commands, code, or call syntax). It references 'Follow subagents-orchestration-guide Call Examples' without showing any, and the dialogue questions are generic rather than providing specific prompts or templates. | 2 / 3 |
Workflow Clarity | The workflow diagram and completion criteria provide a clear sequence with two explicit stop points. However, validation/feedback loops are only implicitly handled ('addressed feedback' in the checklist) — there's no explicit error recovery path if document-reviewer or design-sync finds issues, and the 'fix and re-validate' pattern is missing for what are essentially quality gates. | 2 / 3 |
Progressive Disclosure | The skill references external resources (subagents-orchestration-guide skill, various sub-agents) but no bundle files are provided to support these references. The content itself is reasonably structured with sections, but the heavy reliance on an external 'subagents-orchestration-guide skill' without clear navigation or links makes it harder to follow independently. | 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
68ecb4a
- 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.