Guide · Agent skill
How to use the Debugging and Error Recovery agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The debugging-and-error-recovery skill is a set of instructions that tells an AI coding agent how to investigate a broken test, build, or unexpected behavior in a structured way. Instead of making guesses and retrying, the agent follows a fixed sequence that ends with a root-cause fix and a test that catches the bug again. This guide covers what the skill does, how to install it, how to trigger it, and what it needs to run.
Systematic Debugging and Error Recoveryaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it. Confirm the package contains SKILL.md.
- 2Place the skill folder. Move the unzipped skill folder to ~/.claude/skills/ for personal use, or to .claude/skills/ inside a project for project-only use.
- 3Or upload it in the Claude apps. If you use the Claude apps, go to Settings → Capabilities → Skills and upload the skill there.
- 4Check your project commands. Make sure the project has working test and build commands, and that Git is available for bisection.
- 5Describe the failure. Give the agent the failing test name, build error, or unexpected behavior in plain words, with the error output if you have it.
- 6Review the process. Check that the agent reproduces the failure and finds the cause before it edits code, then confirm it added a regression test.
- 7Verify before moving on. Ask the agent to run the focused test, the full test suite, and the build before you continue with other work.
What the skill makes the agent do
When something breaks, the skill tells the agent to stop making new changes, keep the error output, and work through a triage checklist. The checklist has six steps: reproduce, localize, reduce, fix the root cause, guard against recurrence, and verify end-to-end. The agent should not move on to the next feature until verification passes.
The skill also includes decision trees for non-reproducible bugs, covering timing-dependent, environment-dependent, and state-dependent problems. It adds triage paths for test failures, build errors, and runtime errors.
- Reproduce the failure reliably before trying to fix it
- Narrow down which layer is failing: UI, API, database, build tooling, external service, or the test itself
- Use git bisect to find the commit that introduced a regression
- Fix the underlying cause rather than the symptom
- Write a test that fails without the fix and passes with it
How to install the debugging-and-error-recovery skill
Download the ZIP file from this page. The skill is a single file named SKILL.md inside the package. Unzip it so that the skill folder ends up in one of these locations.
For a personal install that applies across your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need a special command. The skill is meant to be picked up when the request matches its description, which covers failing tests, broken builds, behavior that stopped working, and unexpected errors. Describe the problem in plain words and include the error text if you have it.
If the agent starts guessing and retrying, you can name the skill directly in your request and ask it to follow the triage process.
- "The test suite failed after my last change. Find the root cause before changing anything."
- "The build broke this morning. Use the debugging-and-error-recovery skill to find out what changed."
- "This worked yesterday and now the search returns nothing. Figure out why."
- "I'm getting TypeError: Cannot read property 'x' of undefined. Track down where the value comes from."
Example: finding a regression with bisection
When a bug appeared after a recent change, the skill asks the agent to use git bisect. Git checks out commits between a known-good and a known-bad point, and the test is run at each one until the commit that introduced the bug is found. The agent substitutes your repository's own focused test command where the example shows npm.
The commands below are the ones the skill uses for this step.
git bisect start\ngit bisect bad\ngit bisect good <known-good-sha>\ngit bisect run npm test -- --grep "failing test"Example: fixing the root cause, not the symptom
The skill gives a concrete pattern for this. If the user list shows duplicate entries, deduplicating in the UI hides the problem. The better fix is to find the query that produces the duplicates and correct it. The skill tells the agent to keep asking why until it reaches the actual cause.
After the fix, the skill asks for a regression test. The example it uses checks that a search still finds tasks whose titles contain special characters.
- Symptom fix (avoid): deduplicate in the component
- Root-cause fix (prefer): correct the JOIN or the data model, then add a test for it
What the skill needs to run
The skill requires Git, because the bisection step depends on it. It also requires the project's own test and build commands. The examples are written for npm, so if your project uses another tool, the agent must substitute your repository's commands. The skill is not suited to projects that do not have test or build commands.
The skill does not run scripts and does not use the network, according to the listing. It is a set of instructions for the agent.
- Git installed and the project under version control
- The project's own test and build commands
- Runs scripts: no
- Uses network: no
What people use it for
- Tracking down why a test that passed last week now fails after a dependency or code change
- Finding which commit introduced a regression using git bisect
- Diagnosing a TypeError by following where the undefined value comes from
- Working through a build failure by checking types, imports, config, and dependencies in order
- Turning an intermittent bug into a documented set of conditions with logging added at the suspected location
Frequently asked questions
How do I install the debugging-and-error-recovery skill?
Download the ZIP from this page and unzip it. Put the skill folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Is the debugging-and-error-recovery skill free to use?
The skill is released under the MIT licence, as stated on this page. The MIT licence permits use, and this page does not list any price for the skill.
What does the skill require to work?
It requires Git, because the bisection step uses it, and the project's own test and build commands. The examples use npm, so the agent should substitute your repository's commands if you use something else.
Does the skill run scripts or use the internet?
According to this listing, the skill does not run scripts and does not use the network. It consists of instructions that guide the agent's debugging process.
Why does my agent still guess and retry even with the skill installed?
Check that the skill folder is in the right location and that the request describes a failure, such as a failing test or broken build. You can also name the skill directly in your request and ask the agent to follow the triage steps before changing code.
Is this skill suitable for production incidents?
No. The skill prioritises diagnosis and root-cause fixes over rapid rollback, and it does not cover incident response. For a live production problem that needs immediate mitigation, use your team's incident process first.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who want an agent to find the root cause of a bug rather than patch symptoms, especially for regressions and failing tests or builds. It is not worth the overhead for simple, obvious fixes, for production incidents that need immediate mitigation, or for projects that lack the test and build commands it assumes.
Download the skill