claude-code-audit

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: claude-code-audit
description: Forensic audit of the user's recent Claude Code sessions to surface step-change workflow improvements — not marginal ones. Use when the user asks to "audit my Claude Code sessions", "analyze how I use Claude Code", "find patterns in my usage", "improve my Claude Code workflow", "review my sessions", "find leverage in my setup", or wants to understand where their Claude Code setup is leaking time. Samples dozens of real transcripts, extracts quantitative signal via scripts, uses parallel subagents for deep reads, then synthesizes into a short prioritized report with drafted implementations (new skills, CLAUDE.md rules, hooks, settings diffs) that the user can install directly. Trigger even when the user doesn't say the word "audit" — if they're asking about improving or reviewing their Claude Code habits at scale, use this skill.
---

# Claude Code Audit

## What this is

A disciplined framework for auditing a large sample of the user's Claude Code sessions to find **step-change** improvements — the 2–3 changes that would transform their workflow, not the 20 that would polish it.

The default behavior when asked "how can I improve my workflow" is to produce a long list of marginal suggestions. That output is worse than useless: it buries real leverage under pleasant-sounding noise, and the user does nothing with it. This skill exists to prevent that outcome.

## The guarantee

By the end of this audit you will have produced:

1. **A short prioritized report** — the few findings that would actually move the needle, with quantified evidence.
2. **Drafted implementations** — ready-to-install skills, CLAUDE.md rules, hook scripts, or settings diffs for the top recommendations. *Not suggestions. Actual drafts.*
3. **A paper trail** — the extracted data, sampled session list, and subagent findings, so the user can verify the synthesis and revisit it later.

If you end the audit having produced only observations, you have failed.

## Step-change vs marginal — hold this distinction the whole way

| Marginal | Step change |
|----------|-------------|
| "You should use skill X more often" | "Skill X never triggers on prompts like these — its description excludes the phrasing you actually use. Here's a new description." |
| "You correct Claude a lot about testing style" | "You've given the same correction 14 times in 30 days. The root pattern is Claude defaults to unit tests when you want integration tests. Here's a CLAUDE.md paragraph that eliminates the correction loop." |
| "Consider adding tests earlier" | "19 of your 60 sessions have a 'test afterward' → 'fix regression' → 'fix another regression' loop that averages 35 min and 80k tokens. A pre-commit hook that runs your existing test script would short-circuit it." |

The left column is observation. The right column is diagnosis plus prescription plus evidence. You produce the right column.

## Where session data lives

- Root: `~/.claude/projects/<encoded-project-path>/<session-id>.jsonl`
- Each line is one event: `user`, `assistant`, `attachment` (hook result), `system`, `file-history-snapshot`, `last-prompt`.
- The user is at `~/.claude/` with global CLAUDE.md, skills, settings, and hooks. You'll cross-reference against these during synthesis.
- See `references/session_format.md` for the JSONL schema and which fields matter.

## Setup — working directory

Before starting, set `SKILL_DIR` and `AUDIT_DIR`:

- `SKILL_DIR=~/.claude/skills/claude-code-audit` (where the scripts live — never modify this)
- `AUDIT_DIR=~/claude-audit/<date>` (where the audit outputs go — create a fresh subdir per run, or use a path the user provided)

All `python $SKILL_DIR/scripts/...` invocations below assume these are set. Run from any `cwd`; the scripts take absolute paths. Create `AUDIT_DIR` before stage 1.

## The five stages

Create a TaskList for these so the user can see progress. This is a long-running analysis — 20 to 60 minutes depending on sample size.