/context-audit

name: context-audit
description: '[Adam''s Skills] 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

1. **`CLAUDE.md`** at the repo root, plus any nested `CLAUDE.md` files (`Glob "**/CLAUDE.md"`). 2. **`CONTEXT.md`** at the repo root and anywhere it appears. 3. Everything under **`docs/`** (`Glob "docs/**/*.md"`). 4. Every agent file under **`.claude/agents/`** (`Glob ".claude/agents/*.md"`) — note each agent's `description`, `tools` frontmatter, and body. 5. The repo's **`.claude/settings.json`** and **`.claude/settings.local.json`** if present. 6. 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.

Legacy prompting patterns

Instructions age badly. Each Claude generation ships with its own prompting notes, and some of that advice **inverts** — a line that fixed a real problem two model releases ago now causes the opposite one. Nobody goes back and deletes those lines, so a mature `CLAUDE.md` accumulates them, and they are invisible precisely because they used to work.

Flag each of the following, quoting the line and saying what it now causes:

• **Mandated self-verification** — "double-check your answer", "always re-verify before

responding", "include a final verification step for any non-trivial task", "use a subagent to verify your work". Current models self-check; the instruction compounds with that and spends extra passes on work that was already correct. Fix: delete rather than reword.

• **Anti-laziness and thoroughness prompting** — "always be thorough", "if in doubt, use

\<tool\>", "default to using \<tool\>", "read as many files as you can before answering". Written when tools under-triggered. They now over-trigger. Fix: narrow to when the to