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 both concrete action details and explicit trigger guidance. While it identifies a domain (Design Doc compliance/security), it fails to specify what standards are checked, what auto-fixes are performed, or when Claude should select this skill. Adding a 'Use when...' clause and more specific capability details would significantly improve its effectiveness.
Suggestions
Add an explicit 'Use when...' clause with trigger terms like 'design document review', 'security audit', 'compliance check', 'design doc validation'.
List specific concrete actions such as 'validates security requirements, checks compliance against [specific standards], identifies missing sections, auto-fixes formatting issues'.
Include natural keyword variations users might say, such as 'design document', 'design review', 'security review', 'policy compliance', and relevant file types or frameworks.
| 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, what compliance standards are checked, or what auto-fixes are applied. | 2 / 3 |
Completeness | Describes a rough 'what' (compliance and security validation with auto-fixes) but completely lacks a 'when' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is also weak, warranting 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', 'policy check', or file format references. | 2 / 3 |
Distinctiveness Conflict Risk | 'Design Doc' provides some specificity, but 'compliance and security validation' is broad enough to overlap with general security review or compliance-checking skills. The lack of detail about what kind of design docs or what compliance frameworks makes it somewhat ambiguous. | 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 strong actionability and workflow clarity—each step has concrete invocation parameters, clear decision criteria, and explicit validation/re-validation loops. The main weaknesses are moderate verbosity (some sections could be tightened) and the monolithic structure that could benefit from splitting detailed content into referenced files. The dual code-side/design-side fix path is a sophisticated and well-documented workflow pattern.
Suggestions
Consider extracting the subagent prompt templates and the route decision table into a separate reference file (e.g., SUBAGENT-PROMPTS.md) to reduce the main skill's length and improve progressive disclosure.
Remove the 'Orchestrator Definition' section—Claude doesn't need to be told 'I am an orchestrator' as a core identity statement; the execution flow already makes the role clear.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly detailed and well-structured for a complex orchestration workflow, but includes some unnecessary verbosity—e.g., the 'Orchestrator Definition' section stating 'I am an orchestrator' and explaining what an orchestrator does, the scope boundary boilerplate, and some repetitive phrasing. The decision table and route explanations are useful but could be tighter. | 2 / 3 |
Actionability | Each step provides concrete, executable guidance: specific bash commands, exact subagent invocation parameters (subagent_type, description, prompt), structured output templates, and clear decision criteria with thresholds (70%, 90%). The finding-to-route decision table and the user-facing report format are copy-paste ready. | 3 / 3 |
Workflow Clarity | The 11-step workflow is clearly sequenced with explicit validation checkpoints (Steps 9-10 re-validate after fixes), feedback loops (Step 5d re-evaluates c-routed findings after DD updates, dropping satisfied ones), conditional branching (blocked → stop, skip paths for s/d-only routes), and a cleanup step. The security blocked check at Step 4 is an important early-exit validation. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headers, but it's a monolithic document with no references to external files for detailed guidance (e.g., subagent configuration, report schema details, or the documentation-criteria skill referenced in Step 5). For a skill of this complexity (~180 lines), splitting detailed subagent prompt templates or the route decision logic into separate reference files would improve navigability. | 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
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.