SuperAPI AI 工具集

skill-checkup

编程与开发

查看项目

更新于 11-09 16:38

技能介绍

用途

skill-checkup 是一个面向已安装 agent skills 的只读检查工具,覆盖 Claude Code 与 Codex。它以离线 Python 工具形式运行,无额外依赖,用于发现 skill 目录中的结构性问题和描述冲突,并给出可执行的整理建议。工具本身不编辑、合并、移动或归档任何 skill。

主要能力

  • 失效项检测:发现失效链接或文件,以及同名但内容已漂移的副本,并建议比对后保留一个来源、使其余副本保持一致。
  • 竞争描述检测:找出描述功能重叠的 skill,建议合并或改写双方描述以区分边界。
  • 单向使用检测:识别被两个 agent 同时加载但只被其中一个使用的 skill;报告标注安全时可直接删除闲置副本,标注为共享时则应在 Claude Code 的 /skills 菜单中关闭该 skill。~/.agents/skills 中的副本可能同时服务 Cursor 或 Gemini CLI。
  • 未使用项:作为归档候选;应急类工具即使未使用也建议保留。Claude Code 的 /skill-doctor 可给出带 token 成本的同类列表。
  • 体积估算:给出 skill 占用上下文的估算值;/context 显示实测的列表大小。在 1M token 窗口模型上通常影响不大。
  • 新 skill 候选:从历史请求中找出值得沉淀为 skill 的重复请求,写入前需与用户确认;若条目标注“already handled in the body of X”,含义是改写 X 的描述而非新建 skill。
  • 静默附录:低置信度的提及与请求相似项,仅作线索对待。
  • 描述回放:用 replay 子命令对比改写前后描述的行数据,以 hit@3 更高且 steals@1 相近为更优;数值为词法近似,应比较行而非读绝对值。

使用方式

在用户当前项目目录下运行,以便纳入项目级 skill:

uvx --from git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup

不使用 uvx 时:

pipx run --spec git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup

工具会打印汇总表与前五项操作建议,并将完整报告写入 ./skill-checkup-report.md。首次运行读取最多 90 天日志,可能需要约一分钟;后续运行使用 ~/.cache/skill-checkup 缓存。

常用选项:

  • --lang zh 或 --lang en:匹配对话语言。
  • --show-examples:仅在用户想查看匹配到的自身请求时使用;引文保留在本机。
  • --context-tokens 1000000:模型为 1M token 窗口时使用;默认按 200k 估算。
  • --summary-json summary.json --anonymize:生成仅含计数的可分享文件。

检查改写后的描述:

uvx --from git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup replay <skill> --description "<new wording>"

适用场景

适合定期盘点本机 agent skills,排查失效、重复、描述冲突和闲置项,评估是否值得新增 skill,以及在修改描述前后做可对比的效果回放。

限制与注意事项

  • 报告中的相似性发现与静默附录均为对历史请求的词法匹配,应视为候选而非结论;建议改动前先阅读一两个相关 skill 核实。
  • 由 claude -p、Agent SDK 宿主或 codex exec 启动的会话计为使用,但不参与请求分析。
  • 单次 Codex 回合读取 8 个及以上 skill 会被视为清单式扫描,不计为使用。
  • “未使用”仅指在本机日志窗口内无使用记录。
  • 默认按 200k token 窗口估算预算;1M token 模型需传 --context-tokens 1000000。
  • 可选配置 ~/.config/skill-checkup/config.json 可列出废弃目录与已接受的已知问题。
  • 工具不执行任何改动;只有在用户明确指定变更时才修改 skill,并在批准改写后对相应 skill 重跑 replay 并报告前后两行结果。