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?

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

The canonical home for this skill is debugging-and-error-recovery in addyosmani/agent-skills

Quality

Content

77%Scale 1-3

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 debugging skill with excellent workflow clarity and actionability — the six-step triage process with decision trees is well-designed and immediately usable. The main weaknesses are moderate verbosity (some content covers things Claude already knows, like basic error handling patterns and common runtime errors) and a monolithic structure that could benefit from splitting secondary content into referenced files. The security-conscious section on treating error output as untrusted data is a valuable and distinctive addition.

Suggestions

Move error-specific patterns (test/build/runtime triage), safe fallback patterns, and instrumentation guidelines into separate referenced files to keep the main SKILL.md focused on the core debugging workflow.

Trim content Claude already knows — the runtime error triage section (TypeError explanations, CORS basics) and safe fallback code examples are general programming knowledge that don't need to be spelled out.

Dimension	Reasoning	Score
Conciseness	The skill is reasonably well-structured but includes some content Claude already knows (e.g., common error patterns like 'TypeError: Cannot read property x of undefined', basic git bisect usage, safe fallback patterns with try/catch). The 'Common Rationalizations' table and some of the decision trees add value but could be tighter. The safe fallback code examples and instrumentation guidelines feel like general programming advice rather than skill-specific guidance.	2 / 3
Actionability	The skill provides concrete, executable commands (npm test with flags, git bisect), specific code examples (TypeScript regression tests, safe fallback patterns), and detailed decision trees with clear actions at each branch. The triage checklists are immediately actionable with specific steps to follow.	3 / 3
Workflow Clarity	The six-step workflow (Stop → Preserve → Diagnose → Fix → Guard → Resume) is clearly sequenced with explicit validation checkpoints. Step 6 includes a concrete verification checklist, and the 'Stop-the-Line Rule' establishes a clear feedback loop. The decision trees provide branching logic for different scenarios with clear next actions at each node.	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 focused on the core triage workflow.	2 / 3
	Total	10 / 12 Passed

Description

82%Scale 1-3

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 excellent completeness and trigger term coverage. Its main weakness is that the capability description stays at a high level ('guides systematic root-cause debugging') without enumerating specific concrete techniques or actions, and the broad trigger terms could cause overlap with general coding or testing skills.

Suggestions

Add specific concrete actions to improve specificity, e.g., 'Guides systematic root-cause debugging through log analysis, hypothesis testing, bisecting changes, and isolating failing components.'

Narrow the trigger scope slightly to reduce conflict risk, e.g., clarify that this is for when initial fixes haven't worked or when the cause is non-obvious, distinguishing it from simple error-fixing skills.

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 multiple specific concrete actions like 'analyze stack traces, bisect commits, add logging, inspect variable state'. The actions remain somewhat general.	2 / 3
Completeness	Clearly answers both 'what' (guides systematic root-cause debugging) and 'when' (explicit 'Use when' clauses covering test failures, build breaks, unexpected behavior, errors, and needing a systematic approach rather than guessing).	3 / 3
Trigger Term Quality	Includes strong natural trigger terms users would actually say: 'tests fail', 'builds break', 'behavior doesn't match expectations', 'unexpected error', 'root cause', 'debugging', 'finding and fixing'. These cover common variations of how users describe debugging needs.	3 / 3
Distinctiveness Conflict Risk	While 'systematic root-cause debugging' is a reasonably specific niche, the broad triggers like 'unexpected error' and 'behavior doesn't match expectations' could overlap with general coding assistance, error handling, or testing skills. It's somewhat distinguishable but not sharply bounded.	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: finlay611/agent-skills
Path: skills/debugging-and-error-recovery/SKILL.md
Commit: ea12d4d

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