recipe-design

Execute from codebase analysis to design document creation

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

85%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured, highly actionable orchestration recipe with explicit checkpoints, feedback loops, and concrete subagent handoff contracts. Its main weakness is redundant restatement of the same flow across the overview, scope boundaries, and completion checklist.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean and assumes Claude's competence, but the same flow is restated three times — the Workflow Overview diagram, the Scope Boundaries list, and the Completion Criteria checklist largely restate the Execution Flow steps — so it could be tightened by consolidating that redundancy.	2 / 3
Actionability	Guidance is concrete and copy-paste ready: exact `subagent_type` strings (e.g. 'dev-workflows:codebase-analyzer'), fully specified prompt templates with named JSON fields, and specific tool choices (rg/grep, AskUserQuestion) leave no ambiguity about what to invoke.	3 / 3
Workflow Clarity	The four-step sequence is explicit with validation checkpoints at every `[STOP]` marker, quality gates (code-verifier, document-reviewer, design-sync), and a clear feedback loop where 'Correct the scope and re-run' returns to Step 1 with the corrected seed.	3 / 3
Progressive Disclosure	The skill is self-contained with no bundle files, well-organized into clearly labeled sections, and appropriately defers detail to external skills (subagents-orchestration-guide, the dev-workflows subagents) rather than duplicating their content inline.	3 / 3
	Total	11 / 12 Passed

Description

50%

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 third-person and identifies the design-phase domain, but it is abstract and omits any 'Use when...' trigger guidance, leaving all dimensions at the mid level. It reads more like a phase label than a skill-selection trigger.

Suggestions

Add an explicit 'Use when...' clause naming natural triggers, e.g. 'Use when the user requests a design document or ADR, or asks to design an architectural change for a codebase.'

Replace the abstract 'Execute from ... to ...' framing with concrete actions: analyze the codebase, confirm scope, draft an ADR or Design Doc, verify against code, and review for consistency.

Include common trigger variants users would actually say ('design doc', 'ADR', 'architecture design', 'technical design') to improve distinctiveness and trigger coverage.

Dimension	Reasoning	Score
Specificity	The phrase 'Execute from codebase analysis to design document creation' names the domain (codebase analysis, design documents) and a high-level action, but does not enumerate multiple concrete actions like analyze, draft ADR, verify, or review; it stays at the flow level rather than listing specific capabilities.	2 / 3
Completeness	It states what the skill does (run the design phase from analysis to design document), but the 'when' is entirely missing — there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 2 per the rubric guidelines.	2 / 3
Trigger Term Quality	'codebase analysis' and 'design document' are reasonably natural terms a user might say, but coverage is thin and missing common variations (ADR, design doc, architecture review); no trigger clause is present.	2 / 3
Distinctiveness Conflict Risk	The design-phase framing is somewhat specific, but the description is generic enough to overlap with sibling dev-workflow skills (codebase-analyzer, technical-designer) and does not clearly carve out a non-conflicting trigger niche.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: shinpr/claude-code-workflows
Commit: 66e3b29

Reviewed: 1 day 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.