How do I install the Claudemd Audit skill?

Run npx skillmds add majiayu000/claudemd-audit in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Claudemd Audit safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Claudemd Audit?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Claudemd Audit free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Claudemd Audit?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Claudemd Audit by majiayu000 — Agent Skill

Name: Claudemd Audit
Rating: 4.2 (5 reviews)
Author: majiayu000

Claudemd Audit

Use when the user wants to audit CLAUDE.md files for bloat, staleness, misplacement, or information architecture issues. Invoked with /claudemd-audit. Supports --project, --global, --all scopes and --fix for auto-remediation. Use periodically or before shipping to ensure CLAUDE.md stays lean.

majiayu000 8c7b509 2 files · 4.5 KB Updated Sep 9, 2026 567 repo stars

File contents

CLAUDE.md Audit

Every line in always-loaded context must pass: "Would removing this cause Claude to make mistakes?"

Arguments

No args / --project: Project CLAUDE.md + architecture
--global: ~/.claude/CLAUDE.md + global skills/hooks
--all: Global + project + child dirs
--fix: Apply fixes interactively after report

Phase 1: Discovery

Map the architecture before auditing files. Use Glob/Read to find:

Always-loaded: ./CLAUDE.md + @imports, ~/.claude/CLAUDE.md + @imports, AGENTS.md
On-demand: .claude/skills/*/SKILL.md, child CLAUDE.md files
Enforcement: .claude/settings.json hooks, .pre-commit-config.yaml, .githooks/
Reference: docs/*.md, Makefile
Tooling: Linter configs, build systems (package.json, Cargo.toml, pyproject.toml)

Phase 2: Per-File Audit (28 checks)

Use Grep/Read for evidence. Do not guess.

A. Bloat — 1. Line count (flag >200, warn >150, target <100/<50 global) 2. Linter-territory rules (cross-ref linter configs) 3. Self-evident instructions ("write clean code") 4. Conventions Claude already knows 5. AI verbosity (reuse /humanizer patterns; 3+ triggers = flag) 6. Tutorials (>3 sentences, no actionable rule) 7. File-by-file descriptions (>10 lines)

B. Staleness — 8. Dead file refs (verify with ls) 9. Dead commands (check which/command -v) 10. Dead @import refs 11. Stale branch/PR refs (check git branch -a)

C. Misplacement — 12. Should be a hook (deterministic rules; redundant if enforced, suggest hook if not) 13. Should be a skill (domain knowledge >20 lines) 14. Should be in docs/ (>30 lines; use @import)

D. Duplication — 15. Global↔project overlap 16. CLAUDE.md↔skill overlap 17. CLAUDE.md↔hook overlap

E. Missing Essentials — 18. No build/test commands (Makefile/package.json exists but undocumented) 19. No branch conventions 20. Missing @imports for docs/ markdown

F. Structure — 21. Mixed concerns (commands + style + architecture blended) 22. Missing project CLAUDE.md (--all) 23. Unnecessary child CLAUDE.md

G. Architecture — 24. Always-loaded budget (CLAUDE.md + @imports + AGENTS.md total; flag >500 lines) 25. Tier separation (operational essentials only in CLAUDE.md; domain → skills; reference → docs) 26. Cross-ref hygiene (pointers not inlined content; no circular refs) 27. Makefile help target (reference make help instead of listing targets) 28. Hook coverage gap (advisory text vs deterministic enforcement)

Scoring (0-100)

Line count (15): 15/10/5/0 at <100/<150/<200/>200. Bloat (15): -3/finding. Staleness (10): -5/dead ref. Misplacement (15): -3/block. Duplication (10): -3/dup. Essentials (10): +5 build/test, +5 branch conventions. Structure (10): -3/issue. Architecture (15): +5 tiers, +5 budget, +5 cross-refs.

90+ Lean & well-architected / 70-89 Good / 50-69 Needs attention / <50 Overhaul

Output

Architecture table → per-file results table → category findings with line numbers → suggested improvements.

Fix Mode (`--fix`)

Report → ask which fixes to apply → Edit → re-audit for new score.

Gold Standard

Intactus (75 lines): three-tier progressive discovery. CLAUDE.md has branch workflow + Makefile commands + env vars + architecture pointers. Domain knowledge in .claude/skills/shadcn/ (hub-and-spoke). Deep reference in docs/. Every line passes the litmus test.

---name: claudemd-auditdescription: Use when the user wants to audit CLAUDE.md files for bloat, staleness, misplacement, or information architecture issues. Invoked with /claudemd-audit. Supports --project, --global, --all scopes and --fix for auto-remediation. Use periodically or before shipping to ensure CLAUDE.md stays lean.--- # CLAUDE.md Audit Every line in always-loaded context must pass: "Would removing this cause Claude to make mistakes?" ## Arguments - No args / `--project`: Project CLAUDE.md + architecture - `--global`: `~/.claude/CLAUDE.md` + global skills/hooks - `--all`: Global + project + child dirs - `--fix`: Apply fixes interactively after report ## Phase 1: Discovery Map the architecture before auditing files. Use Glob/Read to find: - **Always-loaded**: `./CLAUDE.md` + `@imports`, `~/.claude/CLAUDE.md` + `@imports`, `AGENTS.md` - **On-demand**: `.claude/skills/*/SKILL.md`, child `CLAUDE.md` files - **Enforcement**: `.claude/settings.json` hooks, `.pre-commit-config.yaml`, `.githooks/` - **Reference**: `docs/*.md`, `Makefile` - **Tooling**: Linter configs, build systems (`package.json`, `Cargo.toml`, `pyproject.toml`) ## Phase 2: Per-File Audit (28 checks) Use Grep/Read for evidence. Do not guess. **A. Bloat** — 1. Line count (flag >200, warn >150, target <100/<50 global) 2. Linter-territory rules (cross-ref linter configs) 3. Self-evident instructions ("write clean code") 4. Conventions Claude already knows 5. AI verbosity (reuse `/humanizer` patterns; 3+ triggers = flag) 6. Tutorials (>3 sentences, no actionable rule) 7. File-by-file descriptions (>10 lines) **B. Staleness** — 8. Dead file refs (verify with `ls`) 9. Dead commands (check `which`/`command -v`) 10. Dead `@import` refs 11. Stale branch/PR refs (check `git branch -a`) **C. Misplacement** — 12. Should be a hook (deterministic rules; redundant if enforced, suggest hook if not) 13. Should be a skill (domain knowledge >20 lines) 14. Should be in docs/ (>30 lines; use `@import`) **D. Duplication** — 15. Global↔project overlap 16. CLAUDE.md↔skill overlap 17. CLAUDE.md↔hook overlap **E. Missing Essentials** — 18. No build/test commands (Makefile/package.json exists but undocumented) 19. No branch conventions 20. Missing `@imports` for docs/ markdown **F. Structure** — 21. Mixed concerns (commands + style + architecture blended) 22. Missing project CLAUDE.md (`--all`) 23. Unnecessary child CLAUDE.md **G. Architecture** — 24. Always-loaded budget (CLAUDE.md + @imports + AGENTS.md total; flag >500 lines) 25. Tier separation (operational essentials only in CLAUDE.md; domain → skills; reference → docs) 26. Cross-ref hygiene (pointers not inlined content; no circular refs) 27. Makefile `help` target (reference `make help` instead of listing targets) 28. Hook coverage gap (advisory text vs deterministic enforcement) ## Scoring (0-100) Line count (15): 15/10/5/0 at <100/<150/<200/>200. Bloat (15): -3/finding. Staleness (10): -5/dead ref. Misplacement (15): -3/block. Duplication (10): -3/dup. Essentials (10): +5 build/test, +5 branch conventions. Structure (10): -3/issue. Architecture (15): +5 tiers, +5 budget, +5 cross-refs. 90+ Lean & well-architected / 70-89 Good / 50-69 Needs attention / <50 Overhaul ## Output Architecture table → per-file results table → category findings with line numbers → suggested improvements. ## Fix Mode (`--fix`) Report → ask which fixes to apply → Edit → re-audit for new score. ## Gold Standard Intactus (75 lines): three-tier progressive discovery. CLAUDE.md has branch workflow + Makefile commands + env vars + architecture pointers. Domain knowledge in `.claude/skills/shadcn/` (hub-and-spoke). Deep reference in `docs/`. Every line passes the litmus test.

Frequently asked questions