How to use the Session and Repo Debugger agent skill

What is the debug skill and what does it make the agent do?

An agent skill is a folder containing a SKILL.md file that gives Claude extra instructions for a specific kind of task. When the debug skill is active, the agent follows a fixed workflow for confusing failures: it reads your issue description, inspects the most relevant local evidence, tries to reproduce the problem narrowly, separates the visible symptom from the likely root cause, and recommends the smallest next fix or check.

The evidence it looks at comes from trace tools, state tools, notepad or project memory when relevant, and failing tests or commands. The skill's stated goal is to find the real failure signal quickly and explain the next corrective step.

• Reads the issue and identifies what the user observed.
• Checks trace and state surfaces first when the problem involves orchestration, hooks or agent flow.
• Attempts a narrow reproduction where possible.
• Reports an observed failure, a root-cause hypothesis, the evidence for it and the smallest next action.
• Tags any temporary debug output as [DEBUG-<4hex>] so it can be removed with a single grep.
• Asks for secrets to be redacted from logs and traces before they leave the session.

How do you install the debug skill?

Download the ZIP for the skill from the directory page, then unzip it. The skill is delivered as a folder containing SKILL.md. Place that folder in one of two locations depending on how you want to use it.

For a personal install that applies across your projects, put the unzipped skill folder in ~/.claude/skills/. To limit it to a single project, put it in that project's .claude/skills/ folder instead.

If you use the Claude apps rather than Claude Code, you can upload the skill under Settings → Capabilities → Skills instead of placing files by hand.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills

What do you need before using it?

The skill needs Claude Code or an oh-my-claudecode setup with access to its local trace and state surfaces. It also needs access to the repository and to the failing tests or commands you are debugging. Without local evidence to inspect, the workflow has little to work with.

The skill does not run scripts and does not use the network, according to its listing. It works by reading and reasoning over the local material available to the agent.

• Claude Code, or an OMC setup with access to local trace and state data.
• Access to the repository and to the failing tests or commands.
• Non-technical users without access to logs or a local repo will not get much value from it.

How do you trigger the skill with natural requests?

You do not need a special command. Describe the problem in plain language and say that you want it diagnosed. The skill is meant to activate when you want help with a current OMC or Claude Code session problem, workflow breakage or confusing runtime behaviour.

The more specific your description, the better. Name the symptom, what you expected, and where the failure happened, such as a hook, an agent handoff or a test command.

• "My hook fired twice in this session. Can you diagnose why using the trace and state?"
• "Workflow stopped partway through orchestration. Help me find the real failure signal."
• "The test command fails only in this session, not in my terminal. Reproduce it narrowly and tell me the root cause hypothesis."
• "Figure out what went wrong with the last agent run and suggest the smallest fix to try."

What does a good debugging session look like?

A useful answer follows the output structure in the skill. The agent should first state the observed failure, then offer a root-cause hypothesis, then show the evidence supporting that hypothesis, and finally name the smallest next action. If the evidence points to a missing or wrong seam in the environment, the skill asks the agent to say so plainly and point at the refit or architecture-survey skills.

If the problem is a product or runtime bug rather than a bug in your application code, the skill asks the agent to state that directly. It also says not to prescribe broad rewrites before the failure has been isolated.

• Observed failure
• Root-cause hypothesis
• Evidence for that hypothesis
• Smallest next action

Safety notes: scripts, network and secrets

The skill's listing says it runs no scripts and uses no network. Its instructions still ask the agent to redact secrets from logs and traces before they leave the session.

Redaction is a request to the agent, not a guarantee. Review any log excerpt or trace output yourself before sharing it outside your machine, especially if logs may contain tokens, keys or personal data. The skill should not be used to push logs with secrets to external parties without review.

• No scripts are run by the skill, according to its listing.
• No network use, according to its listing.
• Check redacted output yourself before sharing it.

Tips for getting better results

Give the agent the exact failing command or test and its output. Narrow reproduction is the skill's first preference, so a precise starting point speeds things up. Ask for temporary debug output to be tagged so you can remove it later.

Use the skill for runtime and orchestration problems. For ordinary application bugs, general coding help may be a better fit.

• Paste the exact error message and the command that produced it.
• Mention whether the problem happens only inside Claude Code or also in your terminal.
• Ask the agent to list the cleanup grep for [DEBUG-] tags before finishing.
• Keep the workflow focused on one failure at a time.