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.
Manages Claude Code user configuration (~/.claude/, ~/.claude.json) with commands for cleanup, backup, reset workflows, and health auditing. Use when users need to free storage, preserve MCP servers during resets, search history, or diagnose configuration issues.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-softwareThis skill is limited to using the following tools:
references/backup-restore.mdreferences/command-inventory.mdreferences/known-structure.yamlreferences/reset-workflow.mdSTOP - Before providing ANY response about Claude Code user configuration:
- INVOKE
docs-managementskill for official documentation- QUERY for the user's specific topic
- BASE all responses on official documentation + this skill's custom references
Skipping this step results in outdated or incorrect information.
Before responding, verify:
If ANY checkbox is unchecked, STOP and complete the missing steps.
Central authority for managing Claude Code's user configuration directories. This skill provides:
Architecture: Hybrid delegation - official docs via docs-management, custom workflows via skill references.
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:
Use these keywords when querying docs-management skill:
| 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" |
| Topic | Keywords |
|---|---|
| Retention Setting | "cleanupPeriodDays", "session retention", "auto-cleanup" |
| Session Cleanup | "sessions", "project sessions", "session files" |
| Debug Logs | "debug", "debug transcripts", "debugging" |
| Topic | Keywords |
|---|---|
| Storage Structure | "~/.claude", "storage directory", "claude folder" |
| Projects Directory | "projects", "project sessions", "session storage" |
| Plugins Directory | "plugins", "plugin cache", "installed plugins" |
What do you want to do?
/user-config:storage (was /check-claude-storage)/user-config:cleanup-sessions (was /cleanup-sessions)/user-config:cleanup-agents (was /cleanup-agents)/user-config:cleanup-debug (was /cleanup-debug)/user-config:prune (was /prune-cache)/user-config:prune --nuclear/user-config:backup/user-config:restore/user-config:reset - See reset-workflow.md/user-config:history/user-config:plans/user-config:audit/user-config:session-stats/user-config:mcp/user-config:reset-plugins - Complete plugin reset| 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 |
| 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.
All commands consolidated under /user-config:* namespace:
| 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 |
| 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.
These workflows are NOT in official documentation - they are custom features:
For users who want a fresh start but need to preserve MCP server configs.
Full guide: references/reset-workflow.md
Quick summary:
For full configuration backup and restore.
Full guide: references/backup-restore.md
Backup location: ~/.claude-backups/backup-YYYY-MM-DD-HHmmss/
Detect when Claude Code updates change the config structure.
Full guide: references/known-structure.yaml
Mechanism: Compare actual ~/.claude/ against known structure manifest.
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"
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
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
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/cleanupPeriodDays in settings.json:
Query docs-management: "cleanupPeriodDays", "session retention"
| Command | Default Retention |
|---|---|
| Cleanup commands | 7 days |
| Hook logs | 30 days |
| File history | Never auto-clean (dangerous) |
| 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 |
This skill provides validation criteria used by the user-config-auditor agent.
| 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 |
The user-config-auditor agent performs formal audits:
Custom References (skill-owned):
Official Documentation (via docs-management):
Date: 2025-12-30 Model: claude-opus-4-5-20251101
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.