---
name: audit-context-files
description: "Audit the agent context files (CLAUDE.md, AGENTS.md) at the project root and the user's home directory: cut what does not change a decision, disambiguate what two readers would read two ways, resolve conflicts between the files and against installed skills, and move enforceable rules down to a test, lint, CI check, or hook. Use for /audit-context-files, \"my CLAUDE.md is bloated\", \"clean up AGENTS.md\", or after a context file has grown for a few months."
disable-model-invocation: true
---

# Audit context files

A context file is loaded into every turn, so a line in it that changes nothing is paid for on every request forever, and a line that reads two ways is worse than no line. This audit is idempotent: run it whenever a file has grown, not once at setup.

Scopes, both audited unless the user names one:

- **Project.** `CLAUDE.md` or `AGENTS.md` in the repo root, plus nested ones the host loads.
- **Global.** The same names under the user's home config directory.

Never create the file the repo does not have. If `CLAUDE.md` exists, edit it. If only `AGENTS.md` exists, edit that. If neither exists, ask which to create; do not pick.

## 1. Inventory

Read every file in scope, whole. Split each into individual rules, one claim per rule, and keep the source file and line for each. Number them; the user will refer to them by number.

Also gather what enforcement already exists, so the audit does not propose something the repo has: test commands, lint config, `.githooks/` and `.pre-commit-config.yaml`, `.github/workflows/`, and the host's hook config (Claude Code: `settings.json` hooks).

## 2. Judge each rule

Four verdicts, one per rule. Apply them in this order and stop at the first that fits.

**Dead.** The rule names a path, command, skill, or tool that does not exist. Verify rather than assume: run the command, stat the path, list the host's skill directories. A rule pointing at something absent has never fired, whatever anyone believed. This is the most common finding and the one nobody catches by rereading.

**Enforceable.** A mechanism could hold this rule instead of prose. Route it to the strongest rung it supports per the **encode-lessons-in-structure** principle skill. A rule the agent has broken repeatedly is enforceable by definition: it already failed as prose.

**Ambiguous.** Two readers, two readings. Usually one overloaded word doing the damage. Rewrite it per the **define-the-terms** principle skill: name the concept, and add the term to `CONTEXT.md` when the repo has one.

**Earns its place.** It changes a decision the agent would otherwise get wrong, and you can say which. If you cannot name the failure it prevents, it is not this verdict. Ubiquitous advice ("write clean code", "be concise", "follow best practices") is never this verdict.

## 3. Find the conflicts

Three directions, all of them real:

- **File against file.** Global against project, and `CLAUDE.md` against `AGENTS.md` when both exist. Two files claiming the same authority drift, and the loser is whichever the host happens to load second.
- **File against installed skills.** A rule that contradicts a skill the user has installed. Report which one wins in which situation and let the user decide. Do not rewrite a user's file to agree with a skill set. An opt-in mode like ram-mode governs only the turns it runs in, so a global rule that differs is not automatically wrong.
- **File against itself.** A file long enough to audit usually contradicts itself somewhere, most often where a later section was added without reading the earlier one.

## 4. Report before writing

One table, ordered by verdict, with the rule number, the file, the verdict, and the proposed action in a few words. Then the conflicts as their own short list, each with your read on which should win and why.

Wait for the user to pick. Never apply an audit unasked. This is someone's standing instructions to every agent they run, and a silent rewrite of it is the worst possible outcome of a skill meant to make instructions trustworthy.

## 5. Apply what was approved

- Dead rules: delete, or fix the pointer when the target moved rather than vanished.
- Enforceable rules: build the mechanism, then delete the prose. A rung named and not built leaves the file longer than before, since the prose stays and a promise joins it. When the mechanism cannot be built now, the **capture** skill parks it and the prose stays until it can.
- Ambiguous rules: rewrite, and add terms to the glossary.
- Conflicts: apply the user's call.

Apply the **unslop** skill to every line you touch. Keep the user's voice; this is their file, not yours.

## 6. Report

What was cut and the line count before and after. What became a mechanism, with the path to it. What was captured. What conflicts remain open because the user has not called them yet.