recipe-diagnose
Investigate problem, verify findings, and derive solutions
35
31%
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-diagnose/SKILL.mdQuality
Discovery
0%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is critically weak across all dimensions. It reads as a generic problem-solving statement that could apply to any skill, providing no concrete actions, no domain specificity, and no trigger guidance. It would be nearly impossible for Claude to correctly select this skill from a pool of alternatives.
Suggestions
Specify the domain and concrete actions — e.g., 'Debug Python code by analyzing stack traces, reproducing errors, and applying fixes' instead of generic 'investigate problem'.
Add an explicit 'Use when...' clause with natural trigger terms — e.g., 'Use when the user reports a bug, error, or unexpected behavior in their application.'
Include distinguishing keywords that separate this skill from other problem-solving skills — e.g., mention specific file types, tools, frameworks, or problem categories.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses entirely vague, abstract language — 'investigate problem', 'verify findings', 'derive solutions' are generic actions that could apply to virtually any domain. No concrete actions or specific capabilities are listed. | 1 / 3 |
Completeness | The description weakly addresses 'what' with vague verbs and completely omits 'when' — there is no 'Use when...' clause or any explicit trigger guidance. | 1 / 3 |
Trigger Term Quality | The terms 'problem', 'findings', and 'solutions' are overly generic and not natural keywords a user would use to trigger a specific skill. There are no domain-specific or actionable trigger terms. | 1 / 3 |
Distinctiveness Conflict Risk | This description is extremely generic and would conflict with nearly any problem-solving, debugging, analysis, or troubleshooting skill. There is nothing to distinguish it from other skills. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill defines a well-structured diagnostic orchestration workflow with clear sequencing, validation checkpoints, and iteration limits—its strongest aspect. However, it relies heavily on abstract sub-agent tool invocations without concrete executable examples, reducing actionability. The content is moderately concise but could be tightened by removing redundancy and the self-referential orchestrator identity framing.
Suggestions
Add a concrete JSON schema example for at least one sub-agent's expected output (e.g., the investigator's pathMap/failurePoints structure) to make the expected data formats unambiguous and actionable.
Provide a concrete, minimal end-to-end example showing actual JSON passed between investigator → verifier → solver to demonstrate the workflow in practice.
Remove or minimize the 'Orchestrator Definition' preamble—Claude doesn't need to be told its identity philosophy; focus on what to do rather than what to be.
Consider splitting the detailed quality check criteria (Step 2) and report template (Step 5) into separate referenced files to improve progressive disclosure and reduce the main file's length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some redundancy—the structured JSON field expectations are repeated across steps, and the orchestrator identity preamble ('I am not a worker. I am an orchestrator.') adds little value. Some sections like the problem type table and the step-by-step agent invocation templates are useful, but the overall document could be tightened by ~20-30%. | 2 / 3 |
Actionability | The skill provides structured prompts and expected output schemas, which is helpful, but relies on abstract sub-agent invocations (investigator, verifier, solver, rule-advisor) and tools (TaskCreate, TaskUpdate, AskUserQuestion, Agent tool) without concrete executable code or commands. The agent invocation blocks are pseudo-templates rather than copy-paste-ready implementations, and the expected outputs are described as field names without actual JSON schemas or examples. | 2 / 3 |
Workflow Clarity | The multi-step workflow is clearly sequenced (Steps 0-5) with explicit validation checkpoints: Step 2 has a detailed quality checklist, Step 3 has coverage criteria (sufficient/partial/insufficient), there's a feedback loop (max 2 iterations back to Step 1), design_gap escalation with user confirmation, and clear completion criteria. The flow diagram and iteration limits are well-defined. | 3 / 3 |
Progressive Disclosure | The content is entirely self-contained in a single file with no references to supporting documents, which is acceptable given no bundle files exist. However, the document is quite long (~200+ lines) and could benefit from splitting the detailed sub-agent prompt templates, quality check criteria, and report format into separate reference files. The internal structure with headers is reasonable but the monolithic nature works against discoverability. | 2 / 3 |
Total | 9 / 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.