CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

recipe-diagnose

Investigate problem, verify findings, and derive solutions

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./dev-workflows-frontend/skills/recipe-diagnose/SKILL.md

The canonical home for this skill is recipe-diagnose in shinpr/claude-code-workflows

SKILL.md
Quality
Evals
Security

Quality

Content

73%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.

The content is a well-engineered orchestration workflow: clearly sequenced steps, explicit validation checkpoints, concrete agent invocation templates, and defined feedback loops. Its main weaknesses are verbose, redundant prose in the scope-envelope and coverage-convergence sections and a single-file layout that inlines report templates that could be split out.

Suggestions

Tighten Step 0 and Step 4: replace multi-clause sentences like the envelope-inclusion rule with short bullet criteria, and consolidate the overlapping guidance now spread across the Execution Gate, Step 4, and Completion Criteria.

Move the two full report templates (Step 7) into a referenced file (e.g. reports.md) and keep only the field requirements inline, shortening the main body.

Give the two prerequisite skill references concrete paths or locations so the instruction is executable without guessing where llm-friendly-context and subagents-orchestration-guide live.

DimensionReasoningScore

Conciseness

The body is mostly efficient procedural instruction with no explanations of concepts Claude already knows, but Step 0 and Step 4 contain dense, hard-to-parse sentences (e.g. "newly discovered areas are inside the envelope only when they have one of the relationships above and evidence shows they can change the supported cause set, coverage judgment, or counter-evidence") and the Execution Gate, Step 4, and Completion Criteria partially repeat each other. This fits anchor 3 (mostly efficient, could be tightened) rather than anchor 4's minor-trims-only level.

3 / 5

Actionability

Concrete, copy-ready Agent invocation blocks specify exact subagent_type, description, and prompt field templates; expected-output schemas name specific JSON fields; and two full report templates are provided. Minor gaps keep it at anchor 4: the prerequisite skills ("llm-friendly-context", "subagents-orchestration-guide") are referenced by bare name without paths, and the investigator/verifier/solver subagent types are assumed to exist.

4 / 5

Workflow Clarity

Steps 0-7 are strictly ordered behind an explicit Execution Gate, with a Step 2 validation checklist, verifier coverage criteria, coverageDisposition branching, and a defined feedback loop (verifier names gaps → re-run investigator on gaps → re-verify), plus a final completion checklist. This matches anchor 5's explicit validation, error-recovery loops, and checklists; the only minor fuzz is "design decision gate when applicable" in the overview diagram, which Step 5 substantiates.

5 / 5

Progressive Disclosure

The single file is well organized with clear step headers, code blocks, and templates, and no bundle files exist to reference. It stays at anchor 4 rather than 5 because the ~225-line body inlines two full report templates that could live in reference files, and the two cross-skill references are bare names with no paths or signaling of where their content lives.

4 / 5

Total

16

/

20

Passed

Description

33%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 is terse and grammatically clean but generic: it names abstract actions with no domain, no trigger guidance, and no natural keywords a user would say. It reads closer to "Processes data" than to a distinctive, discoverable skill description.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. "Use when the user reports a bug, unexpected behavior, or asks for root cause analysis or a diagnosis."

Name the domain and concrete artifacts, e.g. "Diagnose software problems by investigating code paths, verifying failure points, and deriving fixes" instead of fully abstract objects like "problem" and "findings".

Include natural trigger terms and synonyms users actually say (debug, troubleshoot, root cause, diagnose, why does X happen) to improve discovery and reduce conflict with other problem-solving skills.

DimensionReasoningScore

Specificity

The description lists three verbs ("Investigate problem", "verify findings", "derive solutions") but every object is abstract and no domain is named, placing it at anchor 2's generic-action level rather than anchor 3, which requires a concrete domain alongside the actions. It is above anchor 1 because distinct actions are named rather than one wholly vague claim.

2 / 5

Completeness

A rough "what" is present ("Investigate problem, verify findings, and derive solutions") but there is no "Use when..." clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 4 because the "when" is entirely absent rather than merely implicit or imprecise.

3 / 5

Trigger Term Quality

No natural user phrases such as "debug", "root cause", "diagnose", or "fix bug" appear; only generic words like "problem" and "solutions" are present, matching anchor 2 (one or two generic keywords, natural phrases missing). It avoids anchor 1 only because "investigate" and "verify" are domain-relevant verbs rather than pure technical jargon.

2 / 5

Distinctiveness Conflict Risk

"Investigate problem ... derive solutions" could describe almost any problem-solving, debugging, or planning skill, creating high overlap risk (anchor 2). It is not 1 because the investigate→verify→solve sequence sketches a diagnosis-specific niche, and not 3 because no domain term distinguishes it from adjacent skills.

2 / 5

Total

9

/

20

Passed

Validation

100%

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

Path

dev-workflows-frontend/skills/recipe-diagnose/SKILL.md

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.