| name | claude-md-guardian |
| model | sonnet |
| description | Produces a CLAUDE.md health report listing conflicts, redundancies, and stale rules across the global, project, and subdirectory hierarchy — and optionally installs a PreToolUse hook to block unauthorized modifications. Use when: "agent behavior is inconsistent", "just merged branches that touched CLAUDE.md", "onboarding a new agent", "after applying learnings", "weekly maintenance". |
| license | proprietary |
| category | system-health |
| triggers | ["agent behavior is inconsistent","merged branches that touched CLAUDE.md","onboarding a new agent","after applying learnings","weekly maintenance"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"context","type":"string","description":"Trigger context — branch merge, onboarding, weekly maintenance, or behavior inconsistency","required":false}] |
| outputs | [{"name":"health_report","type":"string","description":"CLAUDE.md health report listing conflicts, redundancies, and stale rules across global, project, and subdirectory hierarchy"}] |
CLAUDE.md Guardian
I. Philosophy
CLAUDE.md is the agent's behavioral contract. When rules drift, conflict, or
accumulate without review, agent behavior becomes unpredictable. The guardian
skill treats CLAUDE.md as a living document that requires the same rigor as
source code: validation, consistency checks, and protection against unreviewed
modification.
Three failure modes threaten CLAUDE.md health:
- Drift -- Rules added to one CLAUDE.md but not propagated to related files.
- Conflict -- Contradictory rules across global, project, and subdirectory files.
- Bloat -- Accumulated rules that are no longer relevant or are redundant.
Mechanical enforcement (hooks) prevents unauthorized modification. Periodic
audits catch semantic drift that mechanics cannot detect.
II. When to Use
- After applying learnings from
reflect-and-learn to verify no conflicts were introduced.
- During periodic maintenance (weekly or sprint boundaries).
- When agent behavior deviates unexpectedly (first suspect: CLAUDE.md conflict).
- Before onboarding a new team member or agent to a project.
- After merging branches that may have modified CLAUDE.md independently.
Do not use this skill for writing new CLAUDE.md rules (use reflect-and-learn
for correction-based rules, or edit directly). Do not use it for auditing
documentation broadly (use documentation-audit).
III. Workflow
Step 1 -- Inventory all CLAUDE.md files.
Locate every behavioral configuration file:
~/.claude/CLAUDE.md (global)./CLAUDE.md (project root)./subdirectory/CLAUDE.md (subdirectory overrides)./AGENTS.md (cross-tool compatibility)
Step 2 -- Extract and normalize rules.
Parse each file into discrete behavioral rules. Normalize phrasing to detect
semantic duplicates and contradictions. Flag:
- Duplicate rules across files (redundancy)
- Contradictory rules (conflict)
- Rules that reference deprecated tools, paths, or patterns (staleness)
Step 3 -- Check inheritance hierarchy.
CLAUDE.md files form a cascade: global < project < subdirectory. Verify:
- Subdirectory rules do not contradict project rules unintentionally
- Project rules do not repeat global rules unnecessarily
