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

79%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/debugging-and-error-recovery/SKILL.md

Quality

Content

77%

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

This is a solid, actionable debugging skill with excellent workflow clarity and concrete guidance. Its main weakness is length — it tries to cover too many scenarios inline (error-specific patterns, safe fallbacks, instrumentation, rationalizations) that could be split into reference files or trimmed. The decision trees and triage checklists are the strongest elements, providing clear, structured paths through debugging scenarios.

Suggestions

Trim or remove the 'Common Rationalizations' table and 'Safe Fallback Patterns' section — these teach debugging philosophy and defensive coding patterns that Claude already knows, and they add ~40 lines without unique actionable value.

Consider splitting error-specific triage patterns (test failures, build failures, runtime errors) into a separate TRIAGE_PATTERNS.md reference file to keep the main skill focused on the core 6-step workflow.

Dimension	Reasoning	Score
Conciseness	The skill is generally well-structured but includes some content Claude already knows (e.g., common error patterns like 'TypeError: Cannot read property x of undefined', basic safe fallback patterns, and the 'Common Rationalizations' table which teaches debugging philosophy rather than actionable steps). The decision trees and triage checklists add value, but the overall document could be tightened by ~30%.	2 / 3
Actionability	The skill provides concrete, executable commands (git bisect, npm test with flags), specific code examples (TypeScript regression test, safe fallback patterns), and clear decision trees with actionable branches. The triage checklists give specific next steps at each decision point rather than vague guidance.	3 / 3
Workflow Clarity	The 6-step triage checklist is clearly sequenced with explicit validation checkpoints (Step 6: Verify End-to-End includes running tests, building, and manual verification). The Stop-the-Line Rule establishes a clear feedback loop (diagnose → fix → guard → verify → resume). The verification checklist at the end serves as a final gate.	3 / 3
Progressive Disclosure	The content is well-organized with clear headers and logical sections, but it's a long monolithic document (~250 lines) with no references to external files. The error-specific patterns, safe fallback patterns, and instrumentation guidelines could be split into separate reference files to keep the main skill lean. However, there are no bundle files, so this is evaluated as a standalone document that could benefit from splitting.	2 / 3
	Total	10 / 12 Passed

Description

82%

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 is a solid description with strong completeness and good trigger terms that cover common debugging scenarios users would describe. Its main weaknesses are the lack of specific concrete debugging actions (what methodology or steps does it guide?) and some potential overlap with general development or error-handling skills. Adding more specific capabilities would strengthen both specificity and distinctiveness.

Suggestions

Add specific concrete actions the skill performs, e.g., 'Guides systematic root-cause debugging through log analysis, hypothesis formation, bisection, and minimal reproduction steps.'

Differentiate from general coding skills by specifying what makes this approach distinct, e.g., 'Applies a structured methodology rather than ad-hoc fixes' or mention specific techniques used.

Dimension	Reasoning	Score
Specificity	The description names the domain (debugging) and some actions ('root-cause debugging', 'finding and fixing the root cause'), but doesn't list specific concrete actions like 'analyze stack traces, bisect commits, add logging, inspect variable state'. The actions remain somewhat abstract.	2 / 3
Completeness	Clearly answers both what ('Guides systematic root-cause debugging') and when ('Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error'). Has explicit 'Use when...' clauses with multiple trigger scenarios.	3 / 3
Trigger Term Quality	Good coverage of natural trigger terms users would say: 'tests fail', 'builds break', 'behavior doesn't match expectations', 'unexpected error', 'debugging', 'root cause', 'finding and fixing'. These are phrases users naturally use when encountering bugs.	3 / 3
Distinctiveness Conflict Risk	While 'systematic root-cause debugging' is a reasonably specific niche, it could overlap with general coding/development skills or error-handling skills. The triggers like 'unexpected error' and 'behavior doesn't match expectations' are broad enough to potentially conflict with other development-oriented skills.	2 / 3
	Total	10 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Commit: 5e262b2

Reviewed: 2 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.