How to use the Hunt root-cause debugging agent skill

What the Hunt skill makes the agent do

When something errors, crashes, regresses or stops working, Hunt tells the agent to stop and state a specific, testable explanation of the cause first. The agent must name a file, function, line or condition, and state it in the form "I believe the root cause is [X] because [evidence]." Until that sentence exists, the agent is not supposed to touch code.

The skill then asks the agent to check every reported symptom against that explanation, reproduce the problem, read logs and state, and apply a fix only when a repeatable check verifies it. It also sweeps the codebase for the same bug pattern elsewhere and reports what it finds.

• Report-only words such as "diagnose", "investigate", "why" or "look into" mean the agent investigates without fixing.
• A fix is applied only when your request explicitly asks for one, such as "fix", "change", "implement" or "optimize".
• A fix authorization never includes commit, push, publish or destructive actions.

Install the Hunt skill

Download the ZIP for the hunt skill from the directory page and unzip it. Then place the folder in one of two locations, depending on how you want to use it.

You can also upload the skill through the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal install: unzip into ~/.claude/skills/ so it is available across your projects.
• Project install: unzip into the project's .claude/skills/ folder so it applies only to that repository.
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Check what you need before you start

Hunt needs Git, because its bisect and diff workflows run commands such as git status, git diff and git bisect. The agent also needs a runtime that can read your repository and run commands. The exact test or build tools depend on your project.

The skill runs scripts, but it does not use the network, according to the directory listing.

• Git installed and the project under version control
• An agent runtime that can read files and run commands in the repository
• Your project's own test or build tools available locally

Trigger Hunt with a natural request

You do not need a special command. Describe the problem in plain words and mention the failure. The skill's trigger phrases include "debug", "regression", "used to work", "broke after update", "why broken", "not working", "fix error" and "stack trace". Chinese triggers such as 排查 and 报错 also work.

Say what you already know. If the bug used to work at a specific commit or version, say so, because that switches the agent into bisect mode.

• "This test started failing after the last merge. Find the root cause before changing anything."
• "The export crashes with a stack trace pasted below. Why is it breaking?"
• "It used to work on v2 of the parser. Look into what changed."
• "The fix I applied didn't hold, the same error is back. Diagnose it again."

Use bisect mode and repeated-regression mode

When you say something worked before, Hunt activates bisect mode. It first checks git status. If there are modified, staged or untracked files, the agent runs the search in a temporary detached worktree and removes that worktree afterward. If a temporary worktree is not possible, it asks for your approval before cleaning up or stashing.

If the last good version is only a few releases back, the agent reads the diff first. Bisect is used when the diff is too large or the culprit is unclear. Bisect requires a non-interactive pass or fail command defined in advance.

When the same issue is still wrong after a fix, or you provide a good screenshot or version, the skill treats that reference as evidence. The agent lists every symptom in your words and defines a pass/fail check before editing.

Read the output and verify the result

A Hunt run should end with a root cause, the fix or handoff, the verification result and any sibling risks it did not fix. The skill's runtime evidence ladder asks for a source trace, a deterministic repro, logs or state, a narrow test or build, and for UI or native bugs a real runtime check with a screenshot or checklist.

Compiling is not enough for visual or rendering bugs. If the agent cannot run the real check in your environment, it should tell you why and give you the exact screen or command to verify.

• Sibling sweep: after a fix, the agent greps for the same pattern and labels each match as same bug, safe to leave, or unsure.
• Unrelated bugs found during the sweep are listed, not fixed, unless you agree.