recipe-diagnose

Investigate problem, verify findings, and derive solutions

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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

The body is highly actionable and workflow-clear, with concrete sub-agent prompts, explicit JSON contracts, validation checkpoints, and feedback loops. Its main weaknesses are mild verbosity in framing prose and a lack of progressive disclosure, since all detail lives inline in a long monolithic file with no reference files.

Suggestions

Tighten motivational framing (e.g., the 'I am not a worker' identity line) into a single concise directive to improve token efficiency.

Move the final report template and detailed JSON field schemas into a reference file (e.g., references/report-format.md) and link to it from the main flow to enable progressive disclosure.

Consider extracting the per-step prompt templates into references/ so SKILL.md reads as a concise overview pointing to detailed prompts.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean, using tables, JSON contracts, and checklists rather than concept explanations, but includes some motivational framing ('I am not a worker. I am an orchestrator.') and bracketed placeholder prose that could be tightened.	2 / 3
Actionability	It provides concrete Agent-tool invocations with subagent_type, description, and full prompt templates, plus exact JSON field contracts (pathMap, failurePoints, causeCategory enum) and enumerated quality-check checkboxes that are copy-paste ready.	3 / 3
Workflow Clarity	The flow has an explicit sequence with validation checkpoints (Step 2 quality check, Step 3 verifier coverage criteria), feedback loops (re-investigate on insufficient coverage, max 2 iterations, design_gap escalation), and a completion criteria checklist.	3 / 3
Progressive Disclosure	There are no bundle files and no references; the ~236-line body is a well-sectioned monolith with the report template and JSON schemas all inline, so content that could be split out is not, and the under-50-line exception does not apply.	2 / 3
	Total	10 / 12 Passed

Description

27%

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 uses correct third-person voice and names several actions, but it is generic, lacks natural trigger terms, omits any 'Use when' guidance, and would conflict with many other skills. It needs a concrete domain (e.g., diagnosis/root-cause analysis) and an explicit trigger clause.

Suggestions

Add a concrete domain and specific actions, e.g. 'Diagnose root causes of problems by investigating symptoms, verifying failure points, and deriving solutions.'

Include a 'Use when...' trigger clause naming natural terms users say, e.g. 'Use when the user asks to diagnose, debug, find the root cause of, or troubleshoot a problem.'

Sharpen distinctiveness by tying triggers to diagnosis-specific phrasing (root cause, failure point) rather than generic investigation verbs.

Dimension	Reasoning	Score
Specificity	Lists three concrete verbs ('Investigate problem, verify findings, and derive solutions') but they are generic actions with no concrete domain anchor, so it names some actions without being comprehensive or domain-specific.	2 / 3
Completeness	It states what the skill does (investigate/verify/derive) but provides no 'Use when...' trigger clause, so the 'when' is entirely missing; the rubric caps completeness at 2 for a missing explicit trigger.	2 / 3
Trigger Term Quality	The terms are overly generic verbs ('investigate', 'verify', 'derive solutions'); a user would not naturally say these when they need this skill, and natural diagnosis keywords like 'diagnose', 'debug', 'root cause', or 'troubleshoot' are absent.	1 / 3
Distinctiveness Conflict Risk	'Investigate problem, verify findings, and derive solutions' is very generic and would overlap with debugging, code-review, and analysis skills, making it likely to trigger for the wrong skill.	1 / 3
	Total	6 / 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.