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

Retention & Cleanup

Storage Locations

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)

~/ Root Files (3 Concepts)

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 Commands

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

Note: For official retention settings (like cleanupPeriodDays), query docs-management: "cleanupPeriodDays session retention". The defaults below are this plugin's command defaults, not Claude Code's official defaults.

Troubleshooting Quick Reference

Auditing Configuration

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

Audit Checks

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