claude-config-management
Use when configuring, maintaining, troubleshooting, or optimizing Claude Code extensions including skills, commands, hooks, MCP servers, or agents. Provides best practices and prevents common mistakes.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for configuring, maintaining, and optimizing Claude Code extensions. It streamlines the management of MCP servers, skills, hooks, and commands while ensuring optimal context usage and peak performance through proven best practices and anti-pattern prevention. It is an essential resource for developers looking to build stable, efficient, and scalable agentic workflows within the Claude ecosystem.
Use Cases
- Architecting Agent Capabilities: Use the Quick Decision Framework to determine whether a new feature should be implemented as a Skill, Command, Hook, or MCP server based on trigger requirements and domain expertise.
- Context and Token Optimization: Manage MCP server limits and token consumption (e.g., keeping active servers under 10) to prevent context exhaustion and maintain high response quality.
- Environment Troubleshooting: Resolve performance bottlenecks and slow startup times by utilizing diagnostic commands like /doctor and /context to audit project metadata and configuration files.
- Standardizing Team Workflows: Implement consistent project rules and personal overrides using the correct file hierarchy, including CLAUDE.md, .claude/settings.json, and .mcp.json.
- Preventing Common Configuration Errors: Avoid anti-patterns such as vague skill descriptions, overly complex commands, or expensive code style enforcement within CLAUDE.md.
| name | claude-config-management |
|---|---|
| description | Use when configuring, maintaining, troubleshooting, or optimizing Claude Code extensions including skills, commands, hooks, MCP servers, or agents. Provides best practices and prevents common mistakes. |
Claude Code Configuration Management
Critical Constraints
Context Budget: MCP servers consume tokens before you work. A single server with 20 tools can use 14,000+ tokens. Keep active servers under 10.
Precedence Rule: Deny rules always win over allow rules at any level. More specific settings override broader ones.
Performance Threshold: If startup exceeds 30 seconds, clean ~/.claude.json of old project metadata.
Quick Decision Framework
| I need to... | Use | Not |
|---|---|---|
| Enforce rules deterministically | Hook | Skill (probabilistic) |
| Provide domain expertise | Skill | Command (user-invoked) |
| Create user-triggered action | Command | Skill (auto-triggered) |
| Connect external service | MCP Server | Hook |
| Orchestrate multi-step tasks | Agent | Single command |
File Locations
| Content | Location |
|---|---|
| Project overview | CLAUDE.md (root) |
| Team settings | .claude/settings.json |
| Personal overrides | .claude/settings.local.json |
| MCP servers (team) | .mcp.json |
| Skills | .claude/skills/[name]/SKILL.md |
| Commands | .claude/commands/[name].md |
| Reference docs | .claude/docs/ |
Anti-Patterns to Avoid
Skills: Vague descriptions → Claude can't determine when to activate. Fix: Include trigger conditions.
Commands: Complex multi-step workflows → Belongs in skill. Fix: Keep commands simple (3-5 max).
Hooks: Complex inline commands → Hard to debug. Fix: Use script files.
MCP: Too many servers → Context exhaustion. Fix: Use McPick for selective enabling.
CLAUDE.md: Code style rules → Expensive enforcement. Fix: Use linters instead.
Verification Commands
/mcp # MCP server status
/doctor # Full diagnostics
/context # Context usage breakdown
claude mcp list # List configured servers
Maintenance Schedule
- Weekly: Review
/context, clear accumulated sessions - Monthly: Audit CLAUDE.md, check extension updates, clean ~/.claude.json
- Quarterly: Full audit, remove unused extensions, update team docs
Detailed Reference
For complete procedures, checklists, and troubleshooting:
→ Read .claude/docs/config-management-reference.md
For finding and evaluating new extensions:
→ Read .claude/docs/resource-discovery-reference.md or use /discover