From context-audit
Use when user asks to audit Claude Code context hygiene, optimize token usage, review CLAUDE.md for bloat, check settings.json for context-saving flags, or flag expensive MCP servers and oversized skills. Produces a Context Health Score (1-100), per-turn overhead estimate, and ranked action items.
How this skill is triggered — by the user, by Claude, or both
Slash command
/context-audit:context-auditThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Audits the user's Claude Code environment for token waste and context bloat. Reports a **Context Health Score (1-100)**, a concrete **per-turn overhead estimate**, and ranked action items. Offers to walk findings one-by-one, applying safe fixes to `CLAUDE.md` and `settings.json`.
Audits the user's Claude Code environment for token waste and context bloat. Reports a Context Health Score (1-100), a concrete per-turn overhead estimate, and ranked action items. Offers to walk findings one-by-one, applying safe fixes to CLAUDE.md and settings.json.
Schema changes between versions. Never propose a settings key from memory.
# Probe schema via bogus key edit (error returns full schema)
# OR read actual file to see what keys ARE used:
cat ~/.claude/settings.json
claude config list 2>/dev/null
Fail-closed rules (#16):
properties → DO NOT propose it. No guesses.claude CLI is missing → skip MCP-list-dependent checks, fall back to reading settings.json + .mcp.json directly.Before running against user, dogfood on skill's own files:
wc -l ~/.claude/skills/context-audit/SKILL.md — if >400, skill is hypocritical.Use these for all estimates — never invent numbers.
# Approx tokens = chars / 4 (English); safer = chars / 3.5
wc -c <file> # file char count
grep -c '^' <file> # line count
# System prompt inflation of a CLAUDE.md block: chars/4
# MCP tool schema: varies 2-10k tok; measure by listing tools + estimating each
Report in both tokens and bytes so the user can verify.
Locate all CLAUDE.md files:
~/.claude/CLAUDE.md (global/user)$CWD/CLAUDE.md (project)$CWD/**/CLAUDE.md (nested)Measure actual tokens for each (chars/4). Report real numbers.
Hierarchy dedup (#1): compute overlap between global + project + nested:
Per-file flags:
| Issue | Example | Detection |
|---|---|---|
| Default-behavior rules | "Write clean code", "Be concise", "Don't hallucinate" | Pattern list |
| Contradictions | "Always use X" + "Prefer Y over X" | Scan for antonyms |
| Redundancy | Same rule in multiple sections | Line hash |
| Verbose reference blocks | API schemas, long examples | Block >30 lines |
| Stale notes | Dated TODOs, "temporary" rules >30d old | Date regex |
| Narrative | "The reason we do this is..." | Prose paragraphs |
Progressive disclosure: block >30 lines → extract to docs/<topic>.md + 1-line pointer.
Read all three layers:
~/.claude/settings.json (user)$CWD/.claude/settings.json (project)$CWD/.claude/settings.local.json (local, git-ignored)~/.claude/managed-settings.json (policy, read-only)Effective-merge view (#7): show the user the merged config, not raw files. Merge order (last wins for most): managed < user < project < local < CLI args. For permissions.* arrays, items union. Display:
effective autoCompactWindow = 500000 [from: user]
effective permissions.deny = [...] [from: user ∪ project]
Unused permissions.allow entries (#8): grep transcripts for each allow rule's pattern. If rule never matched a tool call in the last N sessions → flag "unused allow — remove to shrink prompt".
# Example: check usage of Bash(ffmpeg:*)
grep -rh 'ffmpeg' ~/.claude/projects/ | wc -l
Known-stable context-hygiene areas (schema-verified only):
permissions.deny — block heavy dirs. Safe.permissions.allow — trim unused, add frequent safe reads.autoCompactWindow (integer chars). Verify this session before proposing.cleanupPeriodDays — transcript retention.skillListingBudgetFraction / skillListingMaxDescChars — tune skill listing cost.Never propose: autoCompactPercentageOverride, bashMaxOutputLength, any key absent from current schema.
Procedure:
Run claude mcp list. Classify each:
| Category | Config | Disable | Cost |
|---|---|---|---|
Local plugin MCP (plugin:foo:bar) | settings.json.enabledPlugins | Flip to false | Schema when connected |
| User stdio/http MCP | mcpServers / .mcp.json | claude mcp remove <name> | Schema when connected |
| claude.ai built-in connector | Account-level (web) | claude.ai → Settings → Connectors | Near-zero if unauthed |
Flag:
✗ Failed to connect).Usage check:
grep -rh '"name":"mcp__plugin_<server>__' ~/.claude/projects/ | wc -l
Zero hits across many sessions → safe to disable.
Unauthed built-in connectors: near-zero cost. Don't spend user attention on these.
CLI replacements for connected MCPs:
ghglabScan ~/.claude/skills/ and ~/.claude/plugins/**/skills/SKILL.md.
Measure:
wc -l / wc -w per file.Flag:
Scan ~/.claude/agents/*.md and $CWD/.claude/agents/*.md.
"subagent_type":"<name>").For each hook in settings.json.hooks:
bash -c "<command>" → wc -c.UserPromptSubmit → multiply by expected turns/session (default 50).Safety: never dry-run hooks that write, post, or mutate state. Static-analyze the command first (check for git commit, curl POST, rm, >, >>). Skip if ambiguous.
time bash -c "$(jq -r .statusLine.command ~/.claude/settings.json 2>/dev/null)"
Flag if >200ms — causes UI lag. Suggest caching or simplification.
Grep transcripts for compact events:
grep -rh 'compact' ~/.claude/projects/*/*.jsonl | grep -ic 'auto.*compact\|compact.*event' | head
# or look for compaction markers in transcript schema
Report: compacts per session over last 30 days. High rate (>1/session average) = context under pressure → prioritize token-saving findings.
# Context Health Report
Score: XX/100
Per-turn overhead: ~XXXX tokens [context floor before any work]
Per-session floor: ~XXXXXX tokens [at N turns/session]
Breakdown:
- CLAUDE.md: XX/25 [findings: N, tokens: XXXX]
- Settings: XX/25 [findings: N]
- Resources: XX/25 [findings: N, MCP tokens: XXXX, skill descriptions: XXXX]
- Hooks: XX/25 [findings: N, per-turn hook cost: XXXX]
## Top Findings (ranked by est. tokens saved)
1. [CLAUDE.md] <issue> — saves ~XXX tok/turn
Location: <file>:<line>
Fix: <one-line action>
...
## Walkthrough
(proceeds one-by-one per section 6)
Sum the concrete costs:
overhead =
tokens(all loaded CLAUDE.md)
+ tokens(skill listing: sum of descriptions + frontmatter)
+ tokens(connected MCP tool schemas)
+ tokens(UserPromptSubmit hook output × 1 per turn)
+ tokens(SessionStart hook output ÷ turns-per-session)
Report actual numbers, not estimates. Use chars/4. This is the context floor the user pays before any prompt/response.
Start 100, subtract:
autoCompactWindow missing on large ctx: -5.Clamp [1, 100].
[N/TOTAL] [AUTO|DECIDE|MANUAL] <title>
Problem: <one line>
Cost: ~XXX tok/turn
Options: 1) <action> 2) <action> 3) skip 4) stop
Apply immediately. Never batch. Never hide items. Every finding in report appears in walkthrough.
Tags:
[AUTO] — safe, reversible, one-shot.[DECIDE] — user picks action.[MANUAL] — user applies printed diff.Alt entry:
y → apply all [AUTO] without prompting, still walk [DECIDE]/[MANUAL].N → stop, print remaining as checklist.Auto-fixable scope (schema-verified only):
permissions.deny for heavy dirs.permissions.allow for clearly-wanted Bash cmds.enabledPlugins.<id> to false after explicit confirm.Write procedure:
cp file file.bak.$(date +%s).Never auto: delete/move CLAUDE.md blocks, remove user MCPs, modify skills, touch managed settings.
Flag in user request: "audit all my projects" / "across all projects".
~/.claude/projects/*/ dirs.| Step | Tool | Target |
|---|---|---|
| Find CLAUDE.md | Glob | **/CLAUDE.md |
| Measure file tokens | Bash | wc -c file | awk '{print int($1/4)}' |
| Read settings | Read | ~/.claude/settings.json |
| Probe schema | Edit (bogus key) | error returns schema |
| Effective merge | Bash | jq -s add user.json project.json local.json |
| List MCPs | Bash | claude mcp list |
| Check MCP usage | Bash | grep -rh '"name":"mcp__plugin_<name>__' ~/.claude/projects/ | wc -l |
| Measure skills | Bash | wc -l ~/.claude/skills/*/SKILL.md |
| Detect CSO-bug desc | Grep | description contains "dispatches |
| Custom agents | Glob | ~/.claude/agents/*.md |
| Time statusline | Bash | time bash -c '<cmd>' |
| Compact rate | Bash | grep transcripts for compact events |
| Backup | Bash | cp X X.bak.$(date +%s) |
| Patch JSON | Edit | preserve format, verified keys only |
| Disable plugin | Edit | enabledPlugins.<id>: false |
| Remove local MCP | Bash | claude mcp remove <name> |
settings.local.json — local overrides.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub cshark-hub/context-audit --plugin context-audit