recipe-review
Design Doc compliance and security validation with optional auto-fixes
50
55%
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-review/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 is too terse and lacks a 'Use when...' clause, making it difficult for Claude to know when to select this skill. While it names a domain (Design Doc) and hints at capabilities (compliance, security validation, auto-fixes), it doesn't specify concrete actions or provide trigger guidance. The description would benefit significantly from explicit trigger terms and a clearer enumeration of what it validates.
Suggestions
Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks to review, validate, or audit a design document for compliance or security issues.'
List specific concrete actions, e.g., 'Validates design documents against compliance standards, checks for security vulnerabilities, flags missing sections, and optionally applies auto-fixes for common issues.'
Include natural keyword variations users might say, such as 'design document', 'design review', 'security audit', 'compliance check', 'RFC review'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain ('Design Doc') and two actions ('compliance and security validation' and 'auto-fixes'), but lacks concrete specifics about what validation entails or what auto-fixes are applied. | 2 / 3 |
Completeness | Provides a partial 'what' (compliance and security validation with auto-fixes) but completely lacks a 'when' clause or explicit trigger guidance, which per the rubric caps completeness at 2, and the 'what' itself is also weak enough to warrant a 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant terms like 'Design Doc', 'compliance', 'security validation', and 'auto-fixes', but misses common user variations such as 'design document', 'security review', 'audit', 'lint', or 'check'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'Design Doc' with 'compliance and security validation' is somewhat specific, but 'compliance' and 'security validation' are broad terms that could overlap with other security or compliance-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
77%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 excellent actionability and workflow clarity — the 11-step process is clearly sequenced with validation checkpoints, conditional branching, and user interaction points. The main weaknesses are moderate verbosity (some sections explain context Claude doesn't need) and the monolithic structure that could benefit from splitting detailed templates and reference material into supporting files.
Suggestions
Extract the report templates, auto-fixable/non-fixable item lists, and design-side update triggers into separate reference files to improve progressive disclosure and reduce the main skill's length.
Remove the 'Orchestrator Definition' section and the 'Context' line — Claude doesn't need to be told 'I am an orchestrator' or that this is 'post-implementation quality assurance' to execute the workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly detailed and well-structured for a complex orchestration workflow, but includes some unnecessary verbosity such as the 'Orchestrator Definition' section ('I am an orchestrator'), explanations of when design-side vs code-side paths apply that Claude could infer, and the scope boundary boilerplate. Some sections could be tightened. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific bash commands, exact subagent invocation parameters (subagent_type, description, prompt), structured output templates, decision tables for routing findings, and clear variable passing between steps ($STEP_2_OUTPUT, etc.). The instructions are copy-paste ready for orchestration. | 3 / 3 |
Workflow Clarity | The 11-step workflow is clearly sequenced with explicit validation checkpoints (Steps 9-10 re-validate after fixes), a blocked-security early exit (Step 4), conditional branching (Step 5d for design-side path), feedback loops (fix → re-validate), and user confirmation gates via AskUserQuestion. The decision table for routing findings and the conditional skip logic are well-defined. | 3 / 3 |
Progressive Disclosure | The content is a long monolithic document with no references to supporting files despite the complexity warranting them (e.g., the report template, auto-fixable items list, and subagent prompt templates could be separate files). However, the internal organization with clear step headers and sections is reasonable. No bundle files are provided to offload content to. | 2 / 3 |
Total | 10 / 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.