Skip to content
Get packs

Systematic Debugging and Error Recovery

Guides an agent through structured root-cause debugging instead of guessing at fixes.

Source Download skill
Repository
addyosmani/agent-skills
Stars
112,668
Licence
MIT
Files
1 file

What it does

When something breaks, such as failing tests, a broken build, or unexpected behavior, the agent follows a fixed sequence: stop making new changes, preserve the error output, reproduce the failure, narrow down which layer is at fault, reduce it to a minimal case, fix the underlying cause, add a test that would catch the bug again, and verify the whole project before continuing. It includes decision trees for flaky, environment-dependent, and state-dependent bugs, plus common triage paths for build, test, and runtime errors.

Great for

  • Developers who want an agent to find the root cause of a bug rather than patch symptoms
  • Teams debugging regressions where something worked before a recent change
  • Anyone whose agent tends to guess-and-retry when a test or build fails

Skip it if

  • Simple, obvious fixes where a full six-step process adds overhead without benefit
  • Production incidents needing immediate mitigation, since the skill prioritises diagnosis over rapid rollback (it does not cover incident response)
  • Projects that do not use the test or build commands the skill assumes; the agent must substitute the repository's own commands

Try asking

  • “The tests in this repo started failing after my last change. Help me find the root cause.”
  • “My build broke after upgrading a dependency. Work through the triage checklist.”
  • “Users report duplicate entries in the list but I can't tell why. Debug it systematically.”
  • “Something that worked yesterday is now throwing a TypeError. Figure out what changed.”
Step-by-step guide: how to use Systematic Debugging and Error RecoveryInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    debugging-and-error-recovery.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip debugging-and-error-recovery.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip debugging-and-error-recovery.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point the agent at the exact error output or logs so it can follow the preserve-evidence step.
  • Tell the agent your project's test and build commands if they are not npm, since the examples assume npm.
  • Ask the agent to explain the root cause before applying the fix, so you can check its reasoning.

What's inside

  • SKILL.md

Redistributed unmodified from addyosmani/agent-skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.