GitHub - mirko-pira/skillhealth: 针对您的Agent技能的审计与可观测性——使用热力图、带修复方案的医生诊断、关系图
GitHub - mirko-pira/skillhealth: 针对您的Agent技能的审计与可观测性——使用热力图、带修复方案的医生诊断、关系图
flutter doctor 之于您的Agent技能——您拥有什么、实际使用什么、什么出了问题、以及这一切如何关联。
演示 · 功能 · 为什么 · 为什么需要专用工具 · 安装 · 快速入门 · 工作原理 · 基准测试 · 参数 · 快捷键映射 · 隐私 · 路线图 · 许可证
一切尽在一屏之中。
skillhealth 根据您的真实会话记录，计算每个已安装技能的使用热度（热、温、冷、死），并显示其令牌成本和12周迷你走势图。在控制台打开状态下更改技能或会话记录，列表会实时重新排序——上面演示中那个死掉的regex-build技能瞬间变热。按下d键进入医生模式：任何问题都将作为诊断结果呈现，包含原因和修复方案，y键可将其复制到剪贴板。
同样的数据，可脚本化：可通过管道传输、输出--json格式、在CI中进行门控。
两个演示均可完全复现：docs/demo/demo-tui.tape 和 docs/demo/demo.tape (VHS格式)，基于合成测试环境 (docs/demo/setup-demo.sh)。
skillhealth graph --open 以图谱形式展示同样的技能组合：每个技能是一个节点，大小由使用量决定，颜色由热度决定，交叉引用是边，并带有医生抽屉和可排序的表格视图。可拖拽、缩放，按/键过滤，点击节点查看其使用趋势和连接关系。超过100个节点时，会先发出警告，避免渲染出乱麻图。
技能像依赖一样堆积。安装几个市场插件后，您可能就拥有了数百个技能，而每个技能无论是否被触发，都会在每个会话中占用上下文窗口。skillhealth 提供一条命令，让您看清整个堆栈，并给出可粘贴的修复方案。
状态：v0.2 —— 完整测试套件通过，已针对实际330个技能安装和3.86 GB会话记录语料库进行验证。目前支持Claude Code；Codex和Gemini CLI已列入路线图。
- 基于真实会话记录的使用热度 —— 热/温/冷/死是根据您在会话记录 (
~/.claude/projects/**/*.jsonl) 中的实际Skillinvocation计算得出，而非根据文件日期猜测。您将了解自己实际使用了什么。 - 实时控制台 —— 在终端中直接运行
skillhealth：全屏文本用户界面，包含热度颜色列表、12周迷你走势图、医生视图，并在技能或会话记录发生变化时自动刷新。管道和CI仍保持纯文本输出。 - 范围选择器 ——
--scope project|all|user选择要包含的技能根目录；当仓库存在.claude/skills目录时自动检测为project，否则为all。在TUI中按p键可在各范围间实时切换。 - 项目视角 ——
--lens project|global将使用热度和医生诊断限定为仅针对当前项目的会话记录。在TUI中按L键切换。 - 禁用插件感知 —— 通过
enabledPlugins关闭的技能会获得专用的off状态：存在于磁盘，但从不加载，并排除在始终在线的令牌总数之外。 - 成本拆分 —— 每个技能都分别显示
always_on（每次会话加载）和on_fire（仅调用时加载）的令牌成本。页脚概览显示整个组合中始终在线的总成本。 - 类型化的历史记录交叉验证 ——
history.jsonl（Claude Code自身的命令日志）作为第二个使用信号。医生诊断W010会在技能出现在历史记录但会话记录中无命中时触发——可能是会话记录轮换或错误的--projects-dir，从而避免静默低估热度。 - 完整发现 —— 用户技能 (
~/.claude/skills)、项目技能 (.claude/skills，支持向上查找：在仓库任意子目录运行即可) 以及市场插件，并检测同一名称出现在两个位置时的影子冲突。 - 带可操作修复方案的医生诊断 —— 十项检查；每个诊断结果都带有原因描述，大多数还附带可在Shell中粘贴的具体修复方案。医生诊断从不修改文件本身。
- 关系图 —— 边表示真实的交叉引用（一个技能主体引用另一个技能，
CLAUDE.md中将技能连接在一起），渲染为交互式HTML仪表板、Mermaid图表或JSON格式。 - 详情视图 ——
skillhealth <skill>：调用次数、最后使用时间、令牌成本拆分（始终在线vs调用时触发）、来源、关联技能以及该技能的诊断结果。 - 高速 —— 并行会话记录扫描，附带增量缓存：启动时间约3ms，热运行约50ms，冷运行约每GB 0.5秒（基于上述3.86 GB语料库测量）。
- 可脚本化 —— 所有输出均支持
--json且具有稳定模式，--md可生成包含Mermaid图的Markdown报告，语义退出码（0正常 · 1警告 · 2错误）可直接用于CI或pre-commit钩子。 - 仅本地运行 —— 零网络请求，零遥测。您的会话记录内容绝不会出现在任何输出中——仅包含调用次数和时间戳。
三个具体痛点，来自实际330个技能安装：
- 技能悄然累积。插件一次发布几十个；从未有人卸载它们。大多数人无法在±2的误差范围内回答“我有多少个技能？”——更不用说“哪些技能本月被触发了？”
- 每个技能都消耗上下文，每个会话都受影响。无论技能是否触发，技能元数据都会被加载到上下文窗口中。死技能纯粹是负担：在上述330个技能安装中，从未触发的技能每次会话就消耗约18K令牌的上下文。
- 故障不可见。损坏的符号链接、无效的前置元数据、或指向已删除技能的
CLAUDE.md触发器——Agent会静默跳过它们。您永远无法发现。
因为文件夹无法回答那些关键问题。
ls ~/.claude/skills 只能显示名称——它不知道某个技能自三月以来从未被触发，不知道其前置元数据在两个版本前已无法解析，不知道 CLAUDE.md 仍然指向您删除的内容，也不知道整个堆栈每次会话消耗您多少令牌。
skillhealth 交叉引用三个来源——磁盘上的内容、会话记录中实际发生的内容、以及 CLAUDE.md 所承诺的内容——并将每个差异转化为可粘贴的修复方案。
知道哪些技能被触发、哪些闲置是简单的部分。真正有用的是将四件事联系起来：
- 使用情况：基于真实会话记录调用计算的热度，而非文件日期。
- 成本：始终在线 vs 调用时触发的令牌拆分，因此死技能会显示为每次会话对您的消耗。
CLAUDE.md预算会统计@import扩展的内容，这是表面阅读所遗漏的。 - 健康度：每个诊断结果都包含原因和可粘贴的修复方案。它只报告，从不修改您的文件。
- 连接关系：哪些技能引用了哪些技能，
CLAUDE.md触发器指向哪里，哪些技能被阴影覆盖或成为孤儿。
以上四项，一次完成，本地运行，单一静态二进制文件，支持 --json 和语义退出码，因此相同数据可直接接入CI。
npx skillhealth # 零安装（真正的二进制文件，无需Bun/Node运行时技巧）
# 或
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mirko-pira/skillhealth/releases/latest/download/skillhealth-installer.sh | sh
# 或
cargo install skillhealth
从源码安装：
git clone https://github.com/mirko-pira/skillhealth
cd skillhealth
cargo install --path crates/skillhealth
skillhealth # 实时控制台：每个技能，基于真实使用热度的列表
skillhealth doctor # 诊断：每个结果都包含原因和可粘贴的修复方案
skillhealth graph --open # 浏览器中的交互式仪表板
skillhealth code-review # 单个技能：使用情况、趋势、连接、诊断结果
所有命令均支持脚本化：
skillhealth --json | jq '.skills[] | select(.temperature == "dead") | .name'
skillhealth graph --format mermaid # 粘贴到任何Markdown文件中
skillhealth doctor && echo "skills healthy" # 退出码 0正常 / 1警告 / 2错误
```
~/.claude/skills/