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.