cnife Pi Agent Skill Audit
审计 pi agent 全局安装的技能（~/.agents/skills/），找出哪些高频使用、哪些从未用过，帮助用户做清理决策。
为什么需要这个技能
Pi agent 的技能是逐步累积的。新的实验性技能装上去后可能只用一两次、同类技能可能互相覆盖（比如 smart-search 替代了 tavily 全家桶）、有些技能装完就忘了。如果不定期清理：
- 系统 prompt 被大量不相关技能的 description 占满，影响模型对真正有用技能的判断
- 用户花精力维护的技能库实际只有一半在用
- 新装技能被淹没在长尾列表里
这个技能帮你把"凭感觉删"变成"看数据删"。
工作流
统计调用 → 交叉分析 → 报告展示 → 用户决策 → 删除 → 验证
第一步：运行审计脚本
uv run --script scripts/audit.py
脚本自动扫描 ~/.pi/agent/sessions/ 下的全部会话日志，统计每个技能被调用的次数。输出包含：
- 总览：已安装技能数、有调用记录的技能数、总调用次数
- 四档分类：高频 / 中频 / 低频 / 未使用
- 可视化柱状图：直观对比各技能使用量
- 删除命令：直接给出可 copy-paste 的
bunx skills remove命令
统计原理：pi 的会话日志里记录了两类 skill 调用痕迹——用户主动加载的 <skill name="..."> 标签，以及 agent 自己通过 read 工具读取的 skills/*/SKILL.md。两者合一才能反映真实使用情况。
第二步：分析报告，给建议
对照脚本输出，分析每个未使用或低频技能的清理价值：
| 类别 | 判定 | 建议 |
|---|---|---|
| 🔥 高频 (≥10 次) | 硬需求 | 无条件保留 |
| ✅ 中频 (3-9 次) | 稳定使用 | 保留 |
| ⚠️ 低频 (1-2 次) | 偶尔用到 | 读 SKILL.md 了解用途，让用户判断 |
| ❌ 未使用 (0 次) | 从未调过 | 建议删除，附理由 |
分析未使用技能时，重点关注这几类：
- 被同类覆盖 — 比如 tavily 系列已被 smart-search 取代
- 场景已不存在 — 之前某个项目需要，项目结束了技能也闲置了
- 装完就没用过 — 安装时觉得将来会用，实际上再没碰过
- 面向不同的 agent — 某些技能是为 Hermes/Claude Code 设计的，pi 用不上
对每个建议删除的技能，先读它的 SKILL.md 了解功能（1 分钟），然后在报告中给出清理理由。这样用户不是盲目删除。
第三步：执行删除
用户确认后，用 bunx skills 删除：
# 单个删除
bunx skills remove <skill-name> -g -y
# 批量删除（同系列场景）
bunx skills remove tavily-cli tavily-crawl tavily-search -g -y
参数：
-g— 全局安装（~/.agents/skills/）-y— 跳过交互确认
第四步：验证
ls ~/.agents/skills/ | grep <skill-name>
# 无输出 = 已删除
分析技巧
如何判断技能是否被同类覆盖
这是最常见的无用技能场景。当发现多个技能面向同一个需求领域时：
- 检查各自调用次数 — 调用次数多的那个是用户实际在用的
- 对比 description — 覆盖面更广的通常胜出（如 smart-search 替代多个专用搜索源）
- 向用户确认 — "这个技能看起来被 X 替代了，要删吗？"
如何评估技能价值
高调用次数不直接等于高价值：
- think 调用最多（40+）— 因为每做一次方案规划就用一次，这是高频短流程
- obsidian-diary 调用很多（30+）— 因为每次会话结束都触发，这是高频常规流程
- git-master 调用 10 次— 虽然次数少，但每次都是关键时刻（提交/推送/回滚），价值很高
所以真正该删的是：调用次数为 0，且没有明确理由保留的技能。
注意事项
- 先展示报告再删除，不要跳过用户确认步骤
- 删除前读一遍 SKILL.md，解释该技能是干什么的，用户记不清时有用
- 同系列技能（如 tavily-*、tavily-*）一次列出供用户批量决策
- bunx skills remove 会同时清理全局和所有 agent 的引用，不需要额外步骤
- 本技能只负责 pi agent 技能，Hermes 技能请用
audit-hermes-agent-skills
脚本参考
审计脚本在 scripts/audit.py，使用 PEP 723 内联依赖，uv run --script 直接执行。
支持自定义路径：
uv run --script scripts/audit.py --sessions /custom/sessions/dir --skills /custom/skills/dir
如果脚本输出为空，检查：
~/.pi/agent/sessions/是否存在且有.jsonl文件~/.agents/skills/是否存在且有技能目录