review-claude-config

name

review-claude-config

description

Review the user's Claude Code configuration (settings.json permissions, hooks, skills, rules, CLAUDE.md, bin/ hook scripts) and surface concrete opportunities to improve, refine, consolidate, remove, or add to it. MUST be invoked when the user asks to review/audit/critique their Claude config, asks "what could be better about my setup", wants to prune dead or redundant config, or wants ideas for new hooks/skills/rules/permissions. SHOULD be invoked proactively when work repeatedly trips over a missing guardrail or a repeated manual step that config could automate.

Review Claude Config

Survey the whole Claude Code config surface in the dotfiles repo, then surface opportunities for improvement. This skill is an auditor and orchestrator: it finds and prioritizes opportunities, then hands the actual edits off to the specialized skills (update-config, hook-creator, rule-curator, skill-creator). It does not edit config directly.

1. Run the inventory first

Before reasoning about anything, get the mechanical facts. Run with uv (not python3):

uv run /home/jtk/.claude/skills/review-claude-config/scripts/inventory.py

It locates this dotfiles repo from its own location and reports, only for the config that lives in this repo: every hook command and whether it resolves to a bin/ script, every bin/claude-* script and whether anything still references it (orphan detection), exact-duplicate and subsumed permission entries, allow/deny overlaps, and component counts. Config installed under ~/.claude that doesn't come from this repo is out of scope. It makes no judgments and changes nothing.

Use its output as ground truth. Do not guess at what hooks or permissions exist from memory; read the report.

2. The config surface

Everything lives in claude/ in the dotfiles repo and is symlinked into ~/.claude/ by bin/link-claude. Edit the source in claude/, never the symlinks under ~/.claude/. Hook scripts live in bin/ (on PATH as dotfiles/bin), not under claude/.

• claude/settings.json — permissions, hooks wiring, env, model, statusline.
• .claude/settings.local.json — project-scoped overrides for this repo.
• claude/CLAUDE.md — global instructions for all projects. (The repo also has its own project CLAUDE.md at the root.)
• claude/rules/*.md — auto-loaded guidance, globally or paths:-scoped.
• claude/skills/*/SKILL.md — skills, some with scripts/, references/.
• bin/claude-* — the hook scripts referenced from settings.json.

3. What to look for

Read the actual files; the rubric below is what to weigh, not a checklist to mechanically tick. Lead with high-confidence, high-value findings.

• Permissions. Beyond the script's dupe/subsumption flags: is anything in allow broader than it needs to be (a blanket Bash(foo *) where only one subcommand is ever used)? Are there read-only commands still prompting that belong in allow (see the fewer-permission-prompts skill)? Does deny cover the genuinely destructive cases? Project overrides in settings.local.json that have become permanent probably belong in the global file.
• Hooks. Any hook command the script flagged as missing is broken. Beyond that: is each hook still earning its place, or has it become noise? Is there a repeated manual correction or guardrail that a new hook could automate? Use the hook-creator skill for the event/JSON details.
• Rules. Look for overlap (two rules covering the same ground), staleness (advice that no longer matches how the user works), and missing paths: scoping that makes a narrow rule load globally. Flag rules that just restate what any competent engineer knows: they tax every session that loads them.
• Skills. Weak or keyword-thin descriptions hurt discoverability (the single most important skill property). Look for skills that overlap, that have gone stale, or for recurring multi-step workflows that deserve a new skill. Check that bundled scripts still match what SKILL.md claims.
• CLAUDE.md. Is anything here better expressed as a path-scoped rule, a hook (for things the harness must enforce, not just request), or a skill?

4. Search the web for ideas

Don't audit only against what already exists; the config can lag behind what the tooling now supports. Actively look outward:

• Check the current Claude Code docs for features, hook events, or settings that aren't being used yet. The claude-code-guide agent and code.claude.com/docs are the authoritative sources; prefer them over memory, which goes stale as the product ships.
• Web-search for community patterns: useful hooks, skill ideas, permission setups, and config conventions others have published. Bring back concrete, verified ideas, not vague inspiration.

Treat external ideas as candidates to evaluate against how the user actually works, not mandates to adopt.

5. Present findings, then hand off

Report opportunities grouped by component, each with a one-line rationale and a rough priority. Get the user's buy-in before changing anything. When they pick something to act on, route it to the skill that owns that surface:

• permissions / settings.json / hooks wiring -> update-config
• new or changed hook script -> hook-creator
• rules -> rule-curator
• skills -> skill-creator

Per the user's CLAUDE.md, don't commit or push; leave that to them.