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.
66
79%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/debugging-and-error-recovery/SKILL.mdQuality
Discovery
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 excellent trigger coverage and clear 'what/when' structure. Its main weakness is that the capability description stays at a high level ('guides systematic root-cause debugging') without enumerating specific debugging techniques or actions, and the broad trigger terms could cause overlap with other coding/testing skills.
Suggestions
Add specific concrete actions to increase specificity, e.g., 'Guides systematic root-cause debugging through log analysis, hypothesis testing, bisecting changes, and isolating variables.'
Consider narrowing or clarifying the boundary with general coding help skills by specifying what distinguishes this from simple error-fixing, e.g., 'Use this instead of quick fixes when the root cause is unclear or multiple attempts have failed.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (debugging) and some actions ('systematic root-cause debugging', 'finding and fixing the root cause'), but doesn't list multiple concrete specific 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' (explicit 'Use when' clauses covering test failures, build breaks, unexpected behavior, errors, and needing a systematic approach vs 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'. These cover common variations of how users describe debugging scenarios. | 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. The emphasis on 'systematic approach' helps differentiate but the scope is still quite wide. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
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 through its structured triage checklist and decision trees. Its main weakness is length — it tries to cover too many scenarios inline (error-specific patterns, safe fallbacks, instrumentation guidelines, common rationalizations) that could be split out or trimmed. The security note about treating error output as untrusted data is a valuable and unique addition.
Suggestions
Trim the 'Common Rationalizations' table and 'Safe Fallback Patterns' section — these teach debugging philosophy and defensive coding patterns Claude already knows, rather than project-specific actionable guidance.
Consider extracting error-specific triage patterns (test failures, build failures, runtime errors) into a separate reference file to keep the main SKILL.md focused on the core 6-step workflow.
| 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 safe fallback patterns, and the 'Common Rationalizations' table which teaches debugging philosophy rather than actionable steps). The decision trees and triage checklists earn their place, but the 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 at Step 6 (run specific test, full suite, build, manual check). The Stop-the-Line rule establishes a clear feedback loop (diagnose → fix → guard → verify before resuming). The decision trees provide branching logic for error recovery at each step. | 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 leaner. However, with no bundle files provided, this is somewhat expected. | 2 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- addyosmani/agent-skills
- Commit
f17c6e8
- 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.