Audit

---
description: "Audit the Claude Code instruction/memory layer covering CLAUDE.md, a root AGENTS.md, CLAUDE.local.md, .claude/rules/, and auto-memory against a codified checklist derived from official Claude Code documentation. Use when: 'audit CLAUDE.md', 'audit AGENTS.md', 'memory health', 'audit rules', 'is my CLAUDE.md too long', 'prune instructions', after CLAUDE.md/rules changes or a Claude Code upgrade; actions: audit (default), fix, update, report."
argument-hint: "[audit|fix|update|report]"
user-invocable: true
disable-model-invocation: false
shell: bash
metadata:
  workflow-stage: anytime
  summary: Audit CLAUDE.md, a root AGENTS.md, rules, and auto-memory against the official-docs checklist
---

**Arguments.** `[audit|fix|update|report]`. Default: audit

## Pre-computed context

The deterministic spine, one invocation, header then findings. The root-file line count has
`@` imports expanded, since imported files load at launch; the token figure is bytes / 4 over the
whole always-loaded set and is an estimate, not a measurement.

!`bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/audit-spine.sh" 2>/dev/null || echo "Deterministic spine: unavailable (audit-spine.sh failed to run; run the per-check scripts by hand)"`

# Memory Health

Deterministic health check for the Claude Code instruction/memory layer. Audits files YOU write that
shape Claude's behavior, not the entire context window (MCP tools, agents, and skills are covered by
the `audit` and `audit-automation-gaps` skills in the `harness-config` plugin).

## Scope

| Entity | Location | Load model this audit uses | Audited here |
|--------|----------|--------|-------------|
| Project instructions | `CLAUDE.md` | Every session, full | Yes |
| Project instructions in `AGENTS.md` | `AGENTS.md` and `.claude/AGENTS.md` at the root | Audited only where discovery reports Claude Code reads it; `scripts/lib/agents-md.sh` holds the condition and its record | Yes, as the project instructions (the C-checks) |
| Local overrides | `CLAUDE.local.md` | Every session, full | Yes |
| Rules | `.claude/rules/**/*.md` | Every session (unconditional) or on-demand (path-scoped) | Yes |
| **User instructions** | `${CLAUDE_CONFIG_DIR:-~/.claude}/CLAUDE.md` | Every session, full, in **every** project | Yes |
| **User rules** | `${CLAUDE_CONFIG_DIR:-~/.claude}/rules/**/*.md` | Same as project rules, in every project | Yes |
| Auto-memory | `~/.claude/projects/<project>/memory/` | The M1 budget: first 200 lines / 25KB of MEMORY.md | Yes |
| Nested `AGENTS.md` | `**/AGENTS.md` below the root | Reachable unless a `CLAUDE.md`-family file on its path displaces it without importing or symlinking it (N1) | Reachability only (N1); content is not audited |
| Settings, hooks, MCP, agents, skills | Various | Various | No. Use `harness-config`'s `audit` / `audit-automation-gaps` |

The load-model column is this audit's working model, not a restatement of the docs; each check in
[reference/criteria.md](reference/criteria.md) carries the pointer it rests on.

- **Pointer**: for how each file loads, see
  [How CLAUDE.md files load](https://code.claude.com/docs/en/memory#how-claude-md-files-load),
  [Organize rules with `.claude/rules/`](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/),
  [When Claude Code reads AGENTS.md](https://code.claude.com/docs/en/memory#when-claude-code-reads-agents-md)
  and auto memory's [How it works](https://code.claude.com/docs/en/memory#how-it-works).
- **As of**: 2026-10-01
- **Recheck trigger**: a Claude Code release note or a change to one of those sections alters which
  files load at session start, on demand, or within the auto-memory limits.

Auto memory's effective enabled/disabled state must be resolved before auditing it, not assumed
from a single scope: [`${CLAUDE_PLUGIN_ROOT}/skills/stateless/context/status.md`](../stateless/context/status.md),
"Resolve the effective state".

The two user-scope rows are in scope because they load in every session regardless of where it starts.
Discovery tags every file with its scope so project-scoped criteria (C9) skip personal files rather
than reporting a repo-scoped finding against one. **C6 Consistency** owns instruction-content
conflicts across that discover-instruction-surfaces population, including **user↔project** pairs.
`harness-config:audit-instructions` I15 owns memory-layer precedence adjudication and every conflict
pair with an anchor outside that population (nested `CLAUDE.md`, auto-memory, settings, hooks,
skills, agents, output styles).

## Scope boundary (route out)

This audit owns instruction-layer **health**: structure, size, placement, and index integrity of
the memory files against the codified checklist. Whether an instruction's *content* is still
needed by the current model is the model-era fit question, owned by the `harness-config` plugin's
`audit-instructions` skill. Prior-model workarounds, over-prescriptive scaffolding, bare
prohibitions without rationale, reasoning-echo directives, think-carefully steers, vague design
steers, settled-answers lines on analysis surfaces, and stale example scaffolding fall there.
Guidance a long-run file *lacks* (when to stop and when to keep going, a finish line, a task file,
the end-of-run report shape) is that plugin's `audit-prompting-postures`. When
that plugin is installed, route such findings to `/harness-config:audit-instructions` or
`/harness-config:audit-prompting-postures`, invoked via the Skill tool, rather than
judging them against this checklist; when it is not installed, keep each as a criteria-free
observation in this audit's report (never a checklist finding, never silently dropped) so the
operator can weigh it against current official prompting guidance.

## Argument parsing

| Argument | Action |
|----------|--------|
| *(none)* or `audit` | Run the full codified checklist against all instruction/memory files |
| `update` | Research current official docs, refresh criteria and official-guidance reference files |
| `fix` | Apply fixes for audit findings (requires prior audit, asks for approval) |
| `report` | Show last audit results without re-running |

## Determinism contract

The checklist at [reference/criteria.md](reference/criteria.md) is codified, not a subjective rubric.
Its **deterministic spine** (C1 line budget with `@` imports expanded, M1 index size, the
script-backed M2 index integrity, RD1 orphan-rule, and N1 nested-`AGENTS.md` reachability checks,
plus the provenance classification each finding carries) yields byte-identical findings on the same
repo state; its **judgment tier**
(C2-C9, R1-R4, M3-M4) applies fixed criteria with model reading, so findings vary in wording though
not in criteria. Label those "judgment candidate" in the report. Criteria derive from official Claude
Code documentation: [reference/official-guidance.md](reference/official-guidance.md) holds, per
topic, the audit's decision and a pointer to the docs section behind it, never the docs' text.
Refresh both via the `update` action.

## Script paths

The `context/` and `reference/` files write each bundled script as `<skill-dir>/scripts/<name>.sh`,
where `<skill-dir>` is this skill's directory: `${CLAUDE_SKILL_DIR}`. Put that path in place of the
placeholder before running a command. We never put a `${…}` token in those files: we do not rely on
one being substituted in a file read through the Read tool, or on the Bash tool's environment
carrying `CLAUDE_PLUGIN_ROOT`.

- **Pointer**: for where each `${…}` reference resolves, see
  [Where each variable resolves](https://code.claude.com/docs/en/plugins-reference#where-each-variable-resolves)
  and [Available string substitutions](https://code.claude.com/docs/en/skills#available-string-substitutions).
- **As of**: 2026-09-27
- **Recheck trigger**: either table adds supporting files to where a `${…}` reference resolves.

## Audit mode (default)

Load [context/audit.md](context/audit.md) for the full audit workflow.

## Update mode

Load [context/update.md](context/update.md) for the research-and-refresh workflow.

## Fix mode

Load [context/fix.md](context/fix.md) for the fix-with-approval workflow.

## Derive the report location before writing or reading

Every action that touches the report uses **one** path, resolved here: `audit` writes it, `report`
serves it, `fix` acts on it.

```
${CLAUDE_PLUGIN_DATA}/audit/<state-key>/last-audit.md
```

**Derive `<state-key>` by running this, in the project being audited:**

```bash
bash "${CLAUDE_PLUGIN_ROOT}/lib/state-key.sh"
```

It prints `<repo-identity>/<worktree-discriminator>`, the scheme `harness-config:audit-pass` defines
and `audit-prompting-postures` uses. Run it and use its output as the key. Pass `--explain` when
the report should say which rung produced its key.

**Why the key exists.** We treat `${CLAUDE_PLUGIN_DATA}` as one directory per plugin per machine,
with no project, checkout, worktree, or session segment. A fixed `audit/last-audit.md` is therefore
**one file per machine**.

- **Pointer**: for the plugin data directory, see
  [Environment variables](https://code.claude.com/docs/en/plugins-reference#environment-variables).
- **As of**: 2026-10-01
- **Recheck trigger**: that section adds a project, worktree, or session segment to the data
  directory's path.

Losing reports is the smaller half; the larger half is the read. `report` mode would serve whatever
that file currently holds and `fix` mode would act on it, so on a machine with two repositories,
project B can be shown project A's
findings and offered edits derived from another repository's memory layer. That is a wrong answer
served, not merely an artifact lost, which is why an append-only history does not close it and the
*path* has to carry project identity.

**Never serve a report you cannot attribute.** If nothing exists at the derived path, say that no
audit has been run **for this project** and suggest running one. Do not fall back to an unkeyed
location.

**A `health/` directory or an unkeyed `audit/last-audit.md` under the plugin data directory is
unattributable.** Either is a machine-global file with no project segment, so nothing records which
repository produced it. It cannot be adopted into a project's key without inventing that
attribution, and inventing it is exactly the defect the key exists to remove. Where such a file is
present, name its path to the user as a leftover they may delete, and run the audit rather than
reading it.

**Audit output is contributor-local by design.** Reports audit a contributor's personal auto-memory
(`~/.claude/projects/<project>/memory/`), which varies per team member, so they persist in the
plugin's own data directory, never in the consuming repo.

**A rolling latest is a separate decision from keying, and this skill keeps one on purpose.**
`last-audit.md` is replaced by the next run *of the same project*; the report is a working artifact,
not a trend series. That is only safe because the key makes "the same project" mean something. See
[`docs/conventions/plugin-data-report-keying/`](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-data-report-keying/README.md)
for when a writer owes a per-run history instead.

## Report mode

Read the report at the derived path above and present it. When it is absent, apply the
never-serve-what-you-cannot-attribute rule above rather than reaching for another file.

## Consumer-convention extension seam

This skill ships the doc-derived checklist only. A consuming repo that layers its own
instruction-hygiene conventions (e.g. a team-shared-first codification policy, an always-loaded
context-budget policy, or an exemption from the 200-line CLAUDE.md target for repos that deliberately
run a large rules layer) declares them in its own `CLAUDE.md` / `.claude/rules/`. Read those files
during the audit and apply any additional criteria or documented exemptions they define, reporting
such findings under a `REPO` check-ID so they stay distinct from the doc-derived checks.

## Complementary workflows

If the `claude-md-management` plugin from Anthropic's `claude-plugins-official` marketplace is
installed, its `claude-md-improver` skill audits CLAUDE.md structure and content quality,
complementary to this health check. Run this audit first to identify issues. Its
`revise-claude-md` command captures session learnings after a fix pass. Absent that plugin, the
fix mode here stands on its own.