debugging-and-error-recovery

Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need to figure out what broke and why — a systematic approach to finding and fixing the root cause rather than guessing.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

88%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 body delivers a disciplined, fully actionable debugging workflow: ordered triage steps, executable commands and code, feedback loops, and a verification checklist. Its weaknesses are mild — a few spots over-explain well-known errors, and the length could be reduced by moving error-specific patterns and instrumentation guidance into reference files.

Suggestions

Trim explanations of errors Claude already understands (e.g. the meaning of 'Cannot read property of undefined' or what a CORS error is) in the Runtime Error Triage tree — keep the decision branches, drop the glosses.

Move the Error-Specific Patterns and Instrumentation Guidelines sections into a one-level-deep reference file (e.g. references/triage-patterns.md) referenced from the main checklist, slimming SKILL.md to the core workflow.

Tighten the Safe Fallback Patterns section to one compact example instead of two multi-line TypeScript functions, since the pattern (safe default + graceful degradation) is the transferable idea.

Dimension	Reasoning	Score
Conciseness	The body is largely lean — decision trees, terse checklists, and justified code — but contains minor over-explanation of concepts Claude already knows, e.g. the Runtime Error Triage tree glossing "TypeError: Cannot read property 'x' of undefined" with "Something is null/undefined that shouldn't be". Efficient overall with a few trimmable spots, not the every-token-earns-its-place level.	4 / 5
Actionability	Guidance is fully executable: copy-paste commands ("git bisect run npm test -- --grep 'failing test'", focused-test and isolation invocations), a complete regression-test example, and concrete safe-fallback TypeScript code. Specific examples cover the common cases (test failure, build failure, runtime error, non-reproducible bug), with an explicit note to substitute the repository's own commands.	5 / 5
Workflow Clarity	The six-step triage checklist is strictly ordered ("Work through these steps in order. Do not skip steps."), backed by the Stop-the-Line rule, explicit feedback loops (non-reproducible handling branches; the regression test "should fail without the fix and pass with it"), and a final verification checklist. Clear sequence with explicit validation and checklists throughout.	5 / 5
Progressive Disclosure	A single-file skill with no references/ or scripts/ bundle; sections are clearly headed and nothing is nested or buried. At ~295 lines, the Error-Specific Patterns and Instrumentation Guidelines sections are inline material that could plausibly live in one-level-deep reference files, so structure is good but not the ideal clear-overview-plus-well-signaled-references split.	4 / 5
	Total	18 / 20 Passed

Description

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

A strong description that explicitly covers both what the skill does and when to use it, with natural trigger phrases a user would actually say. The main gap is specificity — it describes the domain and approach without naming the concrete debugging capabilities (reproduce, localize, reduce, fix, guard, verify) — and a few common synonyms (bug, crash, stack trace) are absent.

Dimension	Reasoning	Score
Specificity	"Guides systematic root-cause debugging" and "finding and fixing the root cause" name the domain and 1-2 actions, but the description never enumerates the concrete capabilities the skill actually provides (reproduce, localize, bisect, guard against recurrence). It lists a domain with minimal actions rather than several specific ones.	3 / 5
Completeness	Explicitly answers both questions: the "what" ("Guides systematic root-cause debugging") and the "when" via two explicit "Use when..." clauses with concrete trigger phrases (tests fail, builds break, unexpected error). The "when" is fully explicit with multiple triggers, not merely present.	5 / 5
Trigger Term Quality	Natural user phrasings like "tests fail", "builds break", "something that worked yesterday broke", and "what broke and why" give good coverage, but common synonyms users say — "bug", "crash", "stack trace", "error message", "flaky" — are missing. Solid keyword coverage with a few natural terms absent.	4 / 5
Distinctiveness Conflict Risk	"tests fail, builds break, something that worked yesterday broke" carves a distinct debugging niche with clear triggers, but "you encounter any unexpected error" is broad enough to risk minor overlap with general test/verify/code-review skills. Mostly distinct with minor overlap risk.	4 / 5
	Total	16 / 20 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: addyosmani/agent-skills
Path: skills/debugging-and-error-recovery/SKILL.md
Commit: 2686b62

Reviewed: 3 days 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.