health-check

/health:check

Claude Code 健康诊断的统一入口。运行环境检查（插件注册表、设置、钩子、MCP 服务、SessionStart 可执行性、pre-commit 有效性、权限覆盖范围、市场注册情况）以及可选的深入审计，并将 --fix 路由到相应的内部工作流。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方式……
运行 Claude Code 诊断	查看原始设置（对 settings.json 使用 Read）
排查插件注册表问题	手动检查市场元数据
审计插件是否适用于项目	安装特定插件（使用 /plugin install）
检查技能的 Agentic 优化质量	编辑单个已知技能
通过 --fix 一站式修复注册表／技术栈／Agentic 问题	对单个文件进行精确的局部修改

上下文

• 当前项目：!pwd
• 项目设置是否存在：!find . -maxdepth 2 -path '*/.claude/settings.json'
• 本地设置是否存在：!find . -maxdepth 2 -path '*/.claude/settings.local.json'

参数

从 $ARGUMENTS 中解析以下参数：

参数	说明
--scope=<all|registry|stack|agentic|runtime|usage>	要运行的审计。默认为 all。
--fix	修复检查发现的问题（会提示确认）。
--dry-run	预览修复，不修改文件。
--verbose	包含详细诊断信息。

范围说明：

范围	涵盖内容
registry	插件注册表健康状况（孤立的 projectPath、过期的 enabledPlugins、注册表与设置之间的偏差）
stack	已启用插件与检测到的项目技术栈
agentic	技能／命令／Agent 的 Agentic 优化合规性
runtime	~/.claude.json 膨胀情况（失效的 projects[]、失效的 githubRepoPaths[*]、孤立的 disabledMcpServers、重复的 MCP 命名）。只读审计。
usage	从 ~/.claude/projects/*/*.jsonl 挖掘会话遥测数据，查找从未触发和处于休眠状态的技能及插件 Agent。只读，倾向于基于本地数据（历史记录不足时会跳过）。
all	环境检查 + 全部五项审计

执行

执行此诊断路由器。未提供 --scope 时，默认范围为 all。

步骤 1：运行环境检查（始终运行）

无论 --scope 如何设置，都会运行环境检查。检查内容包括 Claude Code 安装和当前项目 .claude/ 目录的基本健康状况。

1a. 核心环境脚本

bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)"

解析各脚本输出中的 STATUS= 和 ISSUES:。如果 $ARGUMENTS 中设置了 --verbose，则传入该参数。

如果 check-settings.sh 输出 PROJECT_DIR_RESOLVED=<path>，表示工作区根目录下没有 .claude/，但在下一层找到一个嵌套的 */.claude/settings.json（父工作区／monorepo 布局）。在报告中注明解析出的路径，让用户知道检查的是哪个配置。如果输出 PROJECT_DIR_HINT=<msg>，则显示该提示——这表示找到了多个嵌套配置，用户应使用 --project-dir 重新运行，以指定目标配置。

1b. SessionStart 冒烟测试

检查 scripts/install_pkgs.sh（或 .claude/settings.json 中 SessionStart 钩子注册的任何脚本）是否可执行，并且在远程和本地上下文中均能正常退出。

1. 从 .claude/settings.json 中定位 SessionStart 钩子命令（查找 command 字段）。
2. 如果找到脚本，则运行：

   CLAUDE_CODE_REMOTE=true bash <script-path>
   

   捕获退出代码。预期值：0。
3. 再运行一次以验证幂等性——预期值：0。
4. 关闭远程保护后运行：

   CLAUDE_CODE_REMOTE=false bash <script-path>
   

   预期值：0（通常为空操作）。
5. 报告：
   • OK：三次运行的退出代码均为 0
   • WARN：脚本存在，但未在 settings.json 钩子中注册
   • ERROR：脚本以非零状态退出，或钩子中引用的脚本不存在

1c. Pre-commit 配置验证器

如果 .pre-commit-config.yaml 存在：

pre-commit validate-config .pre-commit-config.yaml

报告：

• OK：退出码为 0（配置有效）
• WARN：未安装 pre-commit — 跳过检查，建议运行 pip install pre-commit
• ERROR：退出码非零 — 显示验证错误

1d. 权限覆盖检查

将项目文件中引用的工具与 .claude/settings.json 中的 permissions.allow 进行比较。

1. 从 .claude/settings.json 读取 permissions.allow。从每个 Bash(<prefix>:*) 条目中提取命令前缀。
2. 扫描以下文件中的工具调用：
   • justfile / Justfile — recipe 行中的命令
   • Makefile — recipe 行中的 shell 命令
   • .pre-commit-config.yaml — entry: 字段
3. 对于在项目文件中找到的每个工具：
   • 如果 permissions.allow 中不存在匹配的 Bash(<tool>:*) 条目，则标记为 MISSING
4. 对于 permissions.allow 中的每个 Bash(<tool>:*) 条目：
   • 如果在任何项目文件中都找不到该工具，则标记为 UNUSED（仅供参考，不属于错误）

评分：

• OK：没有缺失的权限
• WARN：缺失 1–3 项权限
• ERROR：缺失 4 项或更多权限

1e. Marketplace 注册检查

本地 marketplace 键（由 claude marketplace add <name> 设置）由用户自行选择，并因安装而异（通常为 laurigates-claude-plugins，有时为 claude-plugins）。应通过稳定的 source.repo 识别 marketplace，而不是使用硬编码的本地键。

1. 读取 .claude/settings.json。
2. 扫描 extraKnownMarketplaces 下的所有条目，找到 source.repo 等于 "laurigates/claude-plugins" 的条目。将该条目的键记为 $MP_KEY。
3. 检查 enabledPlugins 中是否至少有一个键以 @$MP_KEY 为后缀。
4. 报告：
   • OK：两项检查均通过
   • WARN：enabledPlugins 中没有 @$MP_KEY 条目（marketplace 已注册，但未启用任何插件）
   • ERROR：不存在 source.repo = laurigates/claude-plugins 的 extraKnownMarketplaces 条目（运行 /configure:claude-plugins --fix 添加）

用于验证或修复脚本的 jq 参考片段：

MP_KEY=$(jq -r '.extraKnownMarketplaces // {} | to_entries | map(select(.value.source.repo == "laurigates/claude-plugins")) | .[0].key // empty' .claude/settings.json)
if [ -z "$MP_KEY" ]; then
  echo "ERROR: no extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins"
else
  jq -e --arg k "@$MP_KEY" '.enabledPlugins // {} | to_entries | map(select(.key | endswith($k))) | length > 0' .claude/settings.json >/dev/null \
    && echo "OK: marketplace enrolled as $MP_KEY with enabled plugins" \
    || echo "WARN: marketplace $MP_KEY enrolled but no @${MP_KEY} entries in enabledPlugins"
fi

第 2 步：运行特定范围的审计

对于 --scope=registry 或 all：

bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/check-registry.sh" \
  --home-dir "$HOME" --project-dir "$(pwd)"

解析 STATUS=、PLUGIN_COUNT=、ORPHANED_ENTRIES=、STALE_ENABLED_ENTRIES= 和 ISSUES:。

对于 --scope=stack 或 all：按照内部 health-audit 技能中的技术栈审计步骤执行（参见 ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md 及其 REFERENCE.md）。

对于 --scope=agentic 或 all：按照内部 health-agentic-audit 技能中的技能质量审计步骤执行（参见 ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md 及其 REFERENCE.md）。

对于 --scope=runtime 或 all：

bash "${CLAUDE_SKILL_DIR}/scripts/check-runtime.sh" --home-dir "$HOME" --project-dir "$(pwd)"

解析 STATUS=、RUNTIME_SIZE_BYTES=、PROJECTS_TOTAL=、PROJECTS_DEAD=、GH_PATHS_TOTAL=、GH_PATHS_DEAD=、ORPHAN_DISABLED_MCP=、DUPLICATE_MCP=、CLEANUP_SUGGESTED= 和 ISSUES:。传入 --verbose 可列出每个失效路径／孤立服务（默认情况下，每类问题汇总为一项，以保持输出简洁）。

runtime 范围会审计 ~/.claude.json——这个 harness 状态文件会随每次会话增长，且不会自动清理。它会报告四类膨胀项：失效的 projects[] 键、失效的 githubRepoPaths[*] worktree 路径、孤立的 disabledMcpServers[] 条目，以及裸名称与带命名空间的重复 MCP 名称。此审计为只读：它会打印建议的 jq 筛选器，供操作者关闭其他 Claude Code 会话后手动运行。

并发写入警告。 harness 会在会话结束时重写 ~/.claude.json。在执行审计建议的清理操作前，请关闭所有其他 Claude Code 会话；否则，运行中会话的内存状态会在下次写入文件时覆盖你的修改。自动化清理写入不在此审计范围内。

对于 --scope=usage 或 all：

bash "${CLAUDE_SKILL_DIR}/scripts/check-usage.sh" --home-dir "$HOME" --project-dir "$(pwd)"

解析 STATUS=、HISTORY_AVAILABLE=、TRANSCRIPTS_SCANNED=、SKILLS_ENABLED=、SKILLS_FIRED=、SKILLS_NEVER_FIRED=、SKILLS_DORMANT=、AGENTS_ENABLED=、AGENTS_FIRED=、AGENTS_NEVER_FIRED=、AGENTS_DORMANT=、SCHEMA_DRIFT_SUSPECTED= 和 ISSUES:。传入 --verbose 可列出每个从未触发／休眠的技能和 Agent（默认情况下，每类汇总为一行问题）。传入 --window-days N 可更改休眠阈值（默认为 30 天）。

usage 范围会检索本地会话记录（~/.claude/projects/*/*.jsonl），以判断技能和 Agent 的调用时效性：从未触发的技能／Agent（已安装，但历史记录中调用次数为零）以及休眠的技能／Agent（上次调用距今超过指定时间窗口）。Agent 调用记录取自以 subagent_type 为键的 Agent／Task tool_use 事件。发现结果是供审查的参考候选项，而非删除清单——技能或 Agent 即使很少需要，也可能是合适的（例如用于恢复、迁移，或由父技能控制、按需调用的子 Agent）。此审计为只读（不支持 --fix）。

此范围不会读取 ~/.claude.json 中的 pluginUsage.usageCount，也不得开始读取。 该计数器统计的是 hook 触发次数，与技能／Agent／命令的交付次数相同，因此它反映的是插件的 hook 触发频率，而非使用情况——参见 .claude/rules/plugin-usage-telemetry.md。检索会话记录可提供交付信号；runtime 范围使用 ~/.claude.json 与此无关（仅用于检查文件膨胀）。

偏向本地环境。 会话历史保存在本地且长期留存，因此在远程／Web 沙盒中，此范围几乎没有用处（全新克隆仅有 ≤1 份会话记录）。如果会话记录少于两份，它会输出 STATUS=SKIP 和 HISTORY_AVAILABLE=false，而不是报告每个技能都从未触发。如果 TRANSCRIPTS_SCANNED>0，但解析出的工具调用为零，它会输出 STATUS=WARN TYPE=schema_drift（会话记录的 JSON 结构已更改），而不是错误地报告所有技能都从未触发。

步骤 3：报告检查结果

按范围汇总报告：

1. 环境 — 插件/设置/钩子/MCP 状态及数量、SessionStart 冒烟测试、pre-commit 有效性、权限覆盖情况、市场登记情况
2. 注册表 — 孤立的 projectPath 条目、过时的 enabledPlugins 键、注册表与设置之间的差异
3. 技术栈 — 检测到的技术栈，以及相关/不相关/缺失插件建议
4. Agentic — 缺少优化表格的技能、裸 CLI 命令、过时的审查
5. 运行时 — ~/.claude.json 大小、失效的项目/githubRepoPaths、孤立的 orphaned disabledMcpServers、重复的 MCP 命名（只读——无 --fix 路径）
6. 使用情况 — 根据会话遥测数据识别从未触发和休眠的技能（只读——无 --fix 路径；历史记录不足时跳过）

使用 STATUS= 指示符（OK/WARN/ERROR），并统计各范围的问题数量。包含汇总表：

检查项	状态	问题
插件注册表	OK/WARN/ERROR	...
设置文件	OK/WARN/ERROR	...
钩子配置	OK/WARN/ERROR	...
MCP 服务	OK/WARN/ERROR	...
SessionStart 冒烟测试	OK/WARN/ERROR	...
Pre-commit 配置	OK/WARN/ERROR/SKIP	...
权限覆盖情况	OK/WARN/ERROR	...
市场登记情况	OK/WARN/ERROR	...
注册表审计	OK/WARN/ERROR	...
技术栈审计	OK/WARN/ERROR	...
Agentic 审计	OK/WARN/ERROR	...
运行时审计	OK/WARN/ERROR	...
使用情况审计	OK/WARN/ERROR/SKIP	...

完整的报告模板请参阅 REFERENCE.md。

步骤 4：应用修复（如果指定了 --fix）

如果指定了 --fix：

1. 如果指定了 --scope=all，且多个范围都有检查结果，请使用 AskUserQuestion 让用户选择要修复的范围（多选：registry、stack、agentic）。

2. 对每个选定的范围，委派执行：

   范围	委派给
   registry	bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"（指定 --dry-run 时传入该参数）
   stack	按照 ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md（步骤 6）中的 --fix 流程执行
   agentic	按照 ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md（步骤 6）中的 --fix 流程执行

3. 解析各脚本的输出（STATUS=、REMOVED_COUNT=、MESSAGE=、RESTART_REQUIRED=），并报告发生的更改。

4. 如果任何修复报告 RESTART_REQUIRED=true，请提醒用户重启 Claude Code。

步骤 5：验证

重新运行相关检查，并确认问题数量已减少。

Agentic 优化

情境	命令
全面扫描	/health:check
仅检查注册表	/health:check --scope=registry
仅检查技术栈相关性	/health:check --scope=stack
仅进行 Agentic 审计	/health:check --scope=agentic
审计运行时状态（~/.claude.json）	/health:check --scope=runtime
使用情况遥测（从未触发/休眠的技能）	/health:check --scope=usage
使用自定义休眠期限进行使用情况检查	bash check-usage.sh --window-days 60 --verbose
修复所有问题（交互式）	/health:check --fix
预览修复内容（试运行）	/health:check --fix --dry-run
详细诊断	/health:check --verbose
检查插件注册表是否存在	find ~/.claude/plugins -name 'installed_plugins.json'
验证设置 JSON	find .claude -maxdepth 1 -name 'settings.json'
冒烟测试安装脚本	CLAUDE_CODE_REMOTE=true bash scripts/install_pkgs.sh
验证 pre-commit 配置	pre-commit validate-config .pre-commit-config.yaml
检查市场登记情况	find .claude -maxdepth 1 -name 'settings.json'，然后 grep 搜索 extraKnownMarketplaces

已知问题

问题	症状	修复方式
#14202	插件显示“已安装”，但未激活	/health:check --scope=registry --fix
settings.json 中有过时的 enabledPlugins 键	插件显示已启用，但没有注册表／市场条目	/health:check --scope=registry --fix
孤立的 projectPath	插件是为已删除的项目安装的	/health:check --scope=registry --fix
设置 JSON 无效	无法加载设置文件	/health:check
未加入市场	laurigates/claude-plugins 的技能在 Web 会话中不可用	/configure:claude-plugins --fix