playbooks

home / skills / trevors / dot-claude / maintaining-claude-code

maintaining-claude-code skill

/skills/maintaining-claude-code

This skill audits and improves Claude Code configurations, organizing CLAUDE.md, skills, commands, and hooks for reliable discoverability and quality.

npx playbooks add skill trevors/dot-claude --skill maintaining-claude-code

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.9 KB
---
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 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](REFERENCE.md) for detailed examples and troubleshooting.

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

FAQ

How do I choose between a skill and a command?

If Claude should auto-detect and run the capability, use a skill. If the user must explicitly trigger it, use a command. Prefer commands when manual control is important.

When should CLAUDE.md be split into rules?

Split when CLAUDE.md grows beyond about 150 lines or when rules need path-specific scoping; move per-path policies into .claude/rules/.