How to use the agenttrace Session Audit agent skill

What the skill makes the agent do

Agent skills are folders of instructions that Claude loads when a request matches them. This one, agenttrace-session-audit, tells the agent how to use agenttrace to look at the process behind a coding run: token and cost spikes, repeated tool failures, retry loops, latency gaps, anomalies, health scores and differences between sessions.

The skill is guidance only. The bundle contains a SKILL.md file and does not include the agenttrace program itself, so you must install agenttrace separately.

• Reads local session logs from tools such as Claude Code, Codex CLI, Gemini CLI, Aider, Cursor exports, OpenCode, Qwen Code, Kimi, and generic JSON or JSONL traces.
• Produces reports, leading with the highest-risk sessions.
• Can suggest comparing a run against a previous or known-good attempt.

Install the agenttrace Session Audit skill

Download the ZIP from this page and unzip it. The skill folder should contain SKILL.md. Then place it in one of these locations:

For Claude Code, put the unzipped skill folder in ~/.claude/skills/ for your user account, or in .claude/skills/ inside a project to share it with that project.

In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ in the project folder
• Claude apps: Settings → Capabilities → Skills

Install agenttrace itself

The skill expects the agenttrace command-line tool to be available. Install it so that the agenttrace command runs from your PATH. If you are working inside the agenttrace repository, the skill can use go run ./cmd/agenttrace instead.

Before relying on the output, check the installed version and its --help, because adapter coverage and flags can change.

Trigger the skill with natural requests

You do not need a special command. Ask in plain language about a coding run and the agent should pick the skill when the request matches its use cases. Good triggers name the run and the problem, for example asking why a session was expensive or whether a failed task is worth retrying.

Point the agent at the exact session or export when you can. The skill notes that --latest can select an unrelated run, so check the project, time and session ID first.

• Why was my last Claude Code run so expensive?
• Review the local agent logs before I retry this failed task.
• Check whether this session had repeated tool failures or long latency gaps.
• Compare this attempt with the earlier one that worked.

Run a basic audit and read the report

The skill starts by discovering sessions, then writes a report. The first step checks what agenttrace can see. If no sessions are detected, the agent should list the directories checked by --doctor and ask you for the exported session file or log directory.

For a shareable report, ask for Markdown. The agent should lead with critical anomalies, repeated tool failures, token or cost waste, long latency gaps, low health scores and suspiciously shallow sessions.

Inspect one session and compare attempts

To audit a single run, point agenttrace at an export file or a session directory. Metrics can look healthy while the agent has taken the wrong implementation path, so the skill recommends pairing the trace audit with a diff against a known-good attempt.

When comparing, look for changed files or commands that diverge from the task, missing tests, repeated edits to the same files without a clear reason, and lower cost that came from skipping necessary exploration.

• Changed files or commands that diverge from the intended task
• Missing tests or verification steps compared with the reference attempt
• Repeated edits around the same files without a clear reason
• Lower cost that came from skipping necessary exploration

Add a CI health gate

For CI or repeatable team workflows, the skill suggests JSON output and health thresholds. Tune thresholds to your project. A strict gate suits critical workflows, while a reporting-only command is better while the team learns its normal baseline. Start advisory, then tighten gradually.

Keep in mind that health thresholds are advisory process metrics, not merge-review authority.

• Write JSON output for automation.
• Use --fail-under-health, --fail-on-critical and --max-tool-fail-rate to set limits.
• Begin with reporting only if failures are frequent.