Home
Structured debugging session — reproduce, isolate, diagnose, and fix. Trigger with an error message or stack trace, "this works in staging but not prod", "something broke after the deploy", or when behavior diverges from expected and the cause isn't obvious.
...Expand allAbout debug
The debug skill is designed to guide users through a structured debugging workflow when software behavior is incorrect, unclear, or has regressed. It is intended for situations where an error message, stack trace, or unexpected behavior indicates a problem that cannot be immediately diagnosed. By organizing the debugging process into clear phases, it helps users move from symptom observation to root-cause identification in a systematic way rather than relying on guesswork.
The skill follows a four-step methodology: reproduction, isolation, diagnosis, and fix. In the reproduction phase, it focuses on clarifying expected versus actual behavior and establishing reliable steps to reproduce the issue. The isolation phase narrows down the affected components by reviewing recent changes such as deployments, configuration updates, or dependency changes, while also analyzing logs and error outputs. During diagnosis, the process emphasizes forming and testing hypotheses, tracing execution paths, and identifying the underlying root cause instead of surface-level symptoms. Finally, the fix phase focuses on proposing corrective changes while considering side effects and recommending preventive tests to avoid regressions.
This skill is primarily aimed at developers, DevOps engineers, QA testers, and site reliability engineers who regularly troubleshoot production and development issues. It is especially useful in scenarios such as deployment regressions, environment-specific bugs (e.g., staging vs production differences), or unexplained failures after recent changes. By enforcing a disciplined debugging structure, it reduces trial-and-error debugging and improves consistency in incident resolution workflows.
FAQ
What kind of input should I provide to use this debugging skill?
You should provide an error message, stack trace, description of unexpected behavior, reproduction steps, or context such as recent changes or logs. The more precise the information, the more effective the debugging process will be.
Does this skill require access to external tools or connectors?
It can optionally make use of available connectors such as monitoring systems, source control, or project tracking tools if they are connected. However, it can still function using only the provided description, logs, and context.
What kind of problems is this skill not suitable for?
It is not intended for purely theoretical questions or general explanations. It is specifically focused on diagnosing and resolving concrete software issues with observable incorrect behavior.
/debug
If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.
Run a structured debugging session to find and fix issues systematically.
Usage
/debug $ARGUMENTSHow It Works
┌─────────────────────────────────────────────────────────────────┐│ DEBUG │├─────────────────────────────────────────────────────────────────┤│ Step 1: REPRODUCE ││ ✓ Understand the expected vs. actual behavior ││ ✓ Identify exact reproduction steps ││ ✓ Determine scope (when did it start? who is affected?) ││ ││ Step 2: ISOLATE ││ ✓ Narrow down the component, service, or code path ││ ✓ Check recent changes (deploys, config changes, dependencies) ││ ✓ Review logs and error messages ││ ││ Step 3: DIAGNOSE ││ ✓ Form hypotheses and test them ││ ✓ Trace the code path ││ ✓ Identify root cause (not just symptoms) ││ ││ Step 4: FIX ││ ✓ Propose a fix with explanation ││ ✓ Consider side effects and edge cases ││ ✓ Suggest tests to prevent regression │└─────────────────────────────────────────────────────────────────┘What I Need From You
Tell me about the problem. Any of these help:
- Error message or stack trace
- Steps to reproduce
- What changed recently
- Logs or screenshots
- Expected vs. actual behavior
Output
## Debug Report: [Issue Summary]### Reproduction- **Expected**: [What should happen]- **Actual**: [What happens instead]- **Steps**: [How to reproduce]### Root Cause[Explanation of why the bug occurs]### Fix[Code changes or configuration fixes needed]### Prevention- [Test to add]- [Guard to put in place]
If Connectors Available
If ~~monitoring is connected:
- Pull logs, error rates, and metrics around the time of the issue
- Show recent deploys and config changes that may correlate
If ~~source control is connected:
- Identify recent commits and PRs that touched affected code paths
- Check if the issue correlates with a specific change
If ~~project tracker is connected:
- Search for related bug reports or known issues
- Create a ticket for the fix once identified
Tips
- Share error messages exactly — Don't paraphrase. The exact text matters.
- Mention what changed — Recent deploys, dependency updates, and config changes are top suspects.
- Include context — "This works in staging but not prod" or "Only affects large payloads" narrows things fast.
Install debug
Download and extract the skill files to your .claude/skills/ directory.
Download ZIPClone the repository and copy the skill files to your project.
git clone https://github.com/anthropics/knowledge-work-plugins/blob/main/engineering/skills/debug/SKILL.md # Copy SKILL.md to your .claude/skills/ directory
Copy
