User Configuration Management
Unified skill for managing Claude Code user configuration (~/.claude/ and ~/.claude.json). Consolidates all user-config operations into a single entry point with action-based routing.
Related Skill: Invoke the claude-ecosystem:user-config-management skill for the meta-level configuration authority, known-structure manifest, and docs-management delegation patterns.
Quick Decision Tree
What do you want to do?
| Intent | Action | Read-Only? |
|--------|--------|------------|
| Check config health at a glance | status | Yes |
| Deep health audit with drift detection | audit | Yes (unless --fix) |
| See storage breakdown and recommendations | storage | Yes |
| View session file counts and trends | session-stats | Yes |
| Estimate API costs and token usage | costs | Yes |
| Clean up old session files | cleanup-sessions | Destructive |
| Clean up old agent transcripts | cleanup-agents | Destructive |
| Clean up old debug files | cleanup-debug | Destructive |
| Clean up old hook log files | cleanup-hook-logs | Destructive |
| Comprehensive cleanup (all categories) | prune | Destructive |
| Backup config to ~/.claude-backups/ | backup | No (creates files) |
| Restore config from backup | restore | No (overwrites files) |
| Reset Claude Code preserving MCP servers | reset | Destructive |
| Nuclear plugin reset (cache+registry) | reset-plugins | Destructive |
| View/edit ~/.claude.json global config | global | Depends on mode |
| List/manage MCP server configurations | mcp | Depends on mode |
| Search/analyze command history | history | Yes (unless --clear) |
| List/view/archive plan files | plans | Depends on mode |
| Browse file edit history across sessions | file-versions | Yes (unless --restore) |
| Review compaction information loss | compaction-review | Yes |
| Extract successful prompts from sessions | prompt-extract | Yes |
| Search across session transcripts | transcript-search | Yes |
| Generate session retrospective/postmortem | retrospective | Yes |
Argument Routing Table
| Action | Arguments | Default Behavior | Reference |
|--------|-----------|------------------|-----------|
| audit | [--fix] [--verbose] | Full audit with summary report | audit.md |
| backup | [--include-history] [--include-sessions] | Backup essential config only | backup.md |
| cleanup-agents | [days] [--dry-run] [--all-projects] | Remove agent files >7 days, current project | cleanup-agents.md |
| cleanup-debug | [days] [--dry-run] | Remove debug files >7 days | cleanup-debug.md |
| cleanup-hook-logs | [days] [--dry-run] | Remove hook logs >30 days | cleanup-hook-logs.md |
| cleanup-sessions | [days] [--dry-run] [--all-projects] | Remove session files >7 days, current project | cleanup-sessions.md |
| compaction-review | [session-id] [--current] [--compare] | Review most recent compaction | compaction-review.md |
| costs | [--days N] [--project] [--breakdown] [--export FILE] | Summary of recent costs (30 days) | costs.md |
| file-versions | <file-path> [--list] [--diff VER] [--restore VER] | Show version summary for cwd | file-versions.md |
| global | [--view] [--edit SECTION] [--validate] | View config summary | global.md |
| history | <search-term> [--days N] [--stats] [--export FILE] [--clear] | Show recent history summary | history.md |
| mcp | [--list] [--export FILE] [--import FILE] [--add NAME] [--remove NAME] | Show MCP server summary | mcp.md |
| plans | [plan-name] [--list] [--archive] [--cleanup N] | List recent plans | plans.md |
| prompt-extract | [--successful-only] [--category CAT] [--days N] [--export FILE] | Extract all prompts (30 days) | prompt-extract.md |
| prune | [days] [--dry-run] [--all-projects] [--include-debug] [--include-todos] [--nuclear] | Comprehensive cleanup >7 days, current project | prune.md |
| reset | [--backup] [--restore] [--list-backups] | Interactive reset wizard | reset.md |
| reset-plugins | [--dry-run] [--include-marketplaces] [--force] | Clear all except marketplaces | reset-plugins.md |
| restore | [backup-name] [--list] [--mcp-only] [--dry-run] | Interactive selection from backups | restore.md |
| retrospective | [session-id] [--current] [--days N] | Analyze most recent session | retrospective.md |
| session-stats | [--all-projects] | Stats for current project | session-stats.md |
| status | (none) | Unified config overview | status.md |
| storage | [--verbose] | Storage analysis with recommendations | storage.md |
| transcript-search | <query> [--days N] [--project] [--regex] [--context N] | Search all projects, all time | transcript-search.md |
Common Argument Patterns
These patterns are shared across multiple actions:
| Pattern | Used By | Description |
|---------|---------|-------------|
| [days] | cleanup-agents, cleanup-debug, cleanup-sessions, prune | Remove files older than N days (non-negative integer) |
| --dry-run | cleanup-*, prune, reset-plugins, restore | Preview without making changes |
| --all-projects | cleanup-agents, cleanup-sessions, prune | Apply to all projects (default: current only) |
| --days N | costs, history, prompt-extract, transcript-search | Limit time range for analysis |
| --export FILE | costs, history, mcp, prompt-extract | Export results to file |
| --project | costs, transcript-search | Limit to current project |
Safety Classification
Read-Only Actions (Always Safe)
audit (without --fix), compaction-review, costs, file-versions (without --restore), prompt-extract, retrospective, session-stats, status, storage, transcript-search
Destructive Actions (Require Confirmation)
All destructive actions MUST use AskUserQuestion before deletion. Never delete files without explicit user confirmation.
| Action | What Gets Deleted | Reversible? |
|--------|-------------------|-------------|
| cleanup-agents | Agent transcript files (agent-*.jsonl) | No |
| cleanup-debug | Debug transcript files | No |
| cleanup-hook-logs | Hook log .jsonl files | No |
| cleanup-sessions | Session .jsonl files | No |
| prune | Sessions + agents + statsig + plans + optionally debug/todos/locks | No |
| reset | User must manually delete ~/.claude/ (skill only prepares backup) | Partially (backup) |
| reset-plugins | Plugin cache, registry, enabledPlugins setting | Partially (reinstall) |
| history --clear | Command history entries | No |
Write Actions (Create/Modify Files)
| Action | What Gets Written |
|--------|-------------------|
| backup | Creates backup in ~/.claude-backups/ |
| restore | Overwrites config files from backup |
| global --edit | Modifies ~/.claude.json |
| mcp --add/--remove/--import | Modifies ~/.claude.json mcpServers |
| plans --archive | Moves plan files to archive/ subdirectory |
Protected Files (Never Deleted)
These files are NEVER touched by any cleanup action:
| File | Reason |
|------|--------|
| ~/.claude/CLAUDE.md | User instructions |
| ~/.claude/settings.json | User settings |
| ~/.claude/settings.local.json | Local settings |
| ~/.claude/.credentials.json | OAuth tokens (never backup either) |
| ~/.claude/history.jsonl | Command history (use history --clear explicitly) |
| ~/.claude/plugins/ | Installed plugins (use /plugin uninstall) |
| ~/.claude/file-history/ | Edit undo history (losing this removes /rewind capability) |
| ~/.claude/commands/ | User commands |
| ~/.claude/skills/ | User skills |
| ~/.claude/agents/ | User agents |
| ~/.claude/hooks/ | User hooks |
Cross-Platform Path Handling
All actions handle paths cross-platform:
Python: Use pathlib.Path.home() / ".claude" -- never hardcode OS-specific paths.
Bash: Use $HOME/.claude -- works on macOS, Linux, and Git Bash on Windows.
Project path encoding: pwd | sed 's/[\/:]/-/g' | sed 's/^-//'
Execution
Step 1: Parse Action
Extract the action from $ARGUMENTS:
ACTION = first non-flag argument (audit, backup, cleanup-agents, etc.)
REMAINING_ARGS = everything after the action
If no action provided or action is unrecognized, show the Quick Decision Tree above and ask user to specify an action.
Step 2: Load Reference
Load the detailed reference file for the action from references/{action}.md. The reference contains the complete operational instructions, workflows, code examples, and output formats.
Step 3: Execute
Follow the instructions in the reference file, passing REMAINING_ARGS as the action's arguments.