claude-audit

Claude Audit Skill

Produce a deterministic overlap/conflict report for the project's effective Claude Code configuration. The audit considers user-scope (~/.claude/), project-scope (<project>/.claude/), and plugin-provided sources together — because that is what the agent actually loads at runtime.

The output is a single markdown report. The skill itself does not modify any files. All recommendations are presented to the user; they decide what to change.

---

Step 1: Discover the project objective

Before evaluating overlaps, read the project's CLAUDE.md (and any README.md) at the repo root to understand what the project does. Specific things to extract:

• Domain — web app, infra, mobile, ML, mod development, etc.
• Languages / frameworks — informs which language skills are relevant
• Workflows codified in CLAUDE.md — issue tracking, PR conventions, branching, testing

Recommendations later are scoped to these. A python skill is not "redundant" just because the project also uses TypeScript — it might still be load-bearing for tooling scripts.

If no project-level CLAUDE.md exists, fall back to the user-level ~/.claude/CLAUDE.md and note that the audit is using the user-scope objective only.

---

Steps 2–5: Deterministic inventory and analysis

Run the built-in CLI subcommand and capture its markdown output:

python -m claude_prospector audit --project-dir <project-root>

This single command covers all four deterministic steps:

• Step 2 — Inventory: walks user-scope (~/.claude/agents/, ~/.claude/skills/*/SKILL.md), project-scope (.claude/agents/, .claude/skills/*/SKILL.md), the plugin cache (latest version per (marketplace, plugin) only), and Windows Claude Desktop ~/AppData/Roaming/Claude/…/skills-plugin/ if present.
• Step 3 — Direct name collisions: groups all items by (_type, name); any group with more than one entry is a collision.
• Step 4 — Semantic overlaps: computes bigram-Jaccard similarity on description text for same-type pairs; flags pairs with Jaccard ≥ 0.5.
• Step 5 — Tool-coupling concerns: scans each skill body for mcp__* mentions and PowerShell/Bash references; cross-references against each agent's tools: frontmatter and warns on mismatches.

The command also reports cache-hygiene findings: stray temp_git_* clone leftovers and plugin names duplicated across multiple marketplace directories.

Use --format json for machine-readable output with keys inventory, collisions, overlaps, tool_coupling, and cache_hygiene.

---

Step 6: Render the report

Produce a single markdown document with these sections, in order:

# Claude Config Audit — <project name or "user-scope only">

## Project objective

<one paragraph paraphrased from the project CLAUDE.md, or "User-scope audit — no project CLAUDE.md found.">

## Inventory

- **Custom agents**: N (`name1`, `name2`, ...)
- **Custom skills**: N (`name1`, ...)
- **Plugin agents**: N from M plugins
- **Plugin skills**: N from M plugins
- **Effective total exposed to runtime**: N agents, M skills

## Direct name collisions

| Name            | Sources                          | Descriptions diverge? | Tools diverge? | Recommendation                       |
| --------------- | -------------------------------- | --------------------- | -------------- | ------------------------------------ |
| `code-reviewer` | custom, superpowers, feature-dev | No (near-identical)   | Yes            | Keep custom; disable plugin variants |

## Semantic overlaps

| Pair                                     | Jaccard | Verdict                                       | Recommendation                                   |
| ---------------------------------------- | ------- | --------------------------------------------- | ------------------------------------------------ |
| `git` (custom) ↔ `anthropic-skills:git` | 0.92    | True duplicate with project-specific addendum | Extract addendum to dedicated skill, drop custom |

## Tool-coupling concerns

| Agent         | Skill passed in | Missing tool                   | Recommendation                                                                  |
| ------------- | --------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `code-writer` | `powershell`    | `PowerShell` (only has `Bash`) | Translate guidance to POSIX in delegation, or pass to agent that has PowerShell |

## Recommendations summary

| Item                      | Action                | Priority | Rationale                   |
| ------------------------- | --------------------- | -------- | --------------------------- |
| Drop `feature-dev` plugin | uninstall via /plugin | high     | 3 overlap items in one move |

...

Order recommendations by leverage — a single action that resolves multiple overlaps should rank above a single-item fix. Where the user has stated objectives in their CLAUDE.md, mark recommendations that conflict with those objectives as "verify with user before acting" rather than asserting them.

---

Step 7: Offer follow-ups

After delivering the report, ask the user:

1. Whether to open GitHub Issues for each "drop" / "modify" recommendation (using the project's issue tracker per CLAUDE.md conventions)
2. Whether to create a Milestone grouping them, if there are 3+ recommendations
3. Whether to start on any specific recommendation now

Do not start making changes without explicit user confirmation. This skill is read-only audit + recommendation; modifications are tracked separately.

---

Reference

Why "effective" config, not just custom?

A user might think "my config is fine, I only have 8 custom agents." But what loads at runtime includes ~50 plugin skills and ~5 plugin agents. Overlaps appear at the boundary between custom and plugin, and that boundary is invisible if you only audit one side.

Why scope to project objective?

The same set of skills can be over-broad for one project and under-broad for another. A python skill is essential in a Python repo and dead weight in a pure-Rust repo. The audit should prefer keeping skills the project plausibly needs and dropping ones it does not — which requires knowing what the project does.

Related skills

• superpowers:writing-skills — for authoring new skills if the audit recommends extracting one
• claude-md-management:claude-md-improver — for the CLAUDE.md side of the same hygiene work
• claude-prospector:usage-analysis — for the cost-side view (which skills/agents are actually consumed)

Long-Form Artifact Discipline

Audit reports are routinely 50–200 lines once every agent and skill is enumerated with a keep / modify / drop recommendation. Save the full report to <repo>/.tmp/<YYYY-MM-DD>-claude-audit.md and return a short chat reply listing:

1. Inventory totals — N agents and M skills audited (custom + plugin combined).
2. Disposition counts — keep / modify / drop tallies.
3. Top 2-3 most consequential overlaps or conflicts — typically direct name collisions or high-Jaccard semantic duplicates that resolve multiple items in one action.
4. The file path in backticks as the hand-off.

Do NOT paste the full report body inline — the file is the artifact, the chat reply is the pointer. The user opens the file for the full keep/modify/drop tables; the reply surfaces only what shapes their next decision.