What does this skill do, and when should you use it?
This is a general-purpose debugging workflow for AI coding agents handling failed tests, broken builds, runtime bugs, and production incidents. It tells the agent to stop making changes, preserve evidence, and proceed through reproduction, localization, reduction, root-cause repair, recurrence prevention, and end-to-end verification. It also includes failure-specific triage patterns, safe fallback guidance, instrumentation advice, and rules for treating error output as untrusted data. It fits engineering teams that want verifiable debugging instead of guess-driven fixes.
It directs the agent to collect error output, logs, environment details, and reproduction steps; run targeted, verbose, isolated, full-suite, and build commands; localize failures to the UI, API, database, build tooling, external service, or test; use git bisect when investigating regressions; create a minimal failing case; fix the underlying cause; add a regression test; and verify the original scenario, test suite, and build end to end.
- A frontend or backend developer gets a failing test after a code change and needs to distinguish an outdated test from a code defect.
- An engineer encounters a type, import, configuration, dependency, or environment build failure and needs a structured diagnosis.
- A maintainer faces an intermittent runtime bug and needs to investigate timing, environment, state, or randomness.
- A production support engineer receives an error report or log failure and needs to preserve evidence, narrow the fault, and verify the fix.
- A team wants every bug fix to include a regression test and complete verification before resuming feature work.
How do you install this skill?
- Before running npm install, git bisect, a development server, or production alerting, define scope, obtain confirmation where appropriate, and establish permissions and rollback.
- The npm/test/build commands may not fit non-npm or non-JavaScript projects; verify the project's toolchain before applying example flags mechanically.
- Logs and error context may contain credentials, personal data, or business data; the skill mentions removing sensitive logs but lacks a systematic redaction and access-control procedure.
- No dedicated execution tests for this skill's key paths are provided, so static review cannot establish stable effectiveness in target environments.
- Shell / CLI
- Local filesystem
Node.jsnpmGit
Install the collection with: npx skills add addyosmani/agent-skills. Install this individual skill with: npx skills add addyosmani/agent-skills --skill debugging-and-error-recovery. The README also documents repository-level installation for Codex CLI v0.122+: codex plugin marketplace add addyosmani/agent-skills.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/addyosmani/agent-skills.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/debugging-and-error-recovery" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- This test started failing after a code change. Diagnose it in order: reproduce, localize, reduce, fix the root cause, add recurrence protection, and verify end to end.
In a compatible agent where the skill is installed, invoke it when tests fail, builds break, behavior is unexpected, or an error appears. Example prompt: “This test started failing after a code change. Diagnose it in order: reproduce, localize, reduce, fix the root cause, add recurrence protection, and verify end to end.” The skill file does not specify a separate client-specific invocation syntax.
What are this skill's strengths and limitations?
- Defines an ordered workflow covering reproduction, localization, reduction, repair, regression protection, and verification.
- Covers test failures, build errors, runtime errors, intermittent failures, and production incidents.
- Requires evidence preservation, regression tests, and end-to-end checks.
- Includes practical guidance for safe fallbacks, instrumentation, and untrusted error output.
- The supplied material does not show a dedicated test suite or platform-specific integration for this skill.
- Its command examples assume Node.js/npm and Git; projects may need different test and build commands.
- It provides a diagnostic process rather than automatic diagnosis or project-specific tool configuration.
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Systematic Debugging & Recovery this page | 49 · Use with care | ★ 107k | 13d ago | MIT |
| cmux Testing Skill | 60 · Recommended | ★ 28k | 12d ago | NOASSERTION |
| e2e Verify — End-to-End Change Verification Skill | 64 · Recommended | ★ 10k | 12d ago | Apache-2.0 |
| Agent Tool Design Guide | 51 · Use with care | ★ 18k | 15d ago | MIT |
| Jetson BSP Image Validator ✓ NVIDIA · Official | 50 · Use with care | ★ 3.6k | 12d ago | Apache-2.0 |
How did FollowSkills review this skill?
The skill explicitly preserves evidence, treats error output as untrusted data, and requires removing sensitive logs; however, npm install, git bisect, development-server execution, and alert setup can create external or environment effects without user confirmation, privilege boundaries, or rollback guidance. Data-flow and production-incident safeguards are also incomplete, so points are deducted.
The six-step workflow is internally coherent and includes branches for non-reproducible, test, build, and runtime failures; however, its commands assume npm, Node, and particular test-runner flags, with no adaptation across toolchains and no committed executable evidence reproducing this skill's key paths. The static cap therefore applies.
Trigger scenarios are clear and cover test, build, runtime, and production problems, including a non-reproducible path; however, “anything unexpected” is broad, non-fit boundaries and input/output expectations are not explicit, and JavaScript-centric examples lack Chinese-language or broader environment guidance. Points are deducted accordingly.
The document has clear progressive sections for overview, triggers, workflow, patterns, red flags, and verification. The repository README supplies installation guidance, while MIT licensing, team information, and CI are present; however, the skill lacks independent versioning, changelog, maintenance ownership, update path, FAQ material, dependency notes, and toolchain alternatives.
The workflow can directly guide root-cause isolation, regression-test creation, and end-to-end verification, providing clear marginal value over ad hoc debugging; however, the commands and examples are generic, there is no representative output verification, and project-specific adaptation may be required. The score remains within the static maximum.
The skill is auditable source material, and repository CI validates skill structure, the evaluation runner, and installation structure; however, the supplied test fixture is unrelated to this skill, and no dedicated key-path tests or third-party execution evidence are shown, so only limited credit is justified.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →