Skill

user-config-management

Manages Claude Code user configs (~/.claude/, ~/.claude.json): storage cleanup, backup/restore, reset with MCP preservation, history/plans/sessions/stats, health audits.

Bash

VS Code

developer-tools

npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystem

Tool Access

This skill is limited to using the following tools:

ReadGlobGrepSkillBash

Preview

> **STOP - Before providing ANY response about Claude Code user configuration:**

Supporting Assets

references/backup-restore.mdreferences/command-inventory.mdreferences/known-structure.yamlreferences/reset-workflow.md

SKILL.md

Similar Skills

user-config

Manages Claude Code user config (~/.claude/) with actions for audit/status, backup/restore, cleanup sessions/agents/debug/logs, costs/storage/session-stats, history/transcript-search, plugin-reset, and more.

20 files7 tools

claude-ecosystem

claudit

Audits Claude Code configurations for best practices in skills, instructions, MCP servers, hooks, plugins, security, over-engineering, and context efficiency via file scans and focused checks. Invoke with /claudit [focus-area].

3 files8 tools

claudit

Claude How-To: Master Claude Code Features

Provides structured tutorials, templates, Mermaid diagrams, and learning path for Claude Code features: slash commands, memory, skills, subagents, MCP, hooks, plugins, checkpoints, CLI.

aradotso-trending-skills-37

Stats

Parent Repo Stars40

Parent Repo Forks6

Last CommitFeb 16, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

User Configuration Management

MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about Claude Code user configuration:

INVOKE docs-management skill 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), query docs-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