---
name: cache-audit
description: Audit Claude Code configuration against prompt caching best practices. Checks system prompt ordering, hook injection patterns, tool stability, model switching, dynamic content size, and thinking block behavior. Returns a scored report with specific fixes. Use when running '/cache-audit', asking 'am I breaking the cache?', or optimizing Claude Code session costs. Do NOT use for auditing web app codebases that call the Claude API — use cost-audit instead.
disable-model-invocation: true
---

# Prompt Cache Audit

Audit the user's Claude Code setup against the 6+1 prompt caching rules derived from Anthropic's official documentation. Produce a scored report in one pass — do not ask for confirmation before running checks.

## Step 1: Read Configuration

Read these files (skip any that don't exist):
1. `~/.claude/settings.json`
2. All `CLAUDE.md` files in the project hierarchy (global, project, local)
3. Any hook scripts referenced in settings.json
4. `~/.claude/skills/*/SKILL.md` — scan frontmatter only
5. MCP server configuration files referenced in settings

## Step 2: Run All Checks

Run checks 1–7 below. For each check, record a verdict: PASS, WARNING, or FAIL.

For pricing math and thresholds, see [references/caching-rules.md](references/caching-rules.md).

### Check 1 — Prompt Ordering (Static Before Dynamic)

Cache hierarchy: `tools` -> `system` -> `messages`. Static content must come first.

1. Verify CLAUDE.md files contain only static instructions (conventions, file references, rules).
2. Flag any dynamic content in CLAUDE.md: timestamps, `!`-backtick commands that produce volatile output, git status, counters.
3. Flag any `currentDate` or date injection that lives in the system prompt rather than in a message.

| Verdict | Condition |
|---------|-----------|
| PASS | All system-level content is static |
| WARNING | Low-frequency dynamic data in system prompt (changes daily, not per-turn) |
| FAIL | High-churn dynamic content (timestamps, file contents, counters) in system prompt |

### Check 2 — Dynamic Updates via Messages

Hooks should inject dynamic data as `additionalContext` in their JSON response (becomes a `<system-reminder>` message). They must NOT modify CLAUDE.md or the system prompt.

1. Read each hook script referenced under `hooks` in settings.json.
2. Check output format: does it return JSON with `hookSpecificOutput.additionalContext`?
3. Flag any hook that writes to CLAUDE.md, settings.json, or any file in the static prompt prefix.
4. Check how `currentDate` is injected — via memory.md message context is correct.

| Verdict | Condition |
|---------|-----------|
| PASS | All hooks use additionalContext pattern |
| FAIL | Any hook modifies static prompt files mid-session |

### Check 3 — Tool Set Stability

Tools must be identical at every conversation turn. Any change busts the ENTIRE cache (tools are first in the hierarchy).

1. Count MCP tools, built-in tools, and skill-provided tools.
2. Check if any skills add or remove tools when invoked.
3. Check for deferred/stub tool loading patterns.
4. Flag: conditional tool definitions, dynamic tool descriptions.

| Verdict | Condition |
|---------|-----------|
| PASS | Tool set is fixed at session start |
| WARNING | Some conditional tool loading |
| FAIL | Skills or hooks that add/remove tools mid-conversation |

### Check 4 — No Mid-Session Model Switches

One model per conversation. Subagents are separate conversations and don't break the cache.

1. Check `model` field in settings.json.
2. Check if any skills set `model:` in their frontmatter to a DIFFERENT model than settings.json. Skills with `context: fork` are fine (they're subagents). Skills WITHOUT `context: fork` that set a different model are a problem.
3. Check `ANTHROPIC_DEFAULT_*_MODEL` env vars in settings.

| Verdict | Condition |
|---------|-----------|
| PASS | Single model per conversation, switches only via subagents |
| FAIL | Inline model switching in same conversation thread |

### Check 5 — Dynamic Content Size

Estimate the token cost of dynamic injections per session and per turn.

1. Measure each hook's typical output size (run hook if possible, or estimate from script logic).
2. Check git status injection — flag if it could exceed 10k chars (large repos with many untracked files).
3. Check status line command output size.
4. Calculate cost estimate using pricing from [references/caching-rules.md](references/caching-rules.md).

| Verdict | Condition |
|---------|-----------|
| PASS | < 2k chars injected per turn |
| WARNING | 2k–10k chars per turn (correct pattern, but expensive) |
| FAIL | > 10k chars per turn |

For oversized git status, recommend trimming:
```bash
git branch --show-current
git diff --stat HEAD | tail -5
git status --short | grep "^[^?]" | head -20
```

### Check 6 — Fork Safety

Compaction and subagents must reuse the same system prompt + tools prefix.

1. Check if using Claude Code's built-in compaction (default = correct).
2. Flag any custom compaction or summarization flows.
3. Check skills with `context: fork` — these are handled correctly by Claude Code.

| Verdict | Condition |
|---------|-----------|
| PASS | Using built-in compaction |
| MANUAL CHECK | Custom compaction flows exist |

### Check 7 — Thinking Block Behavior

Extended thinking has special caching implications.

1. Check `alwaysThinkingEnabled` in settings.json.
2. If enabled: note that thinking blocks count as input tokens when cached. This is a cost multiplier on every turn.
3. Flag patterns that frequently alternate between tool-result and non-tool-result messages (non-tool-result messages strip all previous thinking blocks from context, busting that portion of the cache).

| Verdict | Condition |
|---------|-----------|
| PASS | Thinking disabled, or enabled with awareness of cost impact |
| INFO | Thinking enabled — note cost multiplier in report |

## Step 3: Generate Report

Use the template in [assets/report-template.md](assets/report-template.md). Fill in each check's verdict, findings, and the top fix.

Calculate overall score: count PASS as 1, WARNING as 0.5, FAIL/INFO as 0. Report as X/7.

## Step 4: Recommend Next Steps

If any checks fail or warn:
- Provide the single highest-impact fix with exact file path and code change.
- If the user also builds web apps calling the Claude API, mention `/cost-audit` for app-level optimization.

## Success Criteria

- [ ] All 7 checks evaluated with specific findings
- [ ] Report produced in the template format
- [ ] Top fix is actionable (file path + exact change)
- [ ] Dollar cost estimate included for Check 5