claude-setup-audit

A Claude Code skill that audits your Claude Code setup against Anthropic's official best practices.

Product page → · Install · Usage · What it checks · Contributing

---

claude-setup-audit reads your CLAUDE.md, rules, skills, subagents, and settings, then scores your setup across six dimensions and writes a report where every finding cites a file and line number and includes the exact fix to apply — complete file snippets, not vague advice.

Sources it audits against:

• Steering Claude Code: skills, hooks, subagents and more
• Best practices for Claude Code

---

What it checks

Scores your setup across 6 dimensions (each 0–10, overall 0–100):

Dimension	What it evaluates
CLAUDE.md Health	Line count, bloat, procedures that should be skills, enforcement rules that should be hooks
Primitive Placement	Is each instruction in the right primitive? (CLAUDE.md vs skill vs rule vs hook vs subagent)
Rules Hygiene	Path-specific rules using paths: frontmatter, no duplication with CLAUDE.md
Hooks Usage	Are deterministic requirements in hooks, not advisory text? "Always/never" language detected
Skills Quality	Procedural content, clear descriptions for auto-invocation, disable-model-invocation on side-effect skills
Subagents Quality	Scoped tool lists, explicit model pinning, correct use of isolation vs. main-thread visibility

Every finding includes:

• The specific file and line number
• Why it's wrong (traced to a rubric principle)
• The exact fix to apply (complete file snippets, not vague suggestions)

---

Install

This project ships as a Claude Code plugin.

Option 1: From the community marketplace (once approved)

In Claude Code:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install claude-code-audit@claude-community

Option 2: Direct from GitHub

In Claude Code:

/plugin marketplace add WayneGoosen/claude-code-audit
/plugin install claude-code-audit@WayneGoosen

Option 3: Manual

git clone https://github.com/WayneGoosen/claude-code-audit.git
claude --plugin-dir ./claude-code-audit

---

Usage

Once installed as a plugin, the skill is namespaced. In Claude Code, from your project root:

/claude-code-audit:claude-setup-audit

To audit a specific directory:

/claude-code-audit:claude-setup-audit ./path/to/project

Claude will:

1. Scan all setup files (CLAUDE.md, .claude/rules/, .claude/skills/, .claude/agents/, .claude/settings.json)
2. Score each dimension against the rubric
3. Write a full report to ./claude-setup-audit-report.md
4. Print a summary with your top quick wins

---

Example output

## Audit complete

Overall score: 62/100 (Fair)

| Dimension              | Score |
|------------------------|-------|
| 1. CLAUDE.md Health    | 6/10  |
| 2. Primitive Placement | 5/10  |
| 3. Rules Hygiene       | 8/10  |
| 4. Hooks Usage         | 4/10  |
| 5. Skills Quality      | 7/10  |
| 6. Subagents Quality   | 9/10  |

8 findings total: 2 high, 4 medium, 2 low
Full report written to: ./claude-setup-audit-report.md

Top 3 quick wins:
1. CLAUDE.md lines 45–62: deployment procedure → move to .claude/skills/deploy/SKILL.md
2. CLAUDE.md line 18: "always run prettier after edits" → PostToolUse hook in settings.json
3. .claude/rules/api-rules.md: missing paths: frontmatter for src/api/** scope

---

How it works

The plugin is a manifest plus three Markdown files. There is no binary, no dependency, and nothing to run outside Claude Code:

claude-code-audit/
├── .claude-plugin/
│   └── plugin.json    ← Plugin manifest (name, version, author)
└── skills/
    └── claude-setup-audit/
        ├── SKILL.md           ← The audit runner (invoked by /claude-code-audit:claude-setup-audit)
        ├── rubric.md          ← Scoring criteria, sourced from Anthropic docs
        └── report-template.md ← Output structure

SKILL.md walks Claude through locating your setup files, reading the rubric, scoring each dimension, and writing the report. disable-model-invocation: true means it only runs when you explicitly call /claude-code-audit:claude-setup-audit — it never fires on its own.

---

Philosophy

This tool uses Claude's judgment for the architectural questions that can't be mechanically checked. A linter can flag "CLAUDE.md is over 200 lines." Only Claude can evaluate "this 30-line deployment procedure would work better as a skill with disable-model-invocation: true so engineers invoke it explicitly."

Every recommendation in the report is specific enough to act on immediately — no vague "improve your hooks usage," only "add this JSON to settings.json to enforce this constraint."

---

Keeping it current

The rubric is sourced from Anthropic's docs. As Claude Code evolves (new primitives, updated guidance), the rubric should be updated. See CONTRIBUTING.md — PRs welcome.

Check the sources directly for the latest:

• https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
• https://code.claude.com/docs/en/best-practices

---

Contributing

Contributions are welcome — especially rubric updates as Claude Code's primitives evolve. See CONTRIBUTING.md and the Code of Conduct.

License

MIT © Wayne Goosen