user-config-management

Original：🇺🇸 English
Translated

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.

1installs
Sourcemelodic-software/claude-code-plugins
Added on

NPX Install

npx skill4agent add melodic-software/claude-code-plugins user-config-management

Tags

Translated version includes tags in frontmatter
claude-code-configconfig-backupstorage-cleanupmcp-server-managementconfig-auditing

SKILL.md Content

View Translation Comparison →

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

TopicKeywords
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

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

Storage Locations

TopicKeywords
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?
All actions are invoked via the consolidated 
/user-config <action>
skill:
  1. Check storage usage -> Run 
    /user-config storage
  2. Clean up sessions -> Run 
    /user-config cleanup-sessions
  3. Clean up agents -> Run 
    /user-config cleanup-agents
  4. Clean up debug logs -> Run 
    /user-config cleanup-debug
  5. Comprehensive cleanup -> Run 
    /user-config prune
  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

Directory Structure Reference

~/.claude/ Directory (13 Concepts)

Directory/FilePurposeCleanup SafeAction
projects/
Session files per projectYes (old files)
/user-config cleanup-sessions
debug/
Debug transcriptsYes (old files)
/user-config cleanup-debug
plugins/
Installed plugin cacheNo (use /plugin)
/plugin uninstall
file-history/
Edit undo historyNo (loses undo)Never auto-clean
plans/
Saved execution plansYes (old files)
/user-config plans
shell-snapshots/
Shell state capturesYes
/user-config prune
todos/
Todo list stateYes (old files)
/user-config prune
statsig/
Feature flag cacheAlways safe
/user-config prune
ide/
IDE lock filesYes (stale)
/user-config audit
session-env/
Session environmentYes
/user-config prune
settings.json
User settingsNeverManual only
history.jsonl
Command historyUsually keep
/user-config history
.credentials.json
OAuth tokensNever backupManual only

~/ Root Files (3 Concepts)

FilePurposeBackup Priority
.claude.json
Global config (mcpServers, OAuth, flags)Critical (mcpServers)
CLAUDE.md
User-level instructionsHigh
.claudeignore
User-level ignore patternsMedium
IMPORTANT: There is NO 
~/.mcp.json
file. User-scope MCP servers go in 
~/.claude.json
under the 
mcpServers
field.

Action Inventory

All actions consolidated under the 
/user-config <action>
skill:

Cleanup Actions

ActionPurpose
/user-config cleanup-agents
Agent transcript cleanup (7d default)
/user-config cleanup-debug
Debug log cleanup (7d default)
/user-config cleanup-sessions
Session file cleanup (7d default)
/user-config cleanup-hook-logs
Hook log cleanup (30d default)
/user-config prune
Comprehensive cleanup (--nuclear)

Analysis Actions

ActionPurpose
/user-config status
Unified overview of all config
/user-config storage
Storage analysis
/user-config session-stats
Session statistics
/user-config costs
API cost estimation
/user-config audit
Structure drift detection

Backup/Restore Actions

ActionPurpose
/user-config backup
Full backup to ~/.claude-backups/
/user-config restore
Restore from backup
/user-config reset
Backup MCP -> Wipe -> Restore workflow
/user-config reset-plugins
Complete plugin reset (cache + registry + settings)

Configuration Actions

ActionPurpose
/user-config global
View/edit ~/.claude.json safely
/user-config mcp
List/export MCP server configs
/user-config history
Search/export command history
/user-config plans
List/view/archive plan files

Session Analysis Actions

ActionPurpose
/user-config file-versions
Browse file edit history
/user-config compaction-review
Review compaction information loss
/user-config prompt-extract
Extract successful prompts
/user-config transcript-search
Search across session transcripts
/user-config retrospective
Session postmortem/retrospective

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

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

1. Check action 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

text
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

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

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

Cross-Platform Path Handling

All commands must handle paths cross-platform:
Python:
python
from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"
Bash:
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.
CommandDefault Retention
Cleanup commands7 days
Hook logs30 days
File historyNever auto-clean (dangerous)

Troubleshooting Quick Reference

IssueSolution
Storage too largeRun 
/user-config storage
then cleanup actions
Lost MCP servers after resetUse 
/user-config reset
workflow (backs up first)
Unknown files in ~/.claudeRun 
/user-config audit
for drift detection
Can't find old sessionUse 
/user-config history
to search
Need to restore configUse 
/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

CategoryChecks
JSON ValidityAll .json files parse correctly
Orphaned FilesSessions without projects, stale locks
SecurityNo exposed API keys in settings
StructureKnown vs unknown directories/files
Cross-ReferencesTodos 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