Config Audit
Run a read-only health check on CLAUDE.md and related Claude config against config-guidelines.md and get audit-report.md for refactors.
Overview
config-audit is an agent skill most often used in Ship (also Build agent-tooling, Operate iterate) that read-only audits Claude configuration against config-guidelines.md and writes audit-report.md.
Install
npx skills add https://github.com/fearovex/claude-config --skill config-auditWhat is this skill?
- Read-only audit against docs/config-guidelines.md (global) or ~/.claude/docs/config-guidelines.md (project)
- Detects global claude-config repo vs project CLAUDE.md vs no-config stop
- Triggers: /config-audit, audit config, configuration health check
- Outputs audit-report.md as input for config-refactor
- Procedural format aligned with config-guidelines principles including execution-context detection (Principle 13)
- Produces audit-report.md consumed by config-refactor
- Three execution modes: global, project, and no-config stop
Adoption & trust: 1 installs on skills.sh; 1 GitHub stars; trending (+100% hot-view momentum).
What problem does it solve?
Your CLAUDE.md and Claude config have grown messy and you need a guidelines-aligned report before letting an agent refactor them.
Who is it for?
Maintainers of claude-config templates or per-project CLAUDE.md who want a documented baseline audit trail.
Skip if: Repositories with no CLAUDE.md yet (skill stops in no-config mode) or users who want automatic fixes without a separate refactor step.
When should I use this skill?
/config-audit, audit config, audit claude config, review configuration, or configuration health check.
What do I get? / Deliverables
You receive audit-report.md listing gaps against the guidelines spec, ready to hand off to config-refactor.
- audit-report.md
- Documented execution mode (global, project, or no-config halt)
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship review is the canonical shelf because the skill compares live config to a spec and produces a report before you change anything—quality gate behavior. Review matches read-only auditing consumed by config-refactor rather than generating product code.
Where it fits
Run /config-audit on a SaaS repo’s CLAUDE.md before merging a config-refactor PR.
Audit a new project’s Claude files against the deployed global guidelines after project init.
Re-audit the claude-config global repo after adding skills to confirm Principle 13 context detection still holds.
How it compares
Read-only configuration checker that feeds config-refactor—not a one-shot chat review with no audit-report.md artifact.
Common Questions / FAQ
Who is config-audit for?
Solo builders and repo maintainers standardizing Claude Code config against fearovex-style config-guidelines, in either the global claude-config repo or a project with CLAUDE.md.
When should I use config-audit?
In Ship review before refactors; during Build agent-tooling when onboarding a project; in Operate iterate when re-checking config health after changes—especially via /config-audit or audit claude config triggers.
Is config-audit safe to install?
The skill is read-only by design but reads repo and home config paths; review the Security Audits panel on this Prism page and inspect audit-report.md before running config-refactor.
Workflow Chain
Then invoke: config refactor
SKILL.md
READMESKILL.md - Config Audit
# config-audit > Audits the repo's Claude configuration against `docs/config-guidelines.md`. Read-only. > Produces `audit-report.md` consumed by `config-refactor`. **Triggers**: /config-audit, audit config, audit claude config, review configuration, configuration health check --- ## Process ### Step 0 — Detect execution context Determine which mode to run in (per Principle 13): - **Global mode** — CWD is the `claude-config` repo. Detected when ALL of: - `install.sh` exists at CWD root. - `skills/_shared/` exists at CWD root. - OR basename of CWD matches `claude-config` or `agent-config`. - **Project mode** — CWD is any other directory containing a `CLAUDE.md` at root. - **No-config mode** — CWD has no `CLAUDE.md`. Stop and print: `No CLAUDE.md found in this directory. Run project-claude-init (future) or create one manually before auditing.` Record the detected mode and proceed. The mode controls Step 1 (guidelines source) and Step 2 (target file enumeration). ### Step 1 — Locate guidelines **Global mode** — read `docs/config-guidelines.md` from CWD. This file is the spec. **Project mode** — read `~/.claude/docs/config-guidelines.md` (the deployed global spec) as the read-only baseline. The project's own `CLAUDE.md` is the audit target, not a spec source. If the guidelines file does not exist in either mode: - Emit CRITICAL "Guidelines file missing — cannot audit. In global mode, create `docs/config-guidelines.md`. In project mode, run `install.sh` from the `claude-config` repo on this machine." - Stop. Do not produce a partial report. ### Step 2 — Enumerate target files **Global mode** — audit only these targets, in this order: 1. `CLAUDE.md` (root) 2. `output-styles/*.md` 3. `skills/*/SKILL.md` 4. `hooks/*` (read for cross-checks against `CLAUDE.md`, do NOT audit hook internals) 5. `settings.json` and `settings.local.json` (cross-checks only — duplicated rules, hook declarations matching files in `hooks/`) 6. `mcp/*.json` (existence only) 7. `keybindings.json` (existence only) 8. `~/.claude/` orphan scan (Principle 12 whitelists). Do not audit anything else. Out of scope: `docs/` (except guidelines), `memory/`, `agents/`, test fixtures, README. **Project mode** — audit only these targets: 1. `CLAUDE.md` at CWD root (the project's own). 2. `.claude/skills/*/SKILL.md` if present (project-local skills). 3. `.claude/settings.json` and `.claude/settings.local.json` if present. Out of scope in project mode: `~/.claude/` runtime directories, the global `CLAUDE.md`, anything outside the project root. The global layer is read-only reference for duplication checks (Principle 13 anti-duplication rule). ### Step 3 — Run check matrix Apply every check below. For each finding, record: - `severity`: CRITICAL | WARNING | SUGGESTION - `file`: absolute path - `line` (if applicable) - `rule`: the principle name from guidelines (e.g. "Principle 4 — Token budget") - `finding`: one-sentence description - `fix_hint`: one-sentence suggested action #### Token-budget checks (Principle 4) For each target file: - Count lines. - Compare against the file's soft and hard limit from the guidelines table. - Over hard limit → CRITICAL. - Over soft limit → WARNING. #### Separation-of-concerns checks (Principle 2) Scan `CLAUDE.md` for: - Sections that match orchestrator/agent-specific scope (e.g. "Bind this to … agent or rule only", explicit sub-agent contracts, SDD model assignments). If found and no `agents/<name>.md` exists, raise WARNING "Move scoped section to `agents/`". - A manual skill catalog (table listing 5+ skills with descriptions). If found, raise WARNING "Remove manual skill catalog — harness auto-discovers skills (Principle 2)". Scan each `output-styles/*.md` for: - Bullets that begin with ver