audit-session-metrics
# audit-session-metrics Analyzes session-metrics JSON exports to identify token-usage inefficiencies and produce prioritized audits in plain English. Supports three scopes (session, project, instance) with quick or detailed audit modes, routing the export through Python extraction logic to generate a scope-aware digest for review. Use when investigating conversation overhead, model context waste, or cost optimization across single sessions, projects, or entire Claude Code instances.
git clone --depth 1 https://github.com/centminmod/my-claude-code-setup /tmp/audit-session-metrics && cp -r /tmp/audit-session-metrics/.claude/skills/audit-session-metrics ~/.claude/skills/audit-session-metricsSKILL.md
# Audit Session-Metrics
Reads a session-metrics JSON export and produces a prioritised, plain-English
audit of token-usage waste. It runs on the session's current model (it no
longer pins one — a hard model pin capped the usable context at that model's
window and broke invocation on long sessions). The work is mostly
summarisation over a small disk-read export, so for a ~10× cheaper run
`/model haiku` before invoking (short/early sessions only — Haiku's 200k
window can't hold a long conversation).
Supports three JSON scopes auto-detected from `digest.scope`:
- **session** — single session (`session_*.json`) — per-turn analysis
- **project** — all sessions for one project (`project_*.json`) — per-session analysis
- **instance** — all projects (`instance/*/index.json`) — per-project analysis
## Dispatch — how to route this invocation
**First positional argument received:** `$ARGUMENTS[0]`
**Second positional argument received:** `$ARGUMENTS[1]`
Read `$ARGUMENTS[0]` and match by **literal equality**:
| `$ARGUMENTS[0]` | Route | Then read (session scope) | Then read (project/instance scope) |
|-----------------|--------------------------|---------------------------|------------------------------------|
| `quick` | Quick audit | [`references/quick-audit.md`](references/quick-audit.md) | see Scope routing below |
| `detailed` | Detailed audit | [`references/detailed-audit.md`](references/detailed-audit.md) | see Scope routing below |
| *(empty / other)* | Print usage and stop | this file's "Usage" block below | — |
`$ARGUMENTS[1]` must be the path to a JSON export written by session-metrics.
Accepted patterns:
- `exports/session-metrics/session_<id8>_<ts>.json` — session scope
- `exports/session-metrics/project_<ts>.json` — project scope
- `exports/session-metrics/instance/<datedir>/index.json` — instance scope
If `$ARGUMENTS[1]` is missing, empty, or the file does not exist, print:
> Usage: /audit-session-metrics {quick|detailed} <path-to-session-metrics.json>
>
> Accepted JSON types:
> session: exports/session-metrics/session_*.json
> project: exports/session-metrics/project_*.json
> instance: exports/session-metrics/instance/*/index.json
…and stop without further work.
## Steps
1. Run the extract helper once with the input path:
```
python3 scripts/audit-extract.py $ARGUMENTS[1] --mode $ARGUMENTS[0]
```
The helper emits a single JSON digest to stdout. Read `digest.scope`
from the output — it will be `"session"`, `"project"`, or `"instance"`.
**Do not** read the raw `.jsonl`, and **do not** re-derive numbers the
digest already carries.
2. **Scope routing — read the matching reference file:**
| `digest.scope` | `$ARGUMENTS[0]` | Reference file |
|----------------|-----------------|----------------|
| `session` | `quick` | [`references/quick-audit.md`](references/quick-audit.md) |
| `session` | `detailed` | [`references/detailed-audit.md`](references/detailed-audit.md) |
| `project` | `quick` | [`references/project-quick-audit.md`](references/project-quick-audit.md) |
| `project` | `detailed` | [`references/project-detailed-audit.md`](references/project-detailed-audit.md) |
| `instance` | `quick` or `detailed` | [`references/instance-quick-audit.md`](references/instance-quick-audit.md) |
Follow the playbook step-by-step. Do not improvise additional phases.
3. For `detailed` mode **on session scope only**, the playbook also asks
you to read the user's config files (`~/.claude/CLAUDE.md`,
`./CLAUDE.md`, `~/.claude/settings.json`, `./.claude/settings.json`,
`./.claudeignore`). Each is capped at ≤500 lines — if a file is
bigger, that itself is a finding.
4. **Output contract — three artefacts.** All playbooks specify the
same three-artefact contract:
- **JSON sidecar** at `<project>/exports/session-metrics/audit_<id8>_<ts>_<mode>.json` — structured findings (versioned schema, enum'd metrics).
- **Markdown copy** at `<project>/exports/session-metrics/audit_<id8>_<ts>_<mode>.md` — same content rendered for humans.
- **Inline chat output** — the markdown content printed in your reply.
`<id8>` and `<ts>` come from `digest.session_id_short` and
`digest.ts_str` (the helper parses the input filename and
normalises all three filename patterns).
5. **Write order.** Populate the JSON object first using the digest
values, write the JSON sidecar, render the markdown using the
template in the playbook, write the markdown copy, then print the
markdown inline (without the H1 heading — the chat client already
shows context above the audit). Finish with two stderr-style lines
on their own:
`[audit] saved → <json-path>`
`[audit] saved → <md-path>`
**IMPORTANT:** Use the **Write tool** directly for steps 3 and 5.
Do NOT generate a Python script (e.g. writing to `/tmp/audit_synthesis.py`
and executing it) — this adds unnecessary failure modes (syntax errors,
f-string escaping) and is never required. Build the JSON in the AI's own
context; call Write. Render the markdown in context; call Write again.
## Tone
- **Direct and specific.** Cite the exact ratio, dollar figure, or turn
index. No motivational language, no LLM-theory padding.
- **Prioritise by impact.** Sort findings so the costliest fix is first.
- **Quote sparingly.** Snippets capped at 5 lines each.
- **Honour the playbook.** If quick-audit.md asks for 5 rows, produce 5
rows — don't invent a 6th to look thorough.
## Why this is a separate skill
The audit is a distinct, user-initiated analysis step over a finished
export, not part of generating one. It reads only the on-disk JSON — never
the conversation — so it stands alone as its own turn, which is why
session-metrics *suggests* `/audit-session-metrics` rather than invoking it
programmatically. Running it as a fresh slash command keeps the turn focuseUse this agent for comprehensive codebase analysis, forensic examination, and detailed code mapping with optional Chain of Draft (CoD) methodology. Excels at locating specific functions, classes, and logic, security vulnerability analysis, pattern detection, architectural consistency verification, and creating navigable code reference documentation with exact line numbers. Examples: <example>Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" <commentary>Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic.</commentary></example> <example>Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" <commentary>The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code.</commentary></example> <example>Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" <commentary>Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files.</commentary></example> <example>Context: User requests comprehensive security analysis using Chain of Draft methodology. user: "Analyze the entire authentication system using CoD methodology for comprehensive security mapping" assistant: "I'll use the code-searcher agent with Chain of Draft mode for ultra-concise security analysis" <commentary>The user explicitly requests CoD methodology for comprehensive analysis, so use the code-searcher agent's Chain of Draft mode for efficient token usage.</commentary></example> <example>Context: User wants rapid codebase pattern analysis. user: "Use CoD to examine error handling patterns across the codebase" assistant: "I'll use the code-searcher agent in Chain of Draft mode to rapidly analyze error handling patterns" <commentary>Chain of Draft mode is ideal for rapid pattern analysis across large codebases with minimal token usage.</commentary></example>
Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code.
Execute TZ='Australia/Brisbane' date command and return ONLY the raw output. No formatting, headers, explanations, or parallel agents.
Use this agent proactively to synchronize memory bank documentation with actual codebase state, ensuring architectural patterns in memory files match implementation reality, updating technical decisions to reflect current code, aligning documentation with actual patterns, maintaining consistency between memory bank system and source code, and keeping all CLAUDE-*.md files accurately reflecting the current system state. Examples: <example>Context: Code has evolved beyond documentation. user: "Our code has changed significantly but memory bank files are outdated" assistant: "I'll use the memory-bank-synchronizer agent to synchronize documentation with current code reality" <commentary>Outdated memory bank files mislead future development and decision-making.</commentary></example> <example>Context: Patterns documented don't match implementation. user: "The patterns in CLAUDE-patterns.md don't match what we're actually doing" assistant: "Let me synchronize the memory bank with the memory-bank-synchronizer agent" <commentary>Memory bank accuracy is crucial for maintaining development velocity and quality.</commentary></example>
Use this agent when you need comprehensive UX/UI design guidance, including user experience optimization, premium interface design, scalable design systems, data visualization with Highcharts, or Tailwind CSS implementation. Examples: <example>Context: User is building a dashboard with complex data visualizations and wants to improve the user experience. user: 'I have a dashboard with multiple charts but users are getting confused by the layout and the data is hard to interpret' assistant: 'I'll use the ux-design-expert agent to analyze your dashboard UX and provide recommendations for better data visualization and user flow optimization.'</example> <example>Context: User wants to create a premium-looking component library for their product. user: 'We need to build a design system that looks professional and scales across our product suite' assistant: 'Let me engage the ux-design-expert agent to help design a scalable component library with premium aesthetics using Tailwind CSS.'</example> <example>Context: User is struggling with a complex multi-step user flow. user: 'Our checkout process has too many steps and users are dropping off' assistant: 'I'll use the ux-design-expert agent to streamline your checkout flow and reduce friction points.'</example>
Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis.
Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, GPT-5.4 Image 2, proxied through Cloudflare AI Gateway BYOK). Also analyze/describe existing images using multimodal AI vision. Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", "describe this image", "analyze this image", "what's in this image", "explain this image", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5, gpt5.4), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), image analysis (--analyze), and per-project cost tracking (--costs).
Consult official Claude Code documentation from code.claude.com using selective fetching. Use when working on hooks, skills, subagents, plugins, agent teams, MCP servers, permissions, settings, CI/CD (GitHub Actions, GitLab), IDE extensions (VS Code, JetBrains), desktop/web app features, scheduling, memory/CLAUDE.md, deployment (Bedrock, Vertex, Foundry), sandboxing, monitoring, or any Claude Code feature requiring official docs. Fetches only the specific docs needed per task.