Skip to content
Get packs

Guide · Agent skill

How to use the Diagnosing Bugs agent skill (diagnosing-bugs)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Diagnosing Bugs skill is a set of written instructions that tells an AI agent how to debug. It is aimed at developers who are stuck on an intermittent bug, a performance regression, or a problem that only shows up when someone clicks through a UI. After this guide you will know what the skill changes about the agent's behaviour, how to install it from a ZIP or the Claude apps, how to phrase requests so it triggers, and what to watch for around secrets and scripts.

Diagnosing Bugsmattpocock/skills · MIT

Quick start

  1. 1Download the ZIP. Download the diagnosing-bugs ZIP from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
  3. 3Or upload in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill.
  4. 4Describe the bug in plain language. Say what is broken, failing, throwing or slow, and include the word diagnose or debug this.
  5. 5Let the agent build a repro first. Expect a fast, repeatable pass/fail loop before any fix is proposed.
  6. 6Review the ranked hypotheses. Check the agent's ranked guesses and add any domain knowledge you have.

What the Diagnosing Bugs skill makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a request matches the skill's description. This one, diagnosing-bugs, is a diagnosis loop for hard bugs and performance regressions. It applies when you say "diagnose" or "debug this", or when you report that something is broken, throwing, failing or slow.

Instead of reading code and guessing, the agent follows a strict order. It first builds a fast, repeatable test that fails on your exact bug. It then shrinks that test to the smallest failing case, lists ranked guesses about the cause, and only then adds targeted logging to check them.

  • Phase 1: build a feedback loop (a test or script that goes red on this bug).
  • Phase 2: reproduce the bug and minimise the repro.
  • Phase 3: write 3 to 5 ranked, falsifiable hypotheses.
  • Phase 4: instrument one variable at a time, with tagged debug logs.
  • Phase 5: write a regression test at a correct seam, then fix.

Install the skill from the ZIP or the Claude apps

You can install the skill in one of two ways. The first is to download the ZIP from this page and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder so that only that project uses it.

The second is to upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload

Check the skill's files and requirements

The skill folder contains three files: SKILL.md (the instructions the agent reads), agents/openai.yaml, and scripts/hitl-loop.template.sh (an optional script for cases where a human must click through a UI).

The skill needs an agent that can run shell commands and read your codebase. Its core method depends on executing a reproduction loop, so it will not work well where the agent cannot run anything. Depending on the bug, you may also need a test runner, a dev server, or browser automation such as Playwright or Puppeteer. Bash is needed only for the optional human-in-the-loop script.

  • Agent that can run shell commands and read the codebase
  • Whatever your bug needs to reproduce: test runner, dev server, or Playwright/Puppeteer if your loop uses them
  • Bash for the optional scripts/hitl-loop.template.sh

Trigger the skill with natural requests

You do not need a special command. Describe the problem in plain language and include a trigger phrase such as "diagnose" or "debug this", or say that something is broken, throwing errors, failing or slow. The skill's description is what matches your request to the skill.

If you want the full process, say so. The skill says to skip phases only when explicitly justified, so a short request such as a typo may get a quick direct fix instead.

  • "Diagnose why the checkout form sometimes submits twice."
  • "Debug this: the export job throws a timeout after about 20 files."
  • "The dashboard is slow since last week's release, diagnose it."
  • "Login fails in Safari only. Debug this."

What to expect during a session

Expect the agent to ask for a repro before proposing a fix. If it cannot build a loop, it is designed to stop, list what it tried, and ask you for access to the environment, a redacted artifact such as a HAR file or log dump, or permission to add temporary production instrumentation.

For performance regressions, the agent is designed to measure a baseline first, then bisect, rather than add logs. For non-deterministic bugs, it aims to raise the reproduction rate instead of looking for a clean repro.

  • It shows a ranked hypothesis list and may ask you to re-rank it.
  • It tags every debug log with a unique prefix such as [DEBUG-a4f2] so cleanup is one grep.
  • It redacts secrets in output by writing <REDACTED>.

Safety: secrets, scripts and network

The skill tells the agent to redact secrets such as credentials and auth headers when it shows commands, outputs and captured artifacts, writing <REDACTED> in their place. It also advises building loops against environment variables so credentials stay in the environment. This is an instruction to the agent, not something enforced by code, so do not rely on it to guarantee secrets never leak. Review what the agent shows you.

The skill runs scripts (scripts/hitl-loop.template.sh) and does not use the network according to its listing. Read any script before running it.

  • Redaction is an instruction the agent follows, not a guarantee.
  • Keep credentials in environment variables, not in commands you paste.
  • Review the optional Bash script before you let it run.

What people use it for

  • Tracking down an intermittent test or production failure that happens only some of the time.
  • Investigating a performance regression by measuring a baseline and bisecting before changing code.
  • Reproducing a bug that needs a human to click through a UI, using the structured HITL script.
  • Narrowing a failing API call to a minimal curl script against a running dev server.
  • Checking a suspected race condition by looping the trigger many times to raise the failure rate.

Frequently asked questions

How do I install the diagnosing-bugs skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.

Is the diagnosing-bugs skill free to use?

The source material gives the licence as MIT. It does not state pricing, so check the repository's licence file for the terms that apply to your use.

What do I need to run the diagnosing-bugs skill?

You need an agent that can run shell commands and read your codebase. Depending on the bug, you may also need a test runner, a dev server, or Playwright or Puppeteer. Bash is needed only for the optional human-in-the-loop script.

Does the diagnosing-bugs skill use the network?

According to its listing, the skill runs scripts but does not use the network. It still relies on the agent to redact secrets correctly, which is not enforced by code.

Why does the skill make the agent write a test before fixing a bug?

The skill's method is that a tight pass/fail signal is what finds the cause, and guessing without one wastes time. A repeatable test that fails on your exact bug also verifies the fix later. Phase 2 requires reproducing and minimising the bug before any hypotheses are tested.

When should I not use the diagnosing-bugs skill?

Skip it for simple typos or obvious errors where a quick direct fix is enough, since the process is deliberately heavy. Also avoid it where the agent cannot run anything, because the core method depends on executing a reproduction loop.

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

Use this skill when you have an intermittent, hard-to-reproduce, or performance-regression bug, or when you want an agent to reproduce a problem before guessing at fixes. Pick something lighter for simple typos and obvious errors, or in environments where the agent cannot run commands. Treat its secret redaction as a helpful instruction, not a guarantee.

Download the skill