How to use the trace agent skill for evidence-driven tracing

What is an agent skill and what does trace make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that Claude loads when a task matches the skill. The trace skill is the orchestration layer for ambiguous, causal questions where the goal is to explain why an observed result happened, not to rewrite code.

When the skill runs, the lead agent works through a fixed contract: it restates the observation, generates competing hypotheses, gathers evidence for each in parallel, runs a rebuttal round, and returns a ranked synthesis. Its output keeps observation, hypotheses, evidence for, evidence against and gaps, the current best explanation, the critical unknown, and a discriminating probe as separate items.

• Restates the observed result precisely before analysis starts
• Runs three tracer lanes by default: code path, config or environment, and measurement or assumption mismatch
• Tries to falsify its own favourite explanation
• Ranks evidence by strength, from controlled reproductions down to speculation
• Ends with a probe that would collapse the remaining uncertainty

Install the trace skill

The skill is distributed as a ZIP from the page you are reading. Download the ZIP and unzip it into one of two locations. Use ~/.claude/skills/ to make it available in all your projects, or a project's .claude/skills/ folder to limit it to one repository.

You can also upload it in the Claude apps under Settings → Capabilities → Skills. The source notes that the skill is designed to run inside Claude's built-in team mode, which sits on top of the oh-my-claudecode toolkit, so the oh-my-claudecode plugin must be installed in Claude Code.

• Download the trace ZIP from this page
• Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project
• Or upload the ZIP in the Claude apps under Settings → Capabilities → Skills
• Confirm the oh-my-claudecode plugin is installed in Claude Code

Check what you need before you start

Trace depends on a few things. Team mode is the key one: the skill is built to coordinate several parallel agents, so you need Claude's built-in team mode available. The agent also needs real material to inspect, because it cannot reason about a bug it cannot see.

• oh-my-claudecode plugin installed in Claude Code
• Claude built-in team mode (multiple parallel agents)
• Access to the relevant codebase, logs, configs or trace artifacts
• The skill runs no scripts and uses no network access, according to the source

How do you trigger the trace skill with a natural request?

The skill's documented entry point is the command /oh-my-claudecode:trace, which takes an observation as its argument. You can also describe the problem in plain language, such as asking why latency rose after a change or why a benchmark result looks wrong, and say you want the cause explained before anything is changed.

Phrase the request around the observation and the question. Name the symptom, what changed, and what evidence exists. The skill is most useful when you explicitly say you do not want a fix yet.

• /oh-my-claudecode:trace "p95 latency doubled after the cache change"
• "Trace back the likely causes of this output. Don't change any code yet."
• "Why did the nightly job drop 30% of rows? Explain before fixing."
• "Here is last week's postmortem data. Rank the competing causes against the evidence."

Examples of useful traces

The source lists the kinds of problems the skill fits: runtime bugs and regressions, performance, latency and resource behaviour, architecture premortems and postmortems, scientific or experimental results, and config or routing behaviour. Each works best when the observation is specific and the evidence is available.

• A regression where tests pass locally but fail in production, with logs and config diffs to inspect
• A latency spike with trace events or metrics, where the question is queueing, code path or configuration
• A postmortem asking which of several contributing causes best fits the logs
• A benchmark that improved unexpectedly, where the analyst needs confounders checked before trusting it

Safety notes: scripts, network and what the agent can read

According to the source, the trace skill runs no scripts and uses no network. It works by reading material you give it access to: code, tests, configs, docs, logs, outputs, benchmark artifacts, and existing trace artifacts through the trace_timeline and trace_summary tools mentioned in its instructions.

Because the agent reads your files and logs, only point it at material you are comfortable having analysed. Review the ranked output as a reasoned hypothesis, not a verdict.

• No scripts are run by the skill, per the source
• No network use, per the source
• The agent can only inspect what you make available to it
• Treat results as ranked likelihoods, not confirmed root causes

Tips for getting better traces

Give the agent a precise observation, not a guess at the answer. Include the evidence you already have, such as logs, timestamps, configs and the exact output. If two causes seem equally likely, ask for the critical unknown and the discriminating probe first, then run that probe yourself before changing code.

• State the observation as a measurable fact, with numbers and timing where you have them
• Include the artifacts the agent should read, such as logs and configs
• Ask it to keep the probe separate from any fix
• Re-run with new evidence when the critical unknown is answered