---

name: user-config-management description: Central authority for managing Claude Code user configuration directories (~/.claude/ and ~/.claude.json). Covers storage cleanup, backup/restore, reset workflows, MCP server preservation, history management, plan management, session statistics, and configuration health auditing. Delegates to docs-management skill for official documentation. Use when managing user config, cleaning up storage, backing up settings, resetting Claude Code, or auditing configuration health. allowed-tools: Read, Glob, Grep, Skill, Bash

User Configuration Management

MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about Claude Code user configuration:

1. INVOKE docs-management skill for official documentation
2. QUERY for the user's specific topic
3. BASE all responses on official documentation + this skill's custom references

Skipping this step results in outdated or incorrect information.

Verification Checkpoint

Before responding, verify:

• Did I invoke docs-management skill for official docs?
• Did I check this skill's references for custom workflows?
• Is my response based on official docs (settings, MCP) + skill references (reset, backup)?

If ANY checkbox is unchecked, STOP and complete the missing steps.

---

Overview

Central authority for managing Claude Code's user configuration directories. This skill provides:

1. Keyword registry for efficient docs-management queries
2. Custom workflows not covered by official docs (reset, backup/restore, drift detection)
3. Command inventory linking to existing cleanup commands
4. Cross-platform guidance for path handling

Architecture: Hybrid delegation - official docs via docs-management, custom workflows via skill references.

When to Use This Skill

Keywords: user config, ~/.claude, .claude.json, cleanup, storage, backup, restore, reset, MCP servers, history, plans, sessions, debug logs, prune, audit, drift detection

Use this skill when:

• Managing ~/.claude/ directory contents
• Cleaning up storage (sessions, agents, debug, cache)
• Backing up or restoring configuration
• Resetting Claude Code while preserving MCP servers
• Searching command history
• Managing plan files
• Viewing session statistics
• Auditing configuration health
• Detecting structure drift after updates

Keyword Registry for docs-management Queries

Use these keywords when querying docs-management skill:

Configuration Files

Topic	Keywords
Settings Overview	"settings", "settings.json", "configuration files"
User Settings	"user settings", "~/.claude/settings.json"
Global Config	".claude.json", "global config", "mcpServers"
MCP Servers	"MCP servers", "mcpServers", "user-level MCP"

Retention & Cleanup

Topic	Keywords
Retention Setting	"cleanupPeriodDays", "session retention", "auto-cleanup"
Session Cleanup	"sessions", "project sessions", "session files"
Debug Logs	"debug", "debug transcripts", "debugging"

Storage Locations

Topic	Keywords
Storage Structure	"~/.claude", "storage directory", "claude folder"
Projects Directory	"projects", "project sessions", "session storage"
Plugins Directory	"plugins", "plugin cache", "installed plugins"

Quick Decision Tree

What do you want to do?

1. Check storage usage -> Run /user-config:storage (was /check-claude-storage)
2. Clean up sessions -> Run /user-config:cleanup-sessions (was /cleanup-sessions)
3. Clean up agents -> Run /user-config:cleanup-agents (was /cleanup-agents)
4. Clean up debug logs -> Run /user-config:cleanup-debug (was /cleanup-debug)
5. Comprehensive cleanup -> Run /user-config:prune (was /prune-cache)
6. Nuclear cleanup (everything) -> Run /user-config:prune --nuclear
7. Backup configuration -> Run /user-config:backup
8. Restore from backup -> Run /user-config:restore
9. Reset (preserve MCP) -> Run /user-config:reset - See reset-workflow.md
10. Search history -> Run /user-config:history
11. Manage plans -> Run /user-config:plans
12. Audit config health -> Run /user-config:audit
13. View session stats -> Run /user-config:session-stats
14. View MCP servers -> Run /user-config:mcp
15. Reset plugins (nuclear) -> Run /user-config:reset-plugins - Complete plugin reset

Directory Structure Reference

~/.claude/ Directory (13 Concepts)

Directory/File	Purpose	Cleanup Safe	Command
projects/	Session files per project	Yes (old files)	/user-config:cleanup-sessions
debug/	Debug transcripts	Yes (old files)	/user-config:cleanup-debug
plugins/	Installed plugin cache	No (use /plugin)	/plugin uninstall
file-history/	Edit undo history	No (loses undo)	Never auto-clean
plans/	Saved execution plans	Yes (old files)	/user-config:plans
shell-snapshots/	Shell state captures	Yes	/user-config:prune
todos/	Todo list state	Yes (old files)	/user-config:prune
statsig/	Feature flag cache	Always safe	/user-config:prune
ide/	IDE lock files	Yes (stale)	/user-config:audit
session-env/	Session environment	Yes	/user-config:prune
settings.json	User settings	Never	Manual only
history.jsonl	Command history	Usually keep	/user-config:history
.credentials.json	OAuth tokens	Never backup	Manual only

~/ Root Files (3 Concepts)

File	Purpose	Backup Priority
.claude.json	Global config (mcpServers, OAuth, flags)	Critical (mcpServers)
CLAUDE.md	User-level instructions	High
.claudeignore	User-level ignore patterns	Medium

IMPORTANT: There is NO ~/.mcp.json file. User-scope MCP servers go in ~/.claude.json under the mcpServers field.

Command Inventory

All commands consolidated under /user-config:* namespace:

Cleanup Commands (Migrated)

New Command	Was	Purpose
/user-config:cleanup-agents	/cleanup-agents	Agent transcript cleanup (7d default)
/user-config:cleanup-debug	/cleanup-debug	Debug log cleanup (7d default)
/user-config:cleanup-sessions	/cleanup-sessions	Session file cleanup (7d default)
/user-config:prune	/prune-cache	Comprehensive cleanup (--nuclear)
/user-config:cleanup-hook-logs	/cleanup-hook-logs	Hook log cleanup (30d default)
/user-config:storage	/check-claude-storage	Storage analysis
/user-config:session-stats	/session-stats	Session statistics

New Commands

Command	Purpose	Priority
/user-config:status	Unified overview of all config	P0
/user-config:reset	Backup MCP -> Wipe -> Restore workflow	P0
/user-config:audit	Structure drift detection	P0
/user-config:backup	Full backup to ~/.claude-backups/	P1
/user-config:restore	Restore from backup	P1
/user-config:history	Search/export command history	P1
/user-config:plans	List/view/archive plan files	P1
/user-config:global	View/edit ~/.claude.json safely	P1
/user-config:mcp	List/export MCP server configs	P1
/user-config:reset-plugins	Complete plugin reset (cache + registry + settings)	P1

Backward Compatibility: Old command names work but show deprecation notice.

Custom Workflows (Skill-Owned)

These workflows are NOT in official documentation - they are custom features:

Reset Workflow (MCP Preservation)

For users who want a fresh start but need to preserve MCP server configs.

Full guide: references/reset-workflow.md

Quick summary:

1. Backup: Extract mcpServers from ~/.claude.json
2. Backup: Copy settings.json (optional)
3. User wipes ~/.claude/ and ~/.claude.json
4. User relaunches Claude Code (creates fresh config)
5. Restore: Inject mcpServers into new ~/.claude.json

Backup/Restore Workflow

For full configuration backup and restore.

Full guide: references/backup-restore.md

Backup location: ~/.claude-backups/backup-YYYY-MM-DD-HHmmss/

Drift Detection

Detect when Claude Code updates change the config structure.

Full guide: references/known-structure.yaml

Mechanism: Compare actual ~/.claude/ against known structure manifest.

Delegation Patterns

Standard Query Pattern

User asks: "How do I clean up old sessions?"

1. Check command inventory (this skill)
2. Direct to: /user-config:cleanup-sessions
3. If user needs more detail, query docs-management: "cleanupPeriodDays", "session retention"

Reset/Backup Pattern

User asks: "I want to reset Claude Code but keep my MCP servers"

1. Load this skill's references/reset-workflow.md
2. Query docs-management for: "mcpServers", ".claude.json"
3. Guide user through reset workflow

Troubleshooting Pattern

User reports: "Storage is using too much disk space"

1. Run /user-config:storage for analysis
2. Recommend specific cleanup commands based on results
3. If needed, query docs-management for retention settings

Cross-Platform Path Handling

All commands must handle paths cross-platform:

Python:

from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"

Bash:

CLAUDE_DIR="$HOME/.claude"
CLAUDE_JSON="$HOME/.claude.json"
BACKUP_DIR="$HOME/.claude-backups"

Never hardcode:

• C:\Users\USERNAME\.claude\
• /Users/USERNAME/.claude/
• /home/USERNAME/.claude/

Retention Settings

Official Setting (via docs-management)

cleanupPeriodDays in settings.json:

• Sessions inactive > N days deleted at startup
• Default: 30 days
• Setting to 0 = immediate deletion

Query docs-management: "cleanupPeriodDays", "session retention"

Command Defaults

Command	Default Retention
Cleanup commands	7 days
Hook logs	30 days
File history	Never auto-clean (dangerous)

Troubleshooting Quick Reference

Issue	Solution
Storage too large	Run /user-config:storage then cleanup commands
Lost MCP servers after reset	Use /user-config:reset workflow (backs up first)
Unknown files in ~/.claude	Run /user-config:audit for drift detection
Can't find old session	Use /user-config:history to search
Need to restore config	Use /user-config:restore from backup
"Another Claude process running"	/user-config:prune --nuclear clears stale locks

Auditing Configuration

This skill provides validation criteria used by the user-config-auditor agent.

Audit Checks

Category	Checks
JSON Validity	All .json files parse correctly
Orphaned Files	Sessions without projects, stale locks
Security	No exposed API keys in settings
Structure	Known vs unknown directories/files
Cross-References	Todos reference valid sessions

Related Agent

The user-config-auditor agent performs formal audits:

• Uses this skill's known-structure.yaml for drift detection
• Validates JSON syntax
• Checks for orphaned/stale files
• Generates structured audit reports

References

Custom References (skill-owned):

• known-structure.yaml - Structure manifest for drift detection
• reset-workflow.md - MCP preservation reset guide
• backup-restore.md - Backup/restore procedures
• command-inventory.md - Full command reference

Official Documentation (via docs-management):

• Query: "settings", "settings.json" - Settings structure
• Query: "mcpServers", ".claude.json" - MCP server configuration
• Query: "cleanupPeriodDays" - Retention settings

Version History

• v1.0.0 (2025-12-30): Initial release
  • Consolidated command namespace (user-config:*)
  • Reset workflow with MCP preservation
  • Drift detection manifest
  • Pure delegation for official docs
  • Custom references for plugin-specific features

---

Last Updated

Date: 2025-12-30 Model: claude-opus-4-5-20251101