user-config-management
SKILL.md
User Configuration Management
MANDATORY: Invoke docs-management First
STOP - 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.
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:
- Keyword registry for efficient docs-management queries
- Custom workflows not covered by official docs (reset, backup/restore, drift detection)
- Command inventory linking to existing cleanup commands
- 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?
All actions are invoked via the consolidated /user-config <action> skill:
- Check storage usage -> Run
/user-config storage - Clean up sessions -> Run
/user-config cleanup-sessions - Clean up agents -> Run
/user-config cleanup-agents - Clean up debug logs -> Run
/user-config cleanup-debug - Comprehensive cleanup -> Run
/user-config prune - Nuclear cleanup (everything) -> Run
/user-config prune --nuclear - Backup configuration -> Run
/user-config backup - Restore from backup -> Run
/user-config restore - Reset (preserve MCP) -> Run
/user-config reset- See reset-workflow.md - Search history -> Run
/user-config history - Manage plans -> Run
/user-config plans - Audit config health -> Run
/user-config audit - View session stats -> Run
/user-config session-stats - View MCP servers -> Run
/user-config mcp - Reset plugins (nuclear) -> Run
/user-config reset-plugins
Directory Structure Reference
~/.claude/ Directory (13 Concepts)
| Directory/File | Purpose | Cleanup Safe | Action |
|---|---|---|---|
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.
Action Inventory
All actions consolidated under the /user-config <action> skill:
Cleanup Actions
| Action | Purpose |
|---|---|
/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
| Action | Purpose |
|---|---|
/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
| Action | Purpose |
|---|---|
/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
| Action | Purpose |
|---|---|
/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
| Action | Purpose |
|---|---|
/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:
- Backup: Extract mcpServers from ~/.claude.json
- Backup: Copy settings.json (optional)
- User wipes ~/.claude/ and ~/.claude.json
- User relaunches Claude Code (creates fresh config)
- 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 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
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 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:
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), querydocs-management: "cleanupPeriodDays session retention". The defaults below are this plugin's command defaults, not Claude Code's official 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 actions |
| 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
Weekly Installs
8
Repository
melodic-softwar…-pluginsGitHub Stars
38
First Seen
Jan 24, 2026
Security Audits
Installed on
gemini-cli7
antigravity7
windsurf7
claude-code7
trae7
codex7