recipe-design

Execute from codebase-scoped analysis through optional ADR decisions to complete Design Doc approval

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/recipe-design/SKILL.md

Quality

Content

81%Weight 40%Scale 1-5

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, actionable orchestration recipe with clear sequencing and validation feedback loops. Its main weakness is progressive disclosure: the referenced review-resolution.md file is not actually bundled.

Suggestions

Ship the missing references/review-resolution.md file (or remove the broken reference) so the one-level-deep reference resolves.

Trim repeated emphasis phrases ('unchanged', '[Stop] ... received explicit user confirmation') that restate the same constraint multiple times.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's knowledge (it never explains what an ADR or Design Doc is), with only minor repetition of the 'unchanged' and '[Stop]' emphases that could be trimmed.	4 / 5
Actionability	It specifies exact field names and routing verdicts (approved/needs_revision/rejected) and concrete stop points, but defers real detail to referenced skills, leaving minor gaps.	4 / 5
Workflow Clarity	Steps 1-7 are clearly sequenced with explicit validation checkpoints ([Stop] confirmations), feedback loops (rerun code-verifier after correction, rerun Steps 6-7), and a Completion Criteria checklist.	5 / 5
Progressive Disclosure	Content is well organized into clearly headed sections and signals referenced skills, but the one explicit file reference (references/review-resolution.md) points to a file that does not exist in the bundle.	4 / 5
	Total	17 / 20 Passed

Description

46%Weight 40%Scale 1-5

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 distinct design-orchestration niche but stays at a high level, naming phases rather than concrete actions and omitting any user-facing "Use when" trigger. Adding a trigger clause and grounding the actions would lift specificity and completeness.

Suggestions

Append an explicit 'Use when ...' clause naming the natural situations a user would invoke this (e.g., approving a design for Medium/Large work, deciding whether ADRs are needed).

Replace abstract phase labels with a few concrete operations the skill performs (e.g., 'Routes requirement convergence, qualifies ADR decision points, and drives Design Doc verification and approval').

Add common synonyms or trigger terms a user might actually say (e.g., 'design doc', 'ADR', 'technical design approval').

Dimension	Reasoning	Score
Specificity	Names the domain ("codebase-scoped analysis", "optional ADR decisions", "complete Design Doc approval") and a couple of phases, but the actions are abstract phase labels rather than concrete operations, so it falls short of listing several specific actions.	3 / 5
Completeness	It conveys a rough "what" (orchestrate analysis through ADR to Design Doc approval) but has no "Use when..." or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric.	3 / 5
Trigger Term Quality	The terms present ("codebase-scoped analysis", "ADR decisions", "Design Doc approval") are technical jargon rather than natural phrases a user would say, and there are no common synonyms or user-facing trigger words.	2 / 5
Distinctiveness Conflict Risk	The design-phase vocabulary (ADR, Design Doc, codebase-analyzer) gives it a clear niche with minimal overlap against unrelated skills, though it could overlap with sibling design/dev-workflow skills.	4 / 5
	Total	12 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: shinpr/claude-code-workflows
Path: skills/recipe-design/SKILL.md
Commit: 83cf695

Reviewed: about 22 hours ago

Table of Contents

Discovery Implementation Validation

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.