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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill is a specialized utility designed to audit, organize, and optimize Claude Code configurations. It ensures that project-specific instructions (CLAUDE.md), custom skills, commands, and hooks are correctly formatted, highly discoverable, and architecturally sound. By streamlining the .claude directory, it helps developers maintain a high-performance AI agent environment that is both scalable and easy to manage.

Use Cases

  • Configuration Auditing: Use this to validate the quality of CLAUDE.md and ensure that all skills follow the required YAML syntax and 'What + When' description formula.
  • Architectural Decision Making: Leverage the built-in decision matrix to determine whether a new capability should be implemented as a Hook, Command, Skill, or a global rule.
  • Project Refactoring: Clean up messy .claude directories by consolidating redundant skills and splitting oversized CLAUDE.md files into modular rules for better context management.
  • Discoverability Optimization: Improve how Claude auto-detects capabilities by refining trigger phrases and eliminating vague descriptions in custom skill files.
namemaintaining-claude-code
descriptionValidate 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 chars
  • description: 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

  1. Check YAML syntax in all skills
  2. Verify descriptions include trigger phrases
  3. Ensure no duplicate capabilities across skills
  4. Confirm CLAUDE.md content won't quickly grow stale
  5. Check hooks have reasonable timeouts

Resources

See REFERENCE.md for detailed examples and troubleshooting.