| name | community-claude-md-guardian |
| version | 1.0.0 |
| model | sonnet |
| description | Audits CLAUDE.md files for conflicts, stale rules, missing sections, and cross-file coherence. Produces a health report with auto-fix suggestions — audit only, no enforcement mechanism. Full version (adds a PreToolUse hook to enforce the ruleset going forward): `system-health:claude-md-guardian`. Use when: 'check claude.md', 'audit CLAUDE.md', 'fix claude.md', 'claude md health'. |
| triggers | ["check claude.md","audit CLAUDE.md","fix claude.md","claude md health"] |
| category | repo-docs-health |
| inputs | [{"name":"context","type":"string","description":"Trigger context — branch merge, onboarding, weekly maintenance, behavior inconsistency, or post-learning","required":false}] |
| outputs | [{"name":"health_report","type":"string","description":"CLAUDE.md health report with severity-classified findings and auto-fix suggestions"}] |
CLAUDE.md Guardian Skill
I. Philosophy
CLAUDE.md is the agent's behavioral contract. When rules drift, conflict, or accumulate without review, agent behavior becomes unpredictable in ways that are almost impossible to debug — because the symptom (agent doing the wrong thing) is far removed from the cause (contradictory rule added three sessions ago).
The guardian treats CLAUDE.md like source code: it requires validation, consistency checks, and protection against unreviewed modification. The difference is that source code fails loudly at compile time. CLAUDE.md fails silently at runtime, in production, usually at the worst moment.
Three failure modes threaten CLAUDE.md health:
- Conflict — Contradictory rules across global, project, and subdirectory files. The hierarchy resolves them mechanically, but often not the way you intended.
- Drift — Rules that were true when written but no longer match the codebase. Port numbers change. Tool names change. Conventions change. The rule stays.
- Bloat — Accumulated rules that are redundant, vague, or unreferenced. More rules does not mean better behavior. It means more surface area for contradiction.
II. When to Use
- After merging branches that touched CLAUDE.md independently
- When agent behavior changes unexpectedly (first suspect: CLAUDE.md conflict or stale rule)
- During periodic maintenance (weekly, or at convergence gates)
- Before onboarding a new agent or team member to verify the contract is coherent
- After applying learnings (reflect-and-learn) to verify no conflicts were introduced
- After a major refactor that changed file paths, port numbers, or tool names
Do not use this skill to write new CLAUDE.md rules. Use it to validate existing ones.
III. Workflow
Step 1: DISCOVER
Find all behavioral configuration files across the entire hierarchy.
Locations to check:
~/.claude/CLAUDE.md — global rules applied to all projects./CLAUDE.md — project root rules./<subdirectory>/CLAUDE.md — subdirectory-specific overrides./AGENTS.md — cross-tool compatibility file (can contradict CLAUDE.md silently)~/.claude/projects/<project-hash>/CLAUDE.md — project-specific agent memory overlays
Use glob and bash to find all CLAUDE.md and AGENTS.md files recursively. Report the full list before proceeding.
Step 2: PARSE
