debugging-and-error-recovery

Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/debugging-and-error-recovery/SKILL.md

Quality

Content

70%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 strong, actionable debugging workflow with explicit validation checkpoints and concrete commands. It is held back by some basic-concept padding and a monolithic inline structure that lacks progressive disclosure via reference files.

Suggestions

Trim or remove the "Safe Fallback Patterns" section and basic explanations (e.g., what a TypeError means) since they restate knowledge Claude already has.

Move the detailed non-reproducible-bug decision tree and error-specific triage patterns into separate reference files (e.g., references/non-reproducible.md) with one-level-deep links from SKILL.md to improve progressive_disclosure.

Tighten the "Common Rationalizations" table to the two or three highest-value rows to reduce token cost.

Dimension	Reasoning	Score
Conciseness	Mostly efficient decision trees and checklists, but it re-explains basics Claude knows (e.g., "TypeError: Cannot read property 'x' of undefined → Something is null/undefined") and the tangential "Safe Fallback Patterns" defensive-coding section adds padding that could be trimmed.	3 / 5
Actionability	Provides executable commands (npm test, git bisect) and concrete code (regression test, getConfig/renderChart), with clear decision trees; minor gaps such as environment-specific substitutions keep it just below fully copy-paste-ready across all stacks.	4 / 5
Workflow Clarity	A clearly sequenced 6-step triage process ("Do not skip steps") with explicit validation in Step 6 (Verify End-to-End) and a final Verification checklist, including feedback loops; debugging is not a destructive/batch operation so no cap applies.	5 / 5
Progressive Disclosure	Well-organized sections, but ~300 lines of content is entirely inline with no bundle files or references; detailed inline material (e.g., the non-reproducible-bug decision tree, error-specific patterns) could be split into one-level-deep reference files.	3 / 5
	Total	15 / 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.

The description cleanly answers both what and when with concrete, natural trigger phrases and a distinct debugging niche. It is slightly light on enumerating multiple specific concrete actions, keeping specificity at the midpoint.

Dimension	Reasoning	Score
Specificity	Names the domain ("systematic root-cause debugging") and one concrete action pair ("finding and fixing the root cause"), but does not enumerate several specific actions like the score-5 anchor, so it sits at the domain-plus-1-2-actions level.	3 / 5
Completeness	Explicitly states what ("Guides systematic root-cause debugging") and an explicit, concrete "Use when..." trigger list with multiple conditions, satisfying both halves with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users say ("tests fail", "builds break", "behavior doesn't match expectations", "any unexpected error"), giving good coverage, though some common terms ("bug", "crash", "stack trace") are absent.	4 / 5
Distinctiveness Conflict Risk	"systematic root-cause debugging" with test/build-failure triggers carves a clear niche with minimal conflict risk, though it lightly overlaps the related test-driven-development skill it references.	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: df1edb2

Reviewed: about 19 hours 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.