| name | claude-reviewer |
| description | Review any project's .claude/ setup against Claude Code best practices and produce an actionable improvement report.
Use when: "/claude-reviewer", "review my claude config", "audit .claude setup", "check my CLAUDE.md", "how good is my claude config", "rate this project's claude setup".
NOT for: reviewing individual skill quality (use /skill-reviewer), code review, PR review.
|
| user-invocable | true |
| argument-hint | [--global] [--verbose] [--with-logs] [project-path] |
| allowed-tools | Read, Glob, Grep, Bash(python3*), Bash(git*) |
/claude-reviewer - Claude Code Configuration Auditor
Review any project's .claude/ folder against best practices from Anthropic's Claude Code configuration guidance.
How It Differs from /skill-reviewer
| /skill-reviewer | /claude-reviewer |
|---|
| Input | A single skill directory | An entire project's .claude/ folder |
| Evaluates | Skill design quality (SKILL.md, scripts, references) | Config hygiene (CLAUDE.md, settings.json, rules/, commands/, skills/, agents/) |
| When | After building a skill | When setting up or auditing a project |
| Output | 10-dimension skill score (max 29) | 8-dimension config score (max 24) |
Arguments
/claude-reviewer -> Review current working directory
/claude-reviewer ~/Code/myproject -> Review specific project
/claude-reviewer --global -> Review ONLY ~/.claude/ global config
/claude-reviewer --verbose -> Include evidence quotes in report
/claude-reviewer --with-logs -> Add transcript-based "unused skills" detection
$ARGUMENTS = [--global] [--verbose] [--with-logs] [project-path]
Parse the argument before starting:
- Extract
--global flag if present.
- Extract
--verbose flag if present. When set, include evidence quotes.
- Extract
--with-logs flag if present. Forward it to scripts/fleet_audit.py in Phase 4 Step 1 for opt-in transcript scanning (unused-skill detection).
- Remaining token is the project path.
- Routing logic:
--global → Global mode: audit only ~/.claude/. Score 5 applicable dimensions (D1, D2, D4, D5, D6 — max 15). Ignore any project path. Use the Global Configuration report template only.- No
--global → Project mode: audit the project path (or cwd if none given). Score all 8 dimensions (max 24). No global section.
- Ask the user for confirmation before reading home directory contents when
--global is used.
- If the path doesn't exist, report "Directory not found: [path]."
- If the path has no
.claude/ directory AND no CLAUDE.md (project mode only), report "No Claude Code configuration found at [path]."
Workflow
Phase 1: Structural Scan
Run the deterministic scanner:
python3 scripts/scan.py <project-path> --json [--global]
If the scanner fails (non-zero exit, invalid JSON), stop and report the error to the user. Do not attempt to score manually without scanner output.
This returns JSON with:
- Full inventory of all
.claude/ components
- Structural scores for D1, D2, D3, D4, D7 (and partial D5, D6, D8)
- Anti-pattern detection
- CLAUDE.md content analysis (section headings, linter content, theory paragraphs)
Parse the JSON output. Use the structural scores directly for D1, D2, D3, D4, D7. Dimensions with score: null require your semantic evaluation in Phase 2.
Phase 2: Semantic Evaluation
For dimensions the scanner cannot fully score:
D5: Skills Setup — Read each skill's SKILL.md. Does the description explain when to trigger AND when NOT to use? Are allowed-tools minimally scoped (no bare Bash)? Does the skill use progressive disclosure (references/, scripts/)? Is the description trigger-focused, not generic?
D6: Agent Configuration — Read each agent file. Is the model selection appropriate? (haiku for read-only, sonnet for balanced, opus for complex.) Are tools minimally scoped? Does each agent have a clear, distinct purpose?
D8: Progressive Disclosure — Holistic judgment: does CLAUDE.md serve as a lean hub that delegates to .claude/ components? Are path-scoped rules used instead of cramming everything into CLAUDE.md? Is the overall structure proportional to the project's complexity?
Also review D3 and D4 for semantic quality the scanner cannot assess:
- D3: Are rule files each focused on a single concern? (Scanner caps at 2; bump to 3 if quality is excellent.)
- D4: Are commands genuinely useful team workflows? (Scanner caps at 2; bump to 3 if commands are high-value.)
Adjust a structural score only if you have specific evidence. Note the reason.
Phase 3: Detect Anti-Patterns
The scanner auto-detects structural anti-patterns. Add semantic ones:
- CLAUDE.md contains content that belongs in linter/formatter configs
- CLAUDE.md has long theory paragraphs (instruction drift)
- Rules files try to cover multiple concerns
- Commands missing
$ARGUMENTS for parameterization
- Skills with generic descriptions that won't trigger correctly
- Agents with overly broad tool access
Phase 4: Generate Report
Step 1 — Fleet skill-cleaner audit. Run python3 scripts/fleet_audit.py <project-path> (or --global in global mode; append --with-logs if the user passed it). Include the script's output verbatim under ## Skill Fleet Audit, placed between Inventory and Scores in the report. The four signals — fleet budget, description trim candidates, duplicates across roots, opt-in unused — are informational; they do not affect the rubric score, but heavy/duplicate findings should surface in Top 3 Improvements where actionable, and per-skill trims flow through /skill-reviewer --fix <skill>. Methodology: skill-cleaner by @steipete.
Step 2 — Fill the report template. Read references/report-template.md and fill the appropriate sections.
Project mode: Score all 8 dimensions (D1-D8, max 24). Grade: 21-24=A, 16-20=B, 11-15=C, 6-10=D, 0-5=F.
Global mode: Use only the Global Configuration section of the template. Score 5 dimensions (D1, D2, D4, D5, D6 — max 15). Grade: 13-15=A, 10-12=B, 7-9=C, 4-6=D, 0-3=F.
Phase 5: Actionable Recommendations
For each dimension scoring below 2, provide a specific, actionable recommendation. Prioritize by expected impact (points gained per effort).
Always include Quick Wins — concrete items achievable in under 5 minutes.
Scoring Dimensions Summary
| Dim | Name | Max | Scanner | Claude |
|---|
| D1 | CLAUDE.md Quality | 3 | Partial (length, sections, linter content) | Content quality, conciseness judgment |
| D2 | Permission Hygiene | 3 | Full | — |
| D3 | Modular Instructions | 3 | Partial (existence, count, path scoping) | Single-concern quality, delegation |
| D4 | Custom Commands | 3 | Partial (frontmatter, $ARGUMENTS, backtick) | Usefulness, workflow coverage |
| D5 | Skills Setup | 3 | Structural signals only | Trigger quality, tool scoping, disclosure |
| D6 | Agent Configuration | 3 | Structural signals only | Model selection, tool scoping, purpose |
| D7 | Git Hygiene | 3 | Full | — |
| D8 | Progressive Disclosure | 3 | Partial (component count) | Holistic organization quality |
References
references/best-practices.md — 8-dimension scoring rubric with anchorsreferences/report-template.md — output format templatescripts/scan.py — structural scanner (D1-D4, D7 full; D5, D6, D8 partial)scripts/fleet_audit.py — fleet-level skill-cleaner signals (Phase 4 Step 1): budget, trim candidates, duplicates, optional unused detectionexamples/sample-review.md — complete example report for calibration
Gotchas
Projects without .claude/ folder: Some projects use only a root CLAUDE.md with no .claude/ directory. This is valid for simple projects. Score D2-D6 as 0 but note "Minimal configuration — appropriate for simple/early-stage projects" rather than treating it as a failure.
Monorepo CLAUDE.md files: Some projects have CLAUDE.md at multiple levels (root, packages/, apps/). Only score the root-level one for D1. Note nested files as a strength.
Git operations require a git repo: scan.py's git checks fail on non-git directories. It handles this gracefully (skips git checks, scores D7 as N/A).
settings.local.json vs settings.json: The local file should be gitignored; the non-local file should be committed. Don't confuse them.
Empty .claude/ directories: Some projects create .claude/ but leave it empty (only settings.local.json from plugin installs). Treat as "no configuration" for scoring.
Global scope requires confirmation: When --global is used, ask the user before reading ~/.claude/ contents. Home directory contents are personal.
