Audit Rules

Audit rules

Read every rule file and invocable-unit (skill/agent) description that could affect a session, and report two kinds of defect: Contradiction — two sources giving opposite guidance for the same trigger — and Unresolved overlap — two auto-invocable units that could both plausibly fire for the same request, with no stated precedence between them. This is a read-broad, write-narrow tool: it reads everything, but only ever proposes edits to files the user can edit directly — their own personal rule files, and skills/agents they author themselves — never to project-shared, third-party, or managed- policy files, since those are owned by more people than whoever is running this skill, and a single contributor's tool making unreviewed proposals against them would exceed what any one person should decide alone.

When to use

• The user asks to audit, review, or check their rules, CLAUDE.md files, or installed skills/agents for contradictions, conflicts, or overlap.
• The user types /audit-rules.

When not to use

• Auditing auto-memory / feedback files (~/.claude/projects/*/memory/*.md) — those are model-authored and self-correcting differently than a hand-authored rule file; out of scope for this skill.
• Auditing settings.json permission or hook configuration — that's structured config, not prose guidance, and needs different contradiction logic than this skill applies.
• A request to audit only one file, or one skill/agent pair — this always runs the full active set. There is no partial-scope mode; a routine /audit-rules always means a full sweep.

Read scope

Gather all of the following before comparing anything. Missing categories (e.g. no managed-policy file on a non-enterprise machine) are expected — report zero found for that category rather than inventing content.

Rule files

1. Personal: ~/.claude/CLAUDE.md and ~/.claude/rules/*.md — the auditor's only edit target.
2. Project: ./CLAUDE.md, ./.claude/rules/*.md, and the repo's own CLAUDE.local.md if present — resolved from the current working directory's project root. Read-only; never an edit target, even when a finding's other side is personal. A symlinked rule file counts as the file it points to.
3. Managed-policy: check for a CLAUDE.md/rules/*.md colocated with the platform's managed-settings directory — macOS /Library/Application Support/ClaudeCode/, Linux /etc/claude-code/, Windows C:\ProgramData\ClaudeCode\. Most machines have none.
4. For every file found in 1–3, follow its own @path imports (e.g. @ROUTING.md) resolved relative to the importing file's directory, and read those in too — an imported file inherits the scope (personal/project/managed) of whatever imported it.

Invocable units (skills and agents)

5. Start from what this session already surfaced: the skill listing and the Agent tool's agent-type listing already in context give a live, deduplicated set of descriptions — use them as the starting point rather than re-deriving the same list from disk.
6. Cross-check each one's actual frontmatter, since the prose listing can hint at but doesn't authoritatively state disable-model-invocation. Read the source SKILL.md from ~/.claude/skills/*/, ./.claude/skills/*/, and every enabled plugin's skills/**/SKILL.md under ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ — cross-reference ~/.claude/plugins/installed_plugins.json for which plugins are actually enabled, so a cached-but-disabled plugin's skills aren't audited as if live. Do the same for agents: ~/.claude/agents/*.md, ./.claude/agents/*.md, and each enabled plugin's agents/*.md.
7. Classify each unit's overlap-check eligibility: a skill is exempt when its frontmatter sets disable-model-invocation: true. An agent is exempt when its own description states it's delegate-initiated, advisory-only, or otherwise never auto-invoked — or when a routing doc the user maintains (e.g. ROUTING.md) documents it as manual-only. Exemption applies only to the overlap check in the next section — an exempt unit is still compared for Contradictions and for stale references (step 9).

Comparing for defects

8. Contradiction — compare every pair of rule files, and every pair of invocable-unit descriptions, for opposite guidance triggered by the same situation (e.g. one says "always squash before merging," another says "never squash when merging"). Two pieces of guidance about different triggers are not a contradiction even if topically related.
9. Unresolved overlap — among invocable units not exempt per step 7, compare every pair's trigger conditions. If both could plausibly fire for the same request and no rule file states which one should win, flag it — even when neither unit's own guidance is individually wrong. This is a carving defect: verbs should not overlap, and when they do, something needs to state the precedence.
10. Stale references — while reading each unit in step 6, note any reference (by name) to another skill or agent that isn't in the current active set from step 5 — evidence it was renamed or removed. Report this as its own line, distinct from the two headline categories; it survives even for units exempt from the overlap check.

Determining the fix, per finding

11. If the finding's only sensible edit target is a personal rule file, or a skill/agent the user authored, propose the fix as an ordinary Edit tool call — the harness's own permission prompt is the entire confirmation mechanism; do not build a separate one.
12. If the finding is a Contradiction whose only editable side is a project-shared, third-party, or managed-policy file, propose no diff against that file, ever. Report the finding with whichever alternative applies:
    • Third-party skill/agent → note that the actionable lever is tightening the user's own ROUTING.md/CLAUDE.md to disambiguate on their side.
    • Managed-policy file → note that this needs escalation to whoever administers the policy; there is no unilateral fix.
    • If the other side is a personal file, propose the edit there instead — the personal file is always in scope for a diff even when the counterpart isn't.
13. If the finding is an Unresolved overlap between two units the user owns, propose the fix as a carving addition — typically a new row in the user's own ROUTING.md stating which unit takes precedence for the shared trigger. If one side is third-party, the same third-party-note rule from step 12 applies; no edit lands on the third-party unit.

Reporting

14. Report directly in the conversation — no persistent report file or audit log.
15. Keep Contradiction and Unresolved overlap as two visibly separate headed sections so a real disagreement is never conflated with a carving gap where nobody's guidance is actually wrong. Add a brief third section for anything from step 10 (stale references) only when one was found.
16. For each finding, name the two sources, the shared trigger, and the specific disagreement or overlap — then either the proposed Edit call, or the report-only note from step 12/13.

Worked example

Dry run against a constructed six-fixture set — no unit-test seam exists for a pure-prose skill, so this dry run stands in for one, covering every case the read/write-authority split needs to get right:

• personal/CLAUDE.md — "Always squash commits before merging a PR," "Always use spaces for indentation," "Never add a Signed-off-by trailer."
• personal/rules/no-auto-commit.md — "Never auto-commit; only commit when the user explicitly asks."
• project/CLAUDE.md — "Never squash commits when merging a PR," "Always use tabs for indentation."
• managed-policy/CLAUDE.md — "All commits made by an agent must include a Signed-off-by trailer."
• Third-party skill auto-commit-helper — "Fires after every file edit to automatically commit the change... without being asked."
• Two user-authored auto-invocable skills, deploy-helper ("Fires when CI reports a flaky test...") and diagnose-ci-failure ("Fires when CI reports a test failure...").
• A third user-authored skill, legacy-deploy, disable-model-invocation: true, also triggered by a flaky test, whose body hands off to a skill named rollback-helper — which does not exist anywhere in the active set.

Running steps 8–16 against this set produced:

Contradiction

1. personal/CLAUDE.md ("always squash") vs. project/CLAUDE.md ("never squash"), same trigger (merging a PR). Edit target: personal/CLAUDE.md only — proposed narrowing it to "squash by default, but follow the project's own convention when one is stated," since the project file is never a target.
2. personal/CLAUDE.md ("always spaces") vs. project/CLAUDE.md ("always tabs"), same trigger (indentation). Same treatment: edit proposed on the personal file only, to defer to a stated project convention.
3. personal/rules/no-auto-commit.md vs. third-party auto-commit-helper. Neither side is a valid edit target on the third-party skill, so: no diff proposed against it; reported with a note that the actionable fix is tightening personal/CLAUDE.md (or a ROUTING.md-style rule) to explicitly rule out that skill firing.
4. personal/CLAUDE.md ("never Signed-off-by") vs. managed-policy/CLAUDE.md ("always Signed-off-by"). No edit target exists on the managed file; reported with a note to escalate to the policy's administrator.

Unresolved overlap

5. deploy-helper and diagnose-ci-failure — both auto-invocable, both could fire for "CI reports a flaky test" (a flaky test is a test failure), and no rule file states which one should run first. Both are user-authored, so the proposed fix is a new ROUTING.md row assigning the flaky-test trigger to one of them explicitly. legacy-deploy shares the same trigger but is exempt from this check — disable-model-invocation: true means it never competes for an auto-fire decision.

Other issues found

6. legacy-deploy references rollback-helper by name, which is not in the active skill/agent set — flagged as a stale reference (most likely renamed or removed) even though legacy-deploy was exempt from the overlap check above.

Two contradictions (1–2) got direct Edit proposals against the personal file; two (3–4) got report-only findings with the alternative each one actually has; the overlap finding (5) got an Edit proposal against ROUTING.md; and the stale reference (6) was called out on its own even though the unit carrying it was exempt from half the checks. That's the full split the read-broad, write-narrow design is meant to produce.