Claude Ecosystem Health

克劳德生态系统健康

 

Architecture

检测相互连接的Claude Code组件之间的漂移：技能、代理、MCP服务器、vault路径、CLI工具和配置策略。

问题： 复杂的克劳德代码设置有数十种技能、代理和命令，它们通过名称相互引用，硬编码保险库路径，并依赖于配置的MCP服务器。当某物被重命名、存档或重新配置时，没有任何东西能检测到涟漪效应。引用会悄无声息地中断。

解决方案： 一种单一的诊断技能，在整个Claude Code生态系统中运行7次检查，并报告损坏、过时或配置错误的内容。默认情况下为只读。

它捕获了什么

需求

• 克劳德代码 已安装并配置
• jq 已安装（用于解析 .claude.json -- brew install jq 在macOS上）
• 技能/代理/命令 ~/.claude/ 目录结构

安装

选项1：技能CLI

npx skills add aplaceforallmystuff/claude-ecosystem-health

选项2：安装程序脚本

git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cd claude-ecosystem-health
./install.sh

选项3：手动复制

git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cp -r claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/

选项4：克隆和符号链接

git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git ~/Dev/claude-ecosystem-health
ln -s ~/Dev/claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/ecosystem-health

项目结构

claude-ecosystem-health/
  install.sh                              # Installer script
  skills/
    ecosystem-health/
      SKILL.md                            # Main skill (lean, links to references)
      references/
        checks.md                         # Detailed check implementations (7 checks)
        pitfalls.md                       # Lessons learned from production runs

该技能使用 渐进式披露：主SKILL.md简洁明了，并链接到参考文件，以了解详细的检查程序和陷阱。这使克劳德的上下文窗口保持了技能优势，同时保留了所有操作细节。

设置

安装后，根据您的环境自定义技能。这些文件包含需要更新的占位符模式：

1. 保险库路径 （签入1 references/checks.md)--将占位符路径替换为实际的vault位置
2. CLI工具 （勾选4）--添加您的设置所依赖的CLI工具
3. CLI over MCP策略 （勾选5）--定义哪些MCP工具在您的设置中具有CLI替换项
4. 报告输出路径 --设置健康报告的保存位置
5. MCP服务器别名 （勾选3）--列出所有代理MCP服务器（例如，包装多个API的基于Docker的服务器）

用法

# Full sweep (all 7 checks, monthly)
/ecosystem-health

# Quick check (checks 1-5, weekly)
/ecosystem-health --quick

# Single targeted check
/ecosystem-health --check vault-paths
/ecosystem-health --check skill-refs
/ecosystem-health --check mcp-servers
/ecosystem-health --check cli-tools
/ecosystem-health --check config-drift
/ecosystem-health --check staleness
/ecosystem-health --check orphans

输出

该技能生成结构化的降价报告，包括：

• 汇总表（正常/警告/每次检查的临界计数）
• 总体健康评级（健康/需要关注/降级）
• 受影响文件、行号和补救指针的详细发现
• 补救总结表

健康阈值

运作原理

该技能是一个结构化的提示，指导Claude Code完成7次诊断检查。每次检查：

1. 扫描源文件（技能、代理、命令、钩子、CLAUDE.md）
2. 提取引用和模式
3. 根据文件系统和配置进行验证
4. 按严重程度对发现进行分类
5. 生成报告

没有文件被修改。该技能是设计为只读的。

为什么 jq 而不是阅读？

.claude.json 在复杂的设置中可以超过40k个令牌。MCP服务器配置在多个级别：

• 顶层 mcpServers
• 项目级别 projects["/path"].mcpServers

读取工具截断大文件，导致误报（实际上在项目级别配置的幻影服务器）。 jq 提取所有服务器名称，而不管文件大小。

生产经验教训

这项技能在大型生产克劳德代码设置上进行了战斗测试。第一次运行暴露了真正的问题——路径中断、幻影MCP工具、过时的技能参考——以及导致 jq 模型检查中的配置解析和代码块过滤方法。

这 references/pitfalls.md 将生产使用过程中遇到的每个问题都归档，这样您就可以避免同样的陷阱。

何时跑步

相关技能

部分 阿普头孢拉膜囊 技能收集：

• 创作守护者 --在创建新工件之前防止重复工件
• 经验教训 --实施修复的结构化回顾
• rfu审计 --投资前的11门公用设施验证

此技能补充但不取代：

• 库存/同步工具 --对所有事物进行计数和编目（此技能可验证健康状况）
• MCP维护工具 --管理单个服务器（此技能可检测哪些需要注意）
• 升级工具 --跟踪克劳德代码发布（此技能可检测内部生态系统漂移）

许可证

麻省理工学院-见 许可证

作者

@阿普头孢拉膜囊