| name | claude-md-governance |
| description | Evaluate, repair, and verify CLAUDE.md quality governance for a repository. Use this skill when CLAUDE.md, .claude settings, hooks, memory, AI coding rules, or agent governance are discussed. |
CLAUDE.md Governance Skill
Use this skill to keep repository AI instructions short, enforceable, and safe.
Operating rules
- Treat CLAUDE.md as always-loaded context. Keep it short and global.
- Move long procedures into skills or docs, referenced by path from CLAUDE.md.
- Use local CLAUDE.md files or path-scoped rules for sensitive directories such as auth, billing, payments, migrations, MQ consumers, and infra.
- Use hooks and CI for deterministic enforcement; do not rely on reminders.
- Prefer conservative defaults. If a project-specific decision is unknown, create a clearly marked TODO and continue.
- After changing CLAUDE.md or governance files, run:
python scripts/claude_md_lint.py --policy .claude-governance/policy.json --output .claude-governance/score.json
python scripts/verify_claude_governance.py
Fix sequence
- Run the static linter.
- Fix hard failures first: excessive length, missing Do NOT introduce, missing hooks, sensitive directories without local rules.
- Rewrite vague rules into measurable rules.
- Replace long @imports with Context Map links unless the file is small and truly always needed.
- Add or update local CLAUDE.md files under sensitive modules.
- Run automated verification.
- Summarize score, hard failures, fixes, and remaining TODOs.
