maintaining-claude-code_skill

Overview

This skill validates, organizes, and improves Claude Code configurations including CLAUDE.md, skills, commands, and hooks. It helps teams audit config quality, improve discoverability, and choose the right entity type for a given need. Use it to keep the .claude directory clean and reliable.

How this skill works

The skill inspects YAML skill files for required structure and length limits, checks CLAUDE.md for clarity and scope, and verifies hooks for exit codes and sensible timeouts. It identifies duplicate or overlapping capabilities, suggests consolidation or splitting of rules, and applies a decision tree to recommend whether to use a CLAUDE.md rule, skill, command, or hook.

When to use it

• Auditing config quality before a release or handoff
• Improving skill discoverability and consistent descriptions
• Organizing a messy or growing .claude directory
• Deciding whether to implement a skill, command, hook, or CLAUDE.md rule
• Validating hooks, timeouts, and exit-code behavior before deployment

Best practices

• Keep CLAUDE.md focused and split into rules when it exceeds ~150 lines
• Write skill descriptions with the “What it does. Use when …” formula and include trigger phrases
• Validate YAML: leading '---', name ≤64 chars, description ≤1024 chars, and a final '---' before content
• Consolidate near-duplicate skills instead of copying similar capabilities
• Use subdirectories under .claude/rules/ for large codebases to scope path-specific rules

Example use cases

• Run an audit to ensure all skills include explicit triggers and valid YAML before publishing
• Reorganize .claude by merging three overlapping code-review skills into one well-scoped skill
• Decide to implement a pre-commit hook for automated checks versus a user-invoked command for manual runs
• Split an oversized CLAUDE.md into per-path rules under .claude/rules/ for a monorepo
• Review hooks to ensure reasonable timeouts and correct exit codes before integrating CI