How to use the Debug and Fix agent skill (ce-debug)

What is an agent skill and what does ce-debug do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a request matches the skill's purpose. The skill's main file is SKILL.md, and it is supported by reference files that the agent reads at specific phases.

Once ce-debug is installed, the agent works through a bug in five phases: triage, investigate, root cause, fix, and handoff. It reproduces the failure, traces the cause back through the code with file and line evidence, and only then proposes a fix. In interactive use it asks you before changing code. Where existing test coverage already owns the behavior, it adds a regression test. If it keeps failing, it stops guessing and diagnoses why it is stuck.

• Reproduces the failure before proposing a cause
• Traces the causal chain from trigger to symptom with file:line evidence
• Asks before editing code in interactive mode
• Adds a regression test where existing coverage owns the behavior
• Escalates after 2-3 hypotheses fail or 3 failed fix attempts

How do you install the ce-debug skill?

Download the ZIP for the ce-debug skill from this page and unzip it. Then place the folder in one of two locations, depending on whether you want the skill for all projects or one project.

For a personal install available across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before you run it?

The skill inspects the working tree and may stash changes, so the project being debugged must be a Git repository. It also needs the project's own test runner and whatever tools are required to reproduce the failure. Issue tracker access is optional; with it, the agent can fetch an issue by reference from systems such as GitHub, Linear or Sentry.

The skill runs scripts and uses the network, so plan for that before you enable it.

• A Git repository for the project being debugged
• The project's test runner and the tools needed to reproduce the failure
• Optional: issue tracker access (for example GitHub, Linear, Sentry) to fetch an issue by reference

How do you trigger ce-debug with a natural request?

You do not need special syntax. Describe the problem in plain language, or give an issue reference, an error message or a test path. The skill's argument hint lists the accepted inputs: an issue reference, error message, test path, or description of broken behavior.

Include what you already know, such as the failing command or the symptom, because the agent needs a reproducible failure to work from.

• "Debug why the checkout test in tests/cart.test.ts fails with a timeout."
• "Fix this error: [paste the error message]"
• "Investigate #123 and tell me the root cause before changing anything."
• "This endpoint got slow after the last merge. Find out why."

What happens during a debug session?

The agent first states the problem, then tries to reproduce it and checks the environment. It traces backward from the symptom to the trigger, looks for related tickets or prior pull requests, and forms hypotheses. It tests one hypothesis and one change at a time, because changing several things at once hides which one mattered.

Before editing, the agent writes up the causal chain with file:line references, the proposed fix, which tests to use or add, and any related ticket or PR. In interactive mode it then asks you whether to apply the fix. If an open PR already fixes the bug, it leads with that link instead of writing a new fix.

What does pipeline mode do?

When an orchestrator such as ce-babysit-pr or lfg calls the skill with mode:pipeline, it runs without asking questions. It returns a structured status that is exactly one of fixed-and-pushed, fixed-not-pushed, diagnosed-no-fix, flaky-infra or needs-human. In this mode the agent may commit and push fixes without a human gate, so review the setup before enabling it.

A mode:return-to-caller variant, used by lfg on its defect route, returns fixed, diagnosed-no-fix, needs-human or blocked and commits without pushing.

• mode:pipeline: non-interactive, may push
• mode:return-to-caller: non-interactive, commits without pushing

What are the safety notes for ce-debug?

Reproduction and environment checks execute code, and command output can print secrets. The skill's guidance is to keep credentials in environment variables, capture verbose output to a file, and surface only sanitized excerpts with secrets replaced by <REDACTED>. If sanitizing removes what the diagnosis needs, the agent should ask you rather than reveal the value.

Do not use the skill on repositories where the agent should not run commands. Do not use it for production incidents where a fix should be reviewed by people first, and be careful with pipeline modes, which can commit and push.

• Reproduction runs code; avoid repositories where command execution is not allowed
• Secrets are redacted in evidence; credentials should live in env vars
• The skill may stash your uncommitted changes during the dirty-tree experiment
• Pipeline modes can commit and push without a human gate

Tips for getting better results

Give a reproducible failure. Without one, the skill's full five-phase process adds ceremony and a quick question is better asked directly. Keep your working tree in a known state before starting, and read the written causal chain before approving a fix.

• Provide a failing test, command or exact error text
• Commit or note your in-progress work so stashing is easy to reason about
• Review the causal chain before approving any change