Audit

Pre-computed context

Claude Code version: !claude --version 2>/dev/null || echo "unknown"

Purpose

Periodic audit of Claude Code configuration files against current official documentation and the consuming project's own conventions. Answers: "Are our settings correct, secure, complete, and up to date?"

Adapting to your environment (graceful degrade)

This skill is self-contained. Where a phase names an adjacent capability, such as a Claude Code issue-tracking skill or an environment-bootstrap checker, treat it as optional: if your setup provides an equivalent skill or tool, use it; otherwise follow the inline guidance here, which stands on its own. Project-specific conventions (required permission patterns beyond the baseline, documented reasons for disabled servers, launcher-script wrappers) come from the consuming repo's own CLAUDE.md and .claude/rules/. Read them when present; this skill does not assume them.

Two adjacent skills cover neighboring questions: the sibling audit-automation-gaps skill asks whether the configured automation SET is the right set (landscape gaps); the audit skill in the claude-memory plugin audits the instruction layer (CLAUDE.md / rules / auto-memory). This skill asks whether the configuration FILES are correct against upstream truth.

Arguments

Parse $ARGUMENTS for:

• --fix: Apply corrections automatically (with user confirmation per fix). Without this flag, report-only mode
• Scope filter: Limit audit to a single category. If omitted, run all categories
  • permissions: deny/ask/allow rules, security gaps
  • mcp: MCP server definitions, commands, env vars, connectivity
  • hooks: hook scripts exist, timeouts, matchers
  • plugins: enabled/disabled status, marketplace availability
  • issues: recheck known GitHub issues only
  • all: run everything (default)

Config Files

Reading settings.local.json safely

Even when no deny rule blocks it, treat settings.local.json as secret-bearing: run bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/check-structure.sh" for key counts and validity, never dump its contents. Supplemental jq recipes: context/procedures.md "Reading settings.local.json safely".

The counts are not guaranteed. Where the project's configuration blocks the read, whether a sandbox denyRead merged from the baseline Read deny or filesystem permissions, the script reports Readable: no and a not inspectable note instead of failing. Record the file as not inspectable, carry that into the report, and do not reach for another reader to get the counts anyway.

Track progress

For any full audit run (Phases 1-5), keep a phase checklist and tick each phase as it completes, either in-response or by copying ${CLAUDE_PLUGIN_ROOT}/skills/audit/templates/checklist.md into wherever the consuming repo keeps working task notes. Phase 5 is SKIPPED in default report-only mode.

Phase 1: Load & Parse

Read all config files and validate basic structure.

Record the installed Claude Code version (claude --version). Phase 3.2 compares issue-fix versions against it. Then run bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/check-structure.sh" before filling the 1.2 Structure inventory table.

1.0 Hook inventory

Run bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/check-hook-coverage.sh" and keep its output for the rest of the run. It enumerates settings-declared hooks and the hooks shipped by every enabled plugin, resolved through the installed-plugin registry so no version-directory guessing is involved, plus the levers (disableAllHooks, allowManagedHooksOnly, strictPluginOnlyCustomization) that switch hooks off wholesale.

Two categories depend on it:

• Category D writes rules for ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} placeholders, which only ever appear in a plugin-provided hook.
• Category B's third narrowing demotes a missing baseline deny to info when a live PreToolUse hook already blocks the family. That narrowing is only takeable against a real inventory.

Read the exit code, not just the table. 0 means the inventory is complete. 1 means it is partial, because some enabled plugin did not resolve or a hook config did not parse, and the "Not enumerated" block names which. For anything a partial inventory could not see, keep the conditional posture in required-permissions.md "Fail open where the inventory is incomplete". 2 is fatal (no readable settings scope, or jq missing); treat it as no inventory at all rather than as an empty one.

The script never runs a hook and never decides whether a hook covers a family. That judgment stays with Category B, against the three preconditions in "Narrowing the baseline".

1.1 JSON validity

Valid JSON: no blocks further analysis.

1.2 Structure inventory

Map script output into the summary table:

1.3 Baseline snapshot

Record script counts for before/after comparison if --fix is used:

• Permission rule counts (deny/ask/allow)
• MCP server count (active vs disabled)
• Hook count by event type
• Plugin count (enabled vs disabled)

Phase 2: Validate

Load the audit checklist: audit-checklist.md

Run each category's checks. Record findings with severity ratings.

Nine categories, with names plus the question each answers below; full per-check criteria in context/validation-categories.md (read it when running Phase 2).

• A, Schema & Structure: $schema present, no unknown keys, mcpServers not in settings.local.json
• B, Permissions: baseline deny/ask patterns present (list in reference/required-permissions.md, plus any additional patterns the consuming repo's own rules declare as required), deny-rules-in-settings.json-only (bug #8961)
• C, MCP Servers: commands resolve, ${VAR} syntax, disabledMcpjsonServers match, documented disable reasons
• D, Hooks: paths resolve + readable, timeout in seconds and sane, valid matchers, quoted path placeholders in shell form, exec-form command resolvable on Windows, no duplicates, valid events
• E, Plugins: static checks (marketplace membership) + live upstream drift detection (scripts/check-plugin-drift.sh, covering ORPHAN/NEW/RENAME modes, auto-fix policy table in the context file)
• F, Environment Variables: documented/justified vars, secrets in settings.local.json only, forward-slash paths
• G, Skill-listing budget: overflow check by a route this run can actually take (/doctor interactively, --debug headless), the budget constant it was measured against, and trim levers scoped to the roster's composition (skillOverrides reaches project and user skills; plugin skills are managed through /plugin)
• H, Model and effort settings: effortLevel, fallbackModel, availableModels, enforceAvailableModels, values the harness accepts into the file but does not apply as written
• I, Deep-link registration: disableDeepLinkRegistration, the one documented value that takes effect, and a visible attempt at an enforcement requirement lodged in a scope that cannot enforce it

Phase 3: Research & Recheck

External verification against current documentation.

Read every page in this phase verbatim, not through a summarizer. These pages are long, with settings and env-vars running to hundreds of KB, and a summarizing fetch truncates, then reports the rows past the cutoff as absent. So for each fetch below, curl https://code.claude.com/docs/en/<page>.md to a file and grep the file, per the fetch route. A truncated read supports NO finding. Say so and move on, in either direction: neither "the key is gone" nor "the key is unchanged" is reportable from a read that may have been cut.

3.1 Official docs check

Fetch code.claude.com/docs/en/settings and compare:

• Are there new settings the project should consider adopting?
• Have any settings in use been deprecated or renamed?
• Has permission rule syntax changed?

3.2 GitHub issue recheck

For each issue in known-issues.md, check live status (gh issue view <number> -R anthropics/claude-code --json state,title, or the consuming repo's own Claude Code issue-tracking skill if it has one). For any issue whose upstream fix has shipped at or below the installed Claude Code version, confirm the settings-specific workaround is still needed and recommend retiring it if not.

3.3 Model configuration verification

MANDATORY for any category H finding: fetch code.claude.com/docs/en/model-config and confirm the behavior the finding rests on. Do NOT report a category H finding from this checklist's wording alone: the accepted effortLevel values, the fallback-chain cap, and the allowlist wildcard rule are all upstream-owned and move with the harness.

3.4 Permission syntax verification

Fetch code.claude.com/docs/en/permissions and verify:

• The project's permission patterns match current documented syntax
• No new permission types added (e.g., new tool types)
• Wildcard behavior unchanged

Phase 4: Report

Present all findings as a severity-rated GFM table:

Severity guide

Interactive checkpoint

If --fix flag is set: Present findings table, then ask user which items to fix. Do NOT proceed without their response.

If report-only (no --fix): Present findings table and summary. Note which items could be auto-fixed.

"Which findings would you like me to fix? Reply with numbers, 'all', or 'skip'."

Phase 5: Fix (only with --fix flag)

For each user-approved fix:

1. Make the edit
2. Validate JSON with jq after each edit
3. Report what changed

After all fixes:

• Present before/after comparison (rule counts, server counts, etc.)
• Verify all config files are still valid JSON

Fixes the skill can apply

Auto-fixable (add $schema, move deny rules from local to project, plugin orphan-removal + new-as-false via scripts/fix-plugin-drift.sh --yes) vs judgment-required (adding a baseline deny rule, new settings from docs, permission restructure, MCP config, orphan-true removal, heuristic rename), with the full matrix in context/procedures.md "Phase 5, fixes the skill can apply". Adding and moving a deny rule are graded apart on purpose: moving one is #8961 placement, while adding one has to be checked against hook coverage that may already hold and against an ask-gate the addition would suppress.

Required permission patterns

Category B (Phase 2) checks that the project's .claude/settings.json contains a security baseline of deny/ask patterns: secret-file Read denies, destructive-git Bash denies, and a git push ask-gate. The concrete list is in reference/required-permissions.md. Projects with a stricter posture declare their additional required patterns in their own rules files. When the consuming repo documents such a list, include it in the Category B check.

Report the secret-file Read denies with their scope, not as protection: a Read(...) deny covers the built-in file tools and the Bash file commands Claude Code recognizes, but not a subprocess that opens the path itself. "Scope of a Read deny" in reference/required-permissions.md carries the covered / not-covered split, the ranked remedies, and the platform limit. Carry it into the finding rather than implying the file is unreachable.

CC settings schema, MCP server shape, hook event names, and permission glob syntax are upstream invariants resolved against their own official pages when a check needs them, rather than asserted as fixed patterns here.

Post-Audit

Consumer workaround inventory

When a settings-affecting upstream issue drives a project-specific workaround (or one becomes obsolete), record that in the consuming repo's own conventions/rules files. The plugin's bundled known-issues.md tracks only broadly-applicable upstream issues and is refreshed via plugin updates, not per-consumer edits.

Suggest frequency

Based on findings count:

• 0 findings: "Config is clean. Recheck after next Claude Code major update."
• 1-3 findings: "Minor drift. Monthly recheck recommended."
• 4+ findings: "Significant drift detected. Consider running after every CC update."