Audit Skill

Scan all AI documentation in the current project, evaluate quality, detect gaps and drift, and produce an actionable report with scores and recommendations.

Step 1: Discover All AI Documentation

Scan for every AI doc file across all three agents. Use Glob patterns to find:

Claude Code files:

• CLAUDE.md (root)
• packages/*/CLAUDE.md (monorepo)
• apps/*/CLAUDE.md (monorepo)
• .claude/rules/*.md
• .claude/skills/*/SKILL.md
• .claude/agents/*.md
• .claude/commands/*.md
• .claude/settings.json
• .claude/hooks/*.json or hooks.json

Cursor files:

• .cursor/rules/*.mdc
• .cursorrules (legacy)
• .cursorignore

Codex CLI files:

• AGENTS.md (root)
• packages/*/AGENTS.md (monorepo)
• apps/*/AGENTS.md (monorepo)
• .codex/config.toml
• .codexignore
• .agents/skills/*/SKILL.md

Record every file found with its path and last-modified date (via Bash stat or git log -1 --format="%ai" [file]).

Step 2: Read and Evaluate Each File

Read every discovered file. For each file, score it against the quality criteria in quality-criteria.md. Compute a score out of 100.

Apply the scoring rubric:

Dimension	Max Points	What to Check
Specificity	15	Does it reference the actual project (name, stack, real commands)? Or is it generic?
Conciseness	10	Uses progressive disclosure effectively — main files orient and point, detail lives in dedicated files that load on demand
Actionability	15	Instructions are concrete and verifiable (not vague "follow best practices")
Completeness	15	All recommended sections present (see quality-criteria.md for per-type checklist)
Consistency	15	No contradictions within the file or with other docs
Currency	10	No outdated framework versions, deprecated APIs, or old tool names
Examples	10	DO/DON'T code examples present and relevant
Structure	10	Proper formatting, headers, frontmatter (for MDC), valid YAML

Total: 100 points

Grades:

• 90-100: Excellent
• 75-89: Good
• 60-74: Needs improvement
• Below 60: Poor

Step 3: Check for Missing Recommended Files

Compare found files against recommended sets based on project type.

All projects should have:

• CLAUDE.md (root)
• .claude/settings.json

If 3+ code conventions detected:

• At least one .claude/rules/ file

If Cursor is used (check for .cursor/ directory):

• .cursor/rules/general.mdc or equivalent
• .cursorignore (if .env files exist)

If Codex CLI is used (check for .codex/ or existing AGENTS.md):

• AGENTS.md (root)
• .codex/config.toml

If ESLint/Prettier/Biome detected:

• PostToolUse hook for auto-formatting

If .env files detected:

• .cursorignore or deny rules in settings.json

If monorepo:

• Package-level CLAUDE.md in at least root packages
• Package-level AGENTS.md for Codex users

Step 4: Detect Sync Drift

Check for equivalent files across agents that should have consistent content but differ. Compare:

CLAUDE.md ↔ .cursor/rules/general.mdc ↔ AGENTS.md (root)

• Key commands (dev, build, test, lint) — all three should list the same commands
• Forbidden patterns — should be consistent across tools
• Framework / stack description — should match

Per rule: .claude/rules/[topic].md ↔ .cursor/rules/[topic].mdc

• Core DO/DON'T items should align
• Examples should demonstrate the same principle

For each drift detected, record:

• Which files differ
• What is different (commands, rules, examples)
• Severity: Minor (formatting only) / Moderate (different examples) / Major (contradictory rules)

Step 5: Detect Stale Content

Look for indicators of outdated content:

Version references:

• Grep for specific version numbers (e.g., "React 17", "Node 14", "Next.js 12")
• Compare against what's in package.json

Deprecated patterns:

• Old import styles (e.g., import React from 'react' required for React < 17)
• Deprecated API usage documented as required
• Old config file names (.babelrc when babel.config.js is used)
• References to removed packages or features

Outdated tool names:

• Package manager mismatch (docs say "npm install" but project uses Bun)
• Test runner mismatch (docs say "jest" but project uses "vitest")

Date indicators:

• Files with last-modified date > 6 months ago (flag for review, not automatic failure)

Step 6: Generate Audit Report

Output a structured report:

# Docsmith Audit Report
Generated: [date]

## Overall Health Score: [X]/100

| Agent | Files Found | Avg Score | Status |
|-------|-------------|-----------|--------|
| Claude Code | [n] | [score] | [grade] |
| Cursor | [n] | [score] | [grade] |
| Codex CLI | [n] | [score] | [grade] |

---

## File-by-File Scores

### Claude Code
| File | Score | Grade | Top Issue |
|------|-------|-------|-----------|
| CLAUDE.md | [score] | [grade] | [main issue] |
| .claude/rules/[name].md | [score] | [grade] | [main issue] |

### Cursor
| File | Score | Grade | Top Issue |
|------|-------|-------|-----------|
| .cursor/rules/[name].mdc | [score] | [grade] | [main issue] |

### Codex CLI
| File | Score | Grade | Top Issue |
|------|-------|-------|-----------|
| AGENTS.md | [score] | [grade] | [main issue] |

---

## Missing Recommended Files

[List any recommended files that are absent, with brief explanation of why each matters]

---

## Sync Drift Detected

[List any drifts found between equivalent files, with severity]

---

## Stale Content

[List any outdated references found, with file and line]

---

## Recommendations (Priority Order)

1. [Highest impact action] — [which file, what to change]
2. [Second action]
3. [Third action]
...

---

## Quick Wins (< 5 minutes each)

- [Small fix 1]
- [Small fix 2]

Step 7: Offer Next Steps

After printing the report, ask: "Would you like me to automatically fix any of these issues? I can:

1. Fix formatting and structure issues
2. Update stale commands to match current package.json
3. Sync drift between equivalent files
4. Generate any missing recommended files

Enter numbers separated by commas, or 'skip' to review manually."

If the user selects options, execute the fixes. For each fix, report what changed.