| name | context-audit |
| description | Audits a repository's Claude context-injection setup — CLAUDE.md, CONTEXT.md, docs/, .claude/agents/, and the per-project memory directory. Reports bloat, broken links, orphaned docs, security risks, missing rules in subagent prompts, and conflicts between memory and project instructions. Use when the user asks to audit their Claude setup, asks "what's wrong with my CLAUDE.md", wants to know if their agents/memory/docs are configured well, or wants to improve Claude's effectiveness in this repository. |
| allowed-tools | Read, Grep, Glob, Bash |
Context audit
Audit the context that gets injected into every Claude session in the current repository. The goal: identify everything that could be working against the agent — security risks, conflicts, bloat, orphaned docs, broken links, and rules that exist in memory but never reach subagents.
Read-only. Print one markdown report. Do not modify any files. (The skill is granted no edit tools, so this is enforced, not just asked.)
Scope note. This is a whole-setup audit. For a deep, classification-based review of the memory directory on its own (Keep / Move / Refresh / Merge / Drop), defer to /memory-audit. Here, assess memory only where it interacts with the rest of the context: conflicts, subagent gaps, and stale references.
What to read
CLAUDE.md at the repo root, plus any nested CLAUDE.md files (Glob "**/CLAUDE.md").CONTEXT.md at the repo root and anywhere it appears.- Everything under
docs/ (Glob "docs/**/*.md").
- Every agent file under
.claude/agents/ (Glob ".claude/agents/*.md") — note each agent's description, tools frontmatter, and body.
- The repo's
.claude/settings.json and .claude/settings.local.json if present.
- The repo's per-project memory directory (Claude's per-user memory, scoped to this repo). To locate it reliably, list
~/.claude/projects/ and pick the directory whose name is the current repo path with every :, /, and \ replaced by - (e.g. C:\Users\me\proj → C--Users-me-proj — note the double dash where : meets \). Match against the actual listing rather than hand-building the path from a guessed rule.
- The index is
MEMORY.md; sibling .md files are individual memories. Read all of them, including any not listed in MEMORY.md.
- Note each memory's declared
type (user / feedback / project / reference) from its frontmatter.
- If the directory does not exist, note that no per-project memory has been set up and continue.
What to check
Security
- "Don't ask permission" / "just do it" / "no need to confirm" instructions that bypass the permission system. Flag and recommend using
.claude/settings.json allowlists instead.
- Hard-coded credentials, API keys, tokens, or secrets in any context file.
- Instructions that authorise irreversible operations (push, force-push, delete, deploy, post-to-external) without confirmation.
- Overly broad tool access in agent frontmatter (
tools: *, tools: All tools) when the agent's role doesn't justify it.
- Agents that can write/edit and also have network egress (
WebFetch, vendor MCPs) without scoping.
- In
.claude/settings.json / .claude/settings.local.json: a repo-wide defaultMode of bypassPermissions (or broad acceptEdits), an over-broad permission allowlist (e.g. Bash(*), Bash(rm *), Bash(curl *)), or hooks that run unreviewed shell commands. Flag each with the specific risk it creates.
Conflicts
- A memory feedback rule that directly contradicts a rule in CLAUDE.md or an agent prompt.
- Two agents claiming overlapping responsibility without a delegation hint distinguishing them.
- CLAUDE.md and an agent file disagreeing on the same convention (naming, testing, error handling, etc.).
- Memory feedback files whose claims contradict each other.
Missing rules in subagents (the big one for AI-quality)
Subagents do not see the user's memory files — they only see their own system prompt. For each memory feedback item that states a universal coding/style rule (not a personal preference, not agent-behaviour governance), check whether the project's coding agent (whatever the repo names it under .claude/agents/, e.g. coder.md or builder.md) has an equivalent rule in its body. If not, flag as a gap — every fresh subagent invocation will re-violate it.
Distinguish:
- Universal rules worth promoting to the subagent (naming conventions, error-handling requirements, no-unilateral-interface-changes, etc.) — flag the gap.
- Personal style preferences the user has explicitly classified as their own (preferred idioms, formatting choices, etc.) — do not flag.
- Agent-behaviour rules (e.g. "don't run deep git archaeology", "don't pipe tool output through ad-hoc scripts") — memory is the correct home; do not flag.
Bloat
- CLAUDE.md sections over ~20 lines covering a single domain that most sessions don't touch. Recommend moving the detail to
docs/<domain>/ and replacing with a one-line pointer.
- Repeated explanations of the same concept across CLAUDE.md, agent files, and docs.
- CLAUDE.md over ~400 lines total — every session pays the token cost.
- Agent prompts over ~800 lines that include content most invocations won't use.
Broken or missing links
- Files referenced from CLAUDE.md or an agent file that do not exist on disk (
Glob to verify each citation).
- Docs under
docs/ that no CLAUDE.md, agent file, or README references (orphaned).
- Bidirectional back-references between CLAUDE.md and docs ("see CLAUDE.md §X" inside a doc that CLAUDE.md already points to) — pick one direction; the doc should be the source of truth and CLAUDE.md should link to it, not vice versa.
Stale or inaccurate context
- Memory files that cite specific file paths, classes, or symbols. For each citation,
Glob or Grep to verify it still exists. Flag stale ones.
- Doc files that name specific code symbols and look stale (e.g. file mtime over ~90 days — a weak signal, since clones reset mtimes; prefer
git log -1 --format=%cs -- <file> where git is available). Recommend verifying against current state rather than asserting staleness.
Documentation coverage
- Top-level source modules, packages, or services (whatever the repo's layout calls them) without a
README.md — note as a coverage gap, not a hard issue.
- Topic or domain docs under
docs/ that CLAUDE.md does not reference under any documentation-pointers section — the agent won't know to read them.
- A
CLAUDE.md that lacks an explicit "read the relevant docs before planning or coding" directive — flag this; without it, agents skip docs even when pointers exist.
Report format
Print one markdown report to stdout. Use the sections below, ordered roughly by severity (highest first). Within each section, one bullet per finding. Each finding must include: severity tag, the file path (and line number where applicable), a one-line root cause, and a concrete fix.
# Context audit — <repo name> (<absolute path>)
Read: CLAUDE.md, CONTEXT.md, N docs files, M agent files, K memory files.
## Security
- **[risk]** `CLAUDE.md:378` — "Don't ask permission" instruction. Bypasses the permission system. Fix: remove; use `.claude/settings.json` tool allowlist instead.
## Conflicts
- **[conflict]** `memory/feedback_X.md` vs `.claude/agents/<coding-agent>.md:120` — memory says A, agent says B. Decide which is correct and align.
## Missing rules in subagents
- **[gap]** `memory/feedback_<rule>.md` — universal rule, not in `<coding-agent>.md`. Every subagent session starts blind to this. Fix: add a rule body to the agent prompt under Coding guidelines.
## Bloat
- **[bloat]** `CLAUDE.md:320-336` — 17-line section relevant to ~5% of sessions. Fix: move to `docs/<topic>/<detail>.md` and replace with a one-line pointer.
## Broken or missing links
- **[broken]** `CLAUDE.md:30` references `<module>/README.md` — file does not exist.
- **[orphan]** `docs/<topic>/<doc>.md` exists but no CLAUDE.md or agent references it.
## Stale or inaccurate context
- **[stale]** `memory/feedback_Y.md:14` cites `OldSymbolName` — no longer exists; replaced by `new-symbol`.
## Documentation coverage
- **[gap]** `<module>/` has no `README.md` and no `docs/<topic>/` reference in CLAUDE.md.
## Summary
N findings — S security, C conflicts, G subagent gaps, B bloat, L broken/orphan, T stale, D coverage.
Highest priority: <one-line recommendation>.
Output behaviour
- Read-only. Do not edit files. Do not write the report to disk.
- Print the full report to stdout.
- If a section has zero findings, omit it entirely — don't list "Security: none".
- End with a Summary line giving counts and the single highest-priority recommendation.
- Do not propose to "apply the fixes" — the audit is purely diagnostic. The user reads it and decides.
