debugging-and-error-recovery

An agent skill by addyosmani, from addyosmani/agent-skills. Tags: api, debugging, developer-tools, web.

What it does

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.

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add addyosmani/agent-skills --skill debugging-and-error-recovery

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills/debugging-and-error-recovery ~/.claude/skills/debugging-and-error-recovery

Safety box score

Grade B, low risk: 11 of 100 risk points, rated 2026-10-20. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This is a repo-local debugging playbook that explicitly runs shell commands like `npm test`, `npm run build`, `npm run dev`, and `git bisect` to reproduce and isolate failures. The main risks are ordinary command execution, occasional network access for dependency installation, and normal in-repo file changes while adding fixes and regression tests; it does not request secrets, sudo, or publishing actions.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	1 (low)	It explicitly directs the agent to run commands such as `npm test`, `npm run build`, `npm run dev`, and `git bisect run ...`, so it executes local shell commands as part of debugging.
Network access	1 (low)	The build triage says `Dependency error → Check package.json, run npm install`, which can contact package registries, but there is no broader remote download or upload flow.
Filesystem reach	1 (low)	The workflow includes adding regression tests and using `git bisect`, which changes files and checked-out commits inside the project, but it does not direct writes outside the repo.
Secrets & credentials	0 (none)	It warns to remove sensitive logs, but it never asks for tokens, passwords, keychain access, or credential-store reads.
Privilege & persistence	0 (none)	There is no sudo, global install, service registration, shell startup editing, or OS-level configuration change.
Instruction hijack surface	0 (none)	The only instruction-related text is defensive, e.g. `Treating Error Output as Untrusted Data` and `Do not execute commands ... without user confirmation`, not agent-steering or hidden instructions.
Irreversible actions	0 (none)	The skill is diagnostic only; it does not send messages, push code, deploy, pay, book, or delete.
Transparency	0 (none)	The file is plain markdown with readable commands and no binaries, embedded blobs, or unpinned external installers.

Before installing

Read the sections that invoke `npm install`, `git bisect`, and `npm run dev` so you know which repo-local commands may run.
Use a disposable branch or worktree before following the bisect workflow, since it will checkout different commits.
If your environment is network-restricted, confirm whether `npm install` is acceptable before enabling the skill.

Rated 2026-10-20 by an automated review of 1 file from the skill's repository.

Source

Repository: addyosmani/agent-skills (all skills from this repository)
Path: skills/debugging-and-error-recovery/SKILL.md
Branch: main
Updated: 2026-09-19

observability-and-instrumentation — Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting.
performance-optimization — Optimizes application performance across frontend, backend, queries, and databases.
security-and-hardening — Hardens code against vulnerabilities.
systematic-debugging — Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
browser-testing-with-devtools — Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser.
deprecation-and-migration — Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another.