# Audit Claude Md

> Audit all CLAUDE.md files in the current project for staleness and coverage gaps. For each existing file, scores freshness by checking git churn in its scoped directory since the file was last touched; flags content drift for stale ones; discovers directories that should have a CLAUDE.md but don't; reports a ranked findings list and offers to invoke /init per-file after approval. Global and proje…

- **Type:** Skill
- **Install:** `agentstack add skill-ada-ggf25-ai-tools-audit-claude-md`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ada-ggf25](https://agentstack.voostack.com/s/ada-ggf25)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ada-ggf25](https://github.com/ada-ggf25)
- **Source:** https://github.com/ada-ggf25/AI-Tools/tree/main/global/claude/skills/audit-claude-md

## Install

```sh
agentstack add skill-ada-ggf25-ai-tools-audit-claude-md
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Audit CLAUDE.md files (staleness + coverage check)

Project-agnostic, global skill. It audits every `CLAUDE.md` in the current repo —
checking whether existing files have drifted from the codebase and whether any
directories should have one but don't — then produces a ranked report and offers to
invoke `/init` on each problem file after per-file approval.

It pairs with `/init` (which writes/rewrites a CLAUDE.md) and `/where-claude` (which
scouts new placements). This skill is the *health-check* that keeps existing docs from
rotting silently.

## The staleness model

### Scope boundary
Each CLAUDE.md "owns" its directory and all subdirectories that do **not** have their
own CLAUDE.md. This scoped ownership is how git churn is attributed: a commit that only
touches files under `frontend/` does not make the root CLAUDE.md stale if `frontend/`
has its own file.

### Git churn signal
For each CLAUDE.md, the freshness baseline is its last-commit timestamp
(`git log -1 --format=%aI -- `). Commits since then that touched files within
the file's scope (excluding noise — see below) are the staleness count. Thresholds:

| Commits in scope since last touch | Signal |
|---|---|
| 0 – 4 | Likely fresh |
| 5 – 14 | Possibly stale — worth reviewing |
| 15+ | Likely stale — recommend `/init` |

Also treat as **likely stale** if any of these changed since the CLAUDE.md was last
touched: a manifest file (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
etc.), a CI config, or a top-level config file — these signal structural change.

### Noise filter
Exclude from the churn count: lock files (`*.lock`, `package-lock.json`, `yarn.lock`,
`Pipfile.lock`), generated/vendored dirs (`node_modules`, `dist`, `build`, `out`,
`vendor`, `.venv`, `target`, `__pycache__`, `.next`, `coverage`), and binary/asset
files. Count only source and config changes.

### Content drift check (only for stale candidates)
For files flagged as possibly/likely stale, read them and do a quick sanity check:
- Does the file reference files, directories, tools, or commands that no longer exist?
- Are there documented conventions that appear to contradict what the code now shows?
- Does the file omit obvious top-level changes (e.g. a new language/framework added)?

This check is semantic and approximate — flag anything suspicious for the user to
decide, not for you to auto-correct.

### Orphaned CLAUDE.md
If a CLAUDE.md's parent directory has been largely deleted or its subtree collapsed
into another module, flag it as **orphaned**. These need deletion, not `/init`.

### Missing CLAUDE.md (coverage gap)
Apply the `/where-claude` scoring heuristic to find directories that qualify for their
own CLAUDE.md but don't have one. Only report clear candidates; bias to restraint
(same as `/where-claude`).

## Procedure

### 1. Orient
- Confirm the cwd is the repo root the user intends (ask if in a monorepo/submodule).
- Find all existing CLAUDE.md files:
  `find . -name CLAUDE.md -not -path '*/node_modules/*' -not -path '*/.git/*'`
- If there are none at all, say so and suggest `/init` for the root, then stop.
- For a large or unfamiliar repo, delegate the directory sweep to the `Explore` agent
  and score from its summary.

### 2. Build the scope map
- For each CLAUDE.md, determine its owned scope: its directory minus subdirectories
  that have their own CLAUDE.md.
- Note parent–child relationships so churn is not double-counted.

### 3. Score staleness (git churn)
For each CLAUDE.md:
- Get the last-touch timestamp: `git log -1 --format=%aI -- `
- Count commits in scope since then, noise-filtered:
  `git log --oneline --since="" --  | wc -l`
  (then manually exclude noise paths in the scope if needed)
- Check whether any manifest/CI/config file in scope changed since then.
- Assign: **Likely fresh** / **Possibly stale** / **Likely stale** / **Orphaned**.

### 4. Content drift check (stale candidates only)
- Read each file flagged as possibly/likely stale.
- Note references to missing paths, contradicted conventions, or obvious omissions.
- Keep notes short — one or two bullet points per file max.

### 5. Coverage gap scan (missing CLAUDE.md)
- Apply the `/where-claude` heuristic to identify directories that clearly qualify but
  have no CLAUDE.md. Report only strong candidates.

### 6. Report
Present the findings in this order:
1. **Likely stale** — high churn, content drift confirmed or suspected. Recommend
   `/init` to rewrite.
2. **Orphaned** — directory largely gone; recommend deletion.
3. **Missing** — new directories that should have a CLAUDE.md. Recommend `/init`.
4. **Possibly stale** — moderate churn; recommend a manual review pass.
5. **Likely fresh** — low churn; list briefly with last-touch date for completeness.

For each finding include: file path, last-touch date, churn count, and a one-line
rationale. For content drift, add the specific concern(s).

### 7. Offer per-file action
For each file in categories 1–3:
- Offer to invoke `/init` (for stale/missing) or flag for manual deletion (orphaned).
- Get approval per file before acting — never batch-rewrite without confirmation.
- Do NOT auto-run `/init` without explicit per-file approval.

## Guardrails
- Never modify or delete any CLAUDE.md without explicit per-file user approval.
- Scope churn attribution correctly: do not charge parent files for commits that only
  touched a child-scoped subtree.
- Apply the noise filter consistently; lock files and generated dirs must not inflate
  staleness scores.
- Content drift check is approximate — flag concerns, do not make authoritative
  pronouncements about what the file "should" say.
- Coverage gap recommendations: bias to restraint; a few clear candidates beat a long
  list of borderline ones.
- Never fabricate repo facts — base every finding on files and git history you actually
  observed.
- For a large repo, delegate the directory sweep to the `Explore` agent rather than
  reading every file in the main thread.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ada-ggf25](https://github.com/ada-ggf25)
- **Source:** [ada-ggf25/AI-Tools](https://github.com/ada-ggf25/AI-Tools)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ada-ggf25-ai-tools-audit-claude-md
- Seller: https://agentstack.voostack.com/s/ada-ggf25
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.