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.

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

When & Why to Use This Skill

This Claude skill is a comprehensive configuration and optimization engine designed for managing Claude Code environments. It provides expert guidance on orchestrating MCP servers, skills, hooks, and agents, focusing on maximizing performance through strict context budget management and the elimination of common architectural anti-patterns.

Use Cases

  • Optimizing agent responsiveness by managing token usage and limiting active MCP servers to prevent context exhaustion.
  • Architecting custom workflows by selecting the correct extension type (Hooks, Skills, or Commands) based on deterministic vs. probabilistic requirements.
  • Troubleshooting environment performance issues and slow startup times through systematic diagnostics and metadata cleanup.
  • Standardizing team-wide development environments using structured configuration files like .mcp.json and .claude/settings.json.
nameclaude-config-management
descriptionUse 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