Debug
Run a reproducible four-step debugging ritual when errors, regressions, or environment mismatches block a solo builder from shipping fixes confidently.
Overview
Debug is an agent skill most often used in Operate (also Ship, Build) that runs a four-step reproduce–isolate–diagnose–fix session from an error message or problem description.
Install
npx skills add https://github.com/anthropics/knowledge-work-plugins --skill debugWhat is this skill?
- Structured /debug command with four phases: reproduce, isolate, diagnose, and fix
- Step 1 captures expected vs actual behavior, exact reproduction steps, and who is affected
- Step 2 narrows code paths and correlates recent deploys, config, and dependency changes with logs
- Fits post-deploy regressions, staging-vs-prod mismatches, and unclear root-cause failures
- CONNECTORS.md reference for unfamiliar placeholders and connected-tool checks
- 4-step structured debugging workflow: reproduce, isolate, diagnose, fix
Adoption & trust: 3.1k installs on skills.sh; 19.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You see a failure or wrong behavior but lack ordered steps to reproduce it, narrow the blast radius, and tie it to a recent change.
Who is it for?
Solo builders debugging regressions after deploy, environment-specific bugs, or stack traces when the failure mode is real but the cause is unclear.
Skip if: Greenfield feature design, pre-code brainstorming, or cases where you already have a minimal reproducible test and a one-line fix—skip the full ritual for trivial typos unless you need audit trail discipline.
When should I use this skill?
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.
What do I get? / Deliverables
You leave the session with confirmed reproduction steps, a narrowed suspect area, a diagnosed root cause informed by logs and change history, and an applied fix you can verify.
- Documented reproduction steps and expected versus actual behavior
- Isolated component or change hypothesis backed by logs and recent change review
- Diagnosed root cause and implemented fix with verification notes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Operate because the skill is triggered by broken behavior, stack traces, and production-versus-staging divergence—the same moment operators need a systematic path from symptom to fix. Errors is the best primary subphase: the workflow centers on expected versus actual behavior, logs, and scope of impact rather than pre-release test planning alone.
Where it fits
Trace an API 500 during local development by reproducing the request and isolating the handler that changed in the last commit.
After a release candidate fails smoke tests, use reproduce and isolate steps to tie the failure to a specific service or config delta.
Investigate customer-reported errors with explicit scope, log review, and recent deploy correlation before patching production.
Turn an alert or error spike into reproduction steps and a narrowed component list instead of flipping random feature flags.
How it compares
Use instead of unstructured back-and-forth chat when you need a fixed debugging checklist, not instead of automated test suites or dedicated APM products.
Common Questions / FAQ
Who is debug for?
Debug is for solo and indie builders using AI coding agents who need a consistent workflow when production, staging, or local behavior diverges and casual guessing wastes time.
When should I use debug?
Use debug when you have an error message or stack trace, when something broke after a deploy, when it works in staging but not production, or during Build and Ship when behavior no longer matches expectations and the cause is not obvious.
Is debug safe to install?
Treat it like any third-party agent skill: review the Security Audits panel on this Prism page and limit agent permissions to what your debugging task requires before running /debug against production systems.
SKILL.md
READMESKILL.md - Debug
# /debug > If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md). Run a structured debugging session to find and fix issues systematically. ## Usage ``` /debug $ARGUMENTS ``` ## How 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 ```markdown ## 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 1. **Share error messages exactly** — Don't paraphrase. The exact text matters. 2. **Mention what changed** — Recent deploys, dependency updates, and config changes are top suspects. 3. **Include context** — "This works in staging but not prod" or "Only affects large payloads" narrows things fast.