CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

73%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 genuinely useful, well-sequenced debugging workflow with strong validation checkpoints and concrete commands. Its weaknesses are token efficiency — it re-explains basic knowledge (generic fallback patterns, what common runtime errors mean) — and a single-file structure that inlines a couple of sections that could be split out.

Suggestions

Trim the Safe Fallback Patterns section to a one-line principle or move it to a reference file — the default-config and empty-state TypeScript examples restate patterns Claude already knows.

Condense the Runtime Error Triage tree: entries like "TypeError: Cannot read property 'x' of undefined → something is null/undefined" explain basic knowledge; keep only the non-obvious diagnostic next steps.

Move the three Error-Specific Patterns triage trees (test/build/runtime) into a single one-level-deep reference file (e.g., references/triage-patterns.md) and keep short pointers in SKILL.md to reduce the main file's token footprint.

DimensionReasoningScore

Conciseness

The body is mostly efficient — decision trees and checklists carry real operational weight — but several sections explain knowledge Claude already has: the runtime-error tree spells out that a TypeError means an undefined value, and the Safe Fallback Patterns section shows generic default-config/empty-state TypeScript that is standard knowledge. It could be tightened without losing value, matching anchor 3 rather than the leaner anchor 4.

3 / 5

Actionability

Most guidance is executable: specific commands ("npm test -- --grep", "git bisect run ..."), a copy-paste regression test example, and concrete branch-by-branch actions in the triage trees. Minor gaps remain — some directives are abstract ("Ask: 'Why does this happen?' until you reach the actual cause") and commands are npm-specific with a substitution note — so it does not reach fully copy-paste-ready anchor 5.

4 / 5

Workflow Clarity

The six-step triage checklist is clearly ordered with an explicit "Do not skip steps" instruction, YES/NO branch decision trees, feedback loops for non-reproducible bugs (retry under load, isolate, compare environments), an explicit verification step ("RESUME only after verification passes"), and a final checklist. This matches the anchor for clear sequence with explicit validation, error-recovery loops, and checklists.

5 / 5

Progressive Disclosure

The skill is a single file with no bundle, and its 11 sections are clearly headed and easy to navigate, with no nested references. However, at ~295 lines, content such as the Error-Specific Patterns triage trees and Safe Fallback code examples could arguably live in one-level-deep reference files, and the cross-reference to "the test-driven-development skill's Discover the Stack First section" is a dangling pointer outside the bundle — minor organization gaps consistent with anchor 4.

4 / 5

Total

16

/

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 capability and trigger conditions with natural, user-sounding phrases. Its main gaps are moderate action specificity and a few missing common trigger synonyms (bug, crash, exception, stack trace), plus one overly broad catch-all trigger clause.

DimensionReasoningScore

Specificity

The description names the domain ("systematic root-cause debugging") and 1-2 concrete actions ("finding and fixing the root cause"), matching the anchor for naming the domain with a couple of concrete actions. It does not list several distinct specific actions (as in "Extract text, fill forms, merge documents"), so it falls short of anchor 4.

3 / 5

Completeness

It clearly answers both what ("Guides systematic root-cause debugging... finding and fixing the root cause") and when, with two explicit "Use when..." clauses containing concrete trigger phrases. Not below 5 because both questions are answered explicitly with concrete triggers, not merely implied.

5 / 5

Trigger Term Quality

It includes natural phrases users would actually say — "tests fail", "builds break", "something that worked yesterday broke", "unexpected error" — giving good keyword coverage. Common variations like "bug", "crash", "exception", or "stack trace" are missing, so it does not reach comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

The failure-triggered framing (broken tests/builds/regressions) carves a mostly distinct niche with minor overlap risk against closely related skills (e.g., testing or code-review skills). The very broad clause "or you encounter any unexpected error" slightly raises conflict risk, keeping it below anchor 5.

4 / 5

Total

16

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

addyosmani/agent-skills

Path

skills/debugging-and-error-recovery/SKILL.md

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.