user-config-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

User Configuration Management

用户配置管理

MANDATORY: Invoke docs-management First

强制要求：先调用docs-management技能

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.

注意 - 在提供任何关于Claude Code用户配置的响应之前：
调用
docs-management
技能获取官方文档
查询用户的具体主题

基于官方文档 + 本技能的自定义参考内容生成所有响应
跳过此步骤会导致信息过时或错误。

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.

在响应前，请验证：

我是否调用了docs-management技能获取官方文档？
我是否查看了本技能的参考内容以了解自定义工作流？
我的响应是否基于官方文档（设置、MCP）+ 技能参考内容（重置、备份）？

如果有任何复选框未勾选，请停止操作并完成缺失的步骤。

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.

管理Claude Code用户配置目录的核心工具。本技能提供：

关键词注册表，用于高效查询docs-management
官方文档未涵盖的自定义工作流（重置、备份/恢复、漂移检测）
命令清单，关联现有清理命令
跨平台路径处理指南

**架构：**混合委托模式 - 官方文档通过docs-management获取，自定义工作流通过技能参考内容获取。

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

关键词： user config, ~/.claude, .claude.json, cleanup, storage, backup, restore, reset, MCP servers, history, plans, sessions, debug logs, prune, audit, drift detection

在以下场景使用本技能：

管理~/.claude/目录内容
清理存储（会话、Agent、调试日志、缓存）
备份或恢复配置
重置Claude Code同时保留MCP服务器
搜索命令历史
管理计划文件
查看会话统计
审计配置健康状况
检测更新后的结构漂移

Keyword Registry for docs-management Queries

docs-management查询关键词注册表

Use these keywords when querying docs-management skill:

查询docs-management技能时使用以下关键词：

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"

主题	关键词
设置概述	"settings", "settings.json", "configuration files"
用户设置	"user settings", "~/.claude/settings.json"
全局配置	".claude.json", "global config", "mcpServers"
MCP服务器	"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"

主题	关键词
保留设置	"cleanupPeriodDays", "session retention", "auto-cleanup"
会话清理	"sessions", "project sessions", "session files"
调试日志	"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"

主题	关键词
存储结构	"~/.claude", "storage directory", "claude folder"
项目目录	"projects", "project sessions", "session storage"
插件目录	"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
```

你想要执行什么操作？

所有操作均通过整合的

/user-config <action>

技能调用：

检查存储使用情况 -> 运行
```
/user-config storage
```
清理会话 -> 运行
```
/user-config cleanup-sessions
```
清理Agent -> 运行
```
/user-config cleanup-agents
```
清理调试日志 -> 运行
```
/user-config cleanup-debug
```
全面清理 -> 运行
```
/user-config prune
```
深度清理（所有内容） -> 运行
```
/user-config prune --nuclear
```
备份配置 -> 运行
```
/user-config backup
```
从备份恢复 -> 运行
```
/user-config restore
```
重置（保留MCP） -> 运行
```
/user-config reset
```
- 查看reset-workflow.md
搜索历史记录 -> 运行
```
/user-config history
```
管理计划 -> 运行
```
/user-config plans
```
审计配置健康状况 -> 运行
```
/user-config audit
```
查看会话统计 -> 运行
```
/user-config session-stats
```
查看MCP服务器 -> 运行
```
/user-config mcp
```
重置插件（深度） -> 运行
```
/user-config reset-plugins
```

Directory Structure Reference

目录结构参考

~/.claude/ Directory (13 Concepts)

~/.claude/目录（13个模块）

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

目录/文件	用途	是否可安全清理	操作命令
`projects/`	按项目划分的会话文件	是（旧文件）	`/user-config cleanup-sessions`
`debug/`	调试记录	是（旧文件）	`/user-config cleanup-debug`
`plugins/`	已安装插件缓存	否（使用/plugin命令）	`/plugin uninstall`
`file-history/`	编辑撤销历史	否（会丢失撤销功能）	切勿自动清理
`plans/`	已保存的执行计划	是（旧文件）	`/user-config plans`
`shell-snapshots/`	Shell状态捕获	是	`/user-config prune`
`todos/`	待办事项列表状态	是（旧文件）	`/user-config prune`
`statsig/`	功能标志缓存	始终可安全清理	`/user-config prune`
`ide/`	IDE锁定文件	是（过期文件）	`/user-config audit`
`session-env/`	会话环境	是	`/user-config prune`
`settings.json`	用户设置	绝不	仅手动操作
`history.jsonl`	命令历史	通常保留	`/user-config history`
`.credentials.json`	OAuth令牌	绝不备份	仅手动操作

~/ Root Files (3 Concepts)

~/根目录文件（3个模块）

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.

文件	用途	备份优先级
`.claude.json`	全局配置（mcpServers、OAuth、标志）	极高（mcpServers）
`CLAUDE.md`	用户级说明文档	高
`.claudeignore`	用户级忽略规则	中

重要提示： 不存在

~/.mcp.json

文件。用户级MCP服务器配置需放在

~/.claude.json

的

mcpServers

字段中。

Action Inventory

操作清单

All actions consolidated under the

/user-config <action>

skill:

所有操作均整合在

/user-config <action>

技能下：

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)

操作	用途
`/user-config cleanup-agents`	Agent记录清理（默认7天）
`/user-config cleanup-debug`	调试日志清理（默认7天）
`/user-config cleanup-sessions`	会话文件清理（默认7天）
`/user-config cleanup-hook-logs`	Hook日志清理（默认30天）
`/user-config prune`	全面清理（支持--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

操作	用途
`/user-config status`	所有配置的统一概览
`/user-config storage`	存储分析
`/user-config session-stats`	会话统计
`/user-config costs`	API成本估算
`/user-config audit`	结构漂移检测

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)

操作	用途
`/user-config backup`	完整备份至~/.claude-backups/
`/user-config restore`	从备份恢复
`/user-config reset`	备份MCP -> 清理 -> 恢复工作流
`/user-config reset-plugins`	完全重置插件（缓存 + 注册表 + 设置）

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

操作	用途
`/user-config global`	安全查看/编辑~/.claude.json
`/user-config mcp`	列出/导出MCP服务器配置
`/user-config history`	搜索/导出命令历史
`/user-config plans`	列出/查看/归档计划文件

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

操作	用途
`/user-config file-versions`	浏览文件编辑历史
`/user-config compaction-review`	查看压缩导致的信息丢失
`/user-config prompt-extract`	提取成功的提示词
`/user-config transcript-search`	跨会话记录搜索
`/user-config retrospective`	会话复盘/回顾

Custom Workflows (Skill-Owned)

自定义工作流（技能专属）

These workflows are NOT in official documentation - they are custom features:

以下工作流未包含在官方文档中，属于自定义功能：

Reset Workflow (MCP Preservation)

重置工作流（保留MCP）

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

适用于想要重新开始但需要保留MCP服务器配置的用户。

完整指南： references/reset-workflow.md

快速摘要：

备份：从~/.claude.json中提取mcpServers
备份：复制settings.json（可选）
用户清理~/.claude/和~/.claude.json
用户重新启动Claude Code（生成新配置）
恢复：将mcpServers注入新的~/.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/

用于完整配置的备份与恢复。

完整指南： references/backup-restore.md

备份位置：

~/.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.

检测Claude Code更新是否改变了配置结构。

完整指南： references/known-structure.yaml

机制： 将实际的~/.claude/目录与已知结构清单进行对比。

Delegation Patterns

委托模式

Standard Query Pattern

标准查询模式

text

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"

text

用户提问："如何清理旧会话？"

1. 查看操作清单（本技能）
2. 引导至：/user-config cleanup-sessions
3. 如果用户需要更多细节，查询docs-management："cleanupPeriodDays", "session retention"

Reset/Backup Pattern

重置/备份模式

text

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

text

用户提问："我想重置Claude Code但保留我的MCP服务器"

1. 加载本技能的references/reset-workflow.md
2. 查询docs-management获取："mcpServers", ".claude.json"
3. 引导用户完成重置工作流

Troubleshooting Pattern

故障排除模式

text

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

text

用户反馈："存储占用过大"

1. 运行/user-config storage进行分析
2. 根据结果推荐具体的清理操作
3. 如有需要，查询docs-management获取保留设置

Cross-Platform Path Handling

跨平台路径处理

All commands must handle paths cross-platform:

Python:

python

from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"

Bash:

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/
```

所有命令必须支持跨平台路径处理：

Python：

python

from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"

Bash：

bash

CLAUDE_DIR="$HOME/.claude"
CLAUDE_JSON="$HOME/.claude.json"
BACKUP_DIR="$HOME/.claude-backups"

切勿硬编码：

```
C:\Users\USERNAME\.claude\
```
```
/Users/USERNAME/.claude/
```
```
/home/USERNAME/.claude/
```

Retention Settings

保留设置

Official Setting (via docs-management)

官方设置（通过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"

settings.json中的**

cleanupPeriodDays

**：

超过N天未活跃的会话会在启动时删除
默认值：30天
设置为0 = 立即删除

查询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)

注意： 关于官方保留设置（如
cleanupPeriodDays
），请查询
docs-management: "cleanupPeriodDays session retention"
。以下默认值是本插件的命令默认值，而非Claude Code的官方默认值。

命令	默认保留时长
清理命令	7天
Hook日志	30天
文件历史	绝不自动清理（存在风险）

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

问题	解决方案
存储占用过大	运行 `/user-config storage` 分析后执行清理操作
重置后丢失MCP服务器	使用 `/user-config reset` 工作流（先备份）
~/.claude中存在未知文件	运行 `/user-config audit` 进行漂移检测
找不到旧会话	使用 `/user-config history` 搜索
需要恢复配置	使用 `/user-config restore` 从备份恢复
"另一个Claude进程正在运行"	`/user-config prune --nuclear` 清理过期锁定

Auditing Configuration

配置审计

This skill provides validation criteria used by the

user-config-auditor

agent.

本技能提供

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

类别	检查内容
JSON有效性	所有.json文件可正确解析
孤立文件	无项目关联的会话、过期锁定文件
安全性	设置中无暴露的API密钥
结构	对比已知与未知目录/文件
交叉引用	待办事项关联有效的会话

Related Agent

关联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

user-config-auditor

Agent执行正式审计：

使用本技能的known-structure.yaml进行漂移检测
验证JSON语法
检查孤立/过期文件
生成结构化审计报告

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

自定义参考内容（技能专属）：

known-structure.yaml - 用于漂移检测的结构清单
reset-workflow.md - 保留MCP的重置指南
backup-restore.md - 备份/恢复流程
command-inventory.md - 完整命令参考

官方文档（通过docs-management获取）：

查询："settings", "settings.json" - 设置结构
查询："mcpServers", ".claude.json" - MCP服务器配置
查询："cleanupPeriodDays" - 保留设置

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

v1.0.0（2025-12-30）：初始版本
- 整合命令命名空间（user-config:*）
- 保留MCP的重置工作流
- 漂移检测清单
- 官方文档纯委托模式
- 插件专属功能的自定义参考内容

Last Updated

最后更新

Date: 2025-12-30 Model: claude-opus-4-5-20251101

**日期：**2025-12-30 **模型：**claude-opus-4-5-20251101