maintaining-claude-code
Validate and improve Claude Code configurations (CLAUDE.md, skills, commands, hooks). Use when auditing config quality, checking skill discoverability, organizing .claude directory, or deciding which entity type to use.
When & Why to Use This Skill
The Maintaining Claude Code skill is a specialized utility designed to audit, organize, and optimize Claude Code configurations. It ensures that project-specific files like CLAUDE.md, custom skills, commands, and hooks are correctly structured and highly performant. By providing systematic validation and architectural guidance, it helps developers maintain a clean, discoverable, and efficient agentic environment, preventing configuration rot and improving AI response accuracy.
Use Cases
- Configuration Auditing: Use this skill to validate YAML syntax and ensure that skill descriptions follow the 'What + When' formula for better discoverability.
- Directory Organization: Clean up cluttered .claude directories by consolidating redundant skills and splitting large CLAUDE.md files into path-specific rules.
- Architectural Decision Making: Consult the built-in decision matrix to determine whether a new capability should be implemented as a Hook, Command, Skill, or MCP Server.
- Best Practices Enforcement: Identify and fix common anti-patterns such as vague descriptions, missing triggers, or overloaded skills that degrade agent performance.
| name | maintaining-claude-code |
|---|---|
| description | Validate and improve Claude Code configurations (CLAUDE.md, skills, commands, hooks). Use when auditing config quality, checking skill discoverability, organizing .claude directory, or deciding which entity type to use. |
Maintaining Claude Code
Validate, organize, and improve Claude Code configurations.
Modes of Operation
Audit Mode
Use when: Checking config quality, validating skills work
Checklist:
- CLAUDE.md: Specific, structured, actionable
- Skills: Valid YAML, good descriptions (What + When formula)
- Commands: Clear purpose, not duplicating skills
- Hooks: Proper exit codes, reasonable timeouts
Organize Mode
Use when: .claude directory is messy, too many similar skills
Guidelines:
- Split CLAUDE.md into rules when >150 lines
- Consolidate similar skills (don't have 3 "code review" skills)
- Use subdirectories in rules/ for large projects
Advise Mode
Use when: Deciding what entity type to create
Decision tree:
- Needs to run automatically before/after actions? -> Hook
- User explicitly triggers with /command? -> Command
- Claude should auto-detect and use? -> Skill
- Always-on behavioral guidance? -> CLAUDE.md
- Path-specific rules? -> .claude/rules/
Quick Reference
Entity Type Decision Matrix
| Need | Best Entity | Alternative |
|---|---|---|
| Global behavior guidelines | CLAUDE.md | Rules if >150 lines |
| Path-specific rules | .claude/rules/ | CLAUDE.md if universal |
| User-invoked workflows | Commands | Skill if auto-detection wanted |
| Auto-detected capabilities | Skills | Command if user should control |
| Pre/post action validation | Hooks | Nothing else does this |
| External API integration | MCP Servers | Bash calls if simple |
| Task-specific personas | Agents | Skills for simpler cases |
Skill Description Formula
<What it does>. Use when <trigger1>, <trigger2>, or <trigger3>.
Good: "Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction."
Bad: "Helps with documents"
YAML Validation
---on line 1 (required)name:max 64 charsdescription:max 1024 chars, must include triggers---before content
Common Anti-Patterns
- Vague descriptions: "Helps with stuff"
- Nested references: SKILL.md -> REF.md -> DETAILS.md
- Overloaded skills: Does 5 unrelated things
- Missing triggers: No "Use when..." clause
Validation Steps
- Check YAML syntax in all skills
- Verify descriptions include trigger phrases
- Ensure no duplicate capabilities across skills
- Confirm CLAUDE.md content won't quickly grow stale
- Check hooks have reasonable timeouts
Resources
See REFERENCE.md for detailed examples and troubleshooting.