How to use the Debugging Strategies agent skill

What an agent skill is and what this one changes

An agent skill is a folder containing a SKILL.md file and optional reference files. When it is installed, the agent can read the skill's description and load its instructions when a task matches. The skill does not add new software to your machine.

This skill tells the agent to follow a systematic process. It covers reproducing the bug, collecting errors and environment details, forming and testing hypotheses such as binary search through code, adding logging, or comparing working and broken setups, and checking common causes like race conditions and stale caches. It also gives guidance for intermittent bugs, performance problems, and production issues, and names profiling tools for Python and Node.js and browser tools.

• It is guidance only: the files contain no scripts that run on their own.
• It does not require anything else to be installed, and it uses no network access.

Install the Debugging Strategies skill

Download the ZIP for this skill from this page and unzip it. You have two options.

For a personal install that applies to all your projects, unzip it into ~/.claude/skills/ so the folder ends up as ~/.claude/skills/debugging-strategies/. For a single project, put it in that project's .claude/skills/ folder instead.

If you use the Claude apps, you can upload the skill instead under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/debugging-strategies/
• Project only: .claude/skills/debugging-strategies/ inside your repository
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill's description says it applies when investigating bugs, performance issues, or unexpected behavior, so describe your problem in plain words. Mention the symptom, what you expected, and what you have already tried.

Good requests name the situation: a bug that happens only sometimes, a page that got slower after a change, or a function that returns the wrong total for some inputs. Vague requests such as 'fix this' work less well because the agent has less to reproduce.

• "This checkout test fails about one run in five. Help me debug it systematically."
• "Our API response time doubled after yesterday's deploy. Walk me through finding the cause."
• "I'm new to this repo and a user says the export button does nothing. How should I track it down?"

Examples of what the agent will do

With the skill active, the agent typically starts by asking for or looking at the exact steps, full error output, and environment, then proposes a hypothesis and a test for it. For an intermittent bug it will look at shared state, async ordering, and timing, and suggest running the case many times. For performance work it will ask you to measure before changing code and name likely culprits such as N+1 queries or synchronous I/O.

The skill also includes a checklist for when you are stuck, covering items such as off-by-one array indexes, case sensitivity, null values, and file paths that are absolute instead of relative.

Tools the skill points to

The reference file references/tools-and-techniques.md is read before the agent selects tools or performs bisect, differential, trace, or memory analysis. It includes browser DevTools debugger and console techniques, performance marks, and a VS Code debugger configuration. The main file names these profiling tools: Browser DevTools Performance tab and Lighthouse; Python cProfile and line_profiler; Node clinic.js and 0x.

Safety notes before you apply a fix

The skill advises against changing production systems and suggests reproducing locally with anonymized data, using feature flags, and testing fixes in staging. However, a careless agent could still suggest risky changes. Read every proposed fix before applying it, especially anything touching data, deployments, or live services.

The skill runs no scripts and uses no network, so any commands the agent runs come from your own environment and permissions, not from the skill files.

Tips for getting better results

Give the agent the full error text and stack trace rather than a paraphrase. Ask it to change one thing at a time and to record what each test showed. If the bug is simple and the error message already explains it, you may not need the method at all.

• Reproduce first; the skill treats reproduction as the starting point.
• Ask for a hypothesis and a test before any code change.
• Use the skill's guidance on git history to check what changed recently.