Skill Cleaner：给你的 AI Agent Skills 做一次大扫除

作者：Zero

项目地址：https://github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner

这是什么工具？

Skill Cleaner 是 Peter Steinberger（PSPDFKit 创始人）开源的一个 TypeScript 脚本，专门用来审计 Codex/OpenClaw 的 skills。

它能做什么？一句话概括：检查你的 skill 目录，找出重复的、没用的、描述太长的 skill，帮你省下宝贵的 prompt 预算。

解决什么问题？

用 AI 编程工具久了，你大概会遇到这些情况：

1. Skill 越装越多，prompt 预算告急

每个 skill 的描述都会被注入到 prompt 里。装了 30 个 skill？50 个？这些描述文本加起来可能已经吃掉了你上下文窗口的一大块。

以 GPT-5.5 的 272,000 tokens 上下文为例，skills 默认占 2% 的预算，也就是约 5,440 tokens。听起来不少？但你仔细算算，一个 skill 描述 200 字节，50 个 skill 就是 10KB，换算成 token 大约 2,500——已经占掉一半预算了。

2. 重复 skill 占着位置

从不同地方安装 skill，可能装了好几个功能重叠的。比如三个不同的「文件搜索」skill，它们都在消耗你的预算，但你只会用到一个。

3. 僵尸 skill 无人问津

三个月前装的那个 skill，你还记得它叫什么吗？大概率它一直躺在那里，从没被调用过，却每次都要占用 prompt 空间。

4. 描述写得太长

有些 skill 的描述恨不得写成一篇小作文。描述越长，消耗的 token 越多。很多时候，一句话就能说清楚的事，没必要写三段。

核心价值

Skill Cleaner 的价值在于：让你的 skill 配置从「随便装装」变成「精打细算」。

它不帮你写代码，不帮你做任务，但它帮你优化 AI 工具的底层效率。prompt 预算省下来了，留给真正对话和任务的空间就多了。

使用方式

基础用法

# 扫描最近 3 个月的使用记录
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --months 3

常用命令

# 不扫描日志（快速查看预算和重复情况）
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --no-logs

# 深度扫描（6 个月日志，最大 800MB）
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --months 6 --max-log-mb 800 --deep-logs

# 自定义预算参数
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --context-tokens 272000 --budget-percent 2 --no-logs

# 扫描额外的 skill 目录
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --root ~/Dropbox/boxd/skills --no-logs

报告内容

运行后你会得到一份报告，按顺序包含：

1. Skill Budget：上下文大小、预算比例、已使用/剩余预算
2. Description candidates：描述过长的 skill，建议精简
3. Duplicates：重复 skill 列表，含相似度分析
4. Unused candidates：近期未使用的 skill 候选
5. Root summary：skill 来源目录及启用状态

安全策略

工具默认只给建议，不会自动删除或修改任何东西。只有你明确要求时，才会执行清理操作，而且是分批次提交：先处理描述优化，再处理删除，最后处理配置禁用。

对于 git ignored 或 untracked 的 skill 目录，工具会特别谨慎，除非你确认可以丢弃，否则不会删除。

工作原理

Token 计算逻辑

Skill Cleaner 参考了 Codex 的 core-skills/src/render.rs 实现：

• 预算比例：2% of raw context_window
• Token 计算：ceil(utf8_bytes / 4)
• 行格式：模拟 Codex 的 model-visible line shape，即 - name: description (file: path)

数据来源

• 从 ~/.codex/models_cache.json 读取 GPT-5.5 的 context_window（默认 272,000 tokens）
• 扫描 ~/.codex/history.jsonl 和 ~/.codex/sessions/**/*.jsonl 检测 skill 使用情况
• 遵循 Codex frontmatter 规则：只解析 YAML frontmatter，默认从父目录取 name

去重机制

使用 realpath 对路径做规范化，避免符号链接导致的误报。比如 /a/b/skill 和 /a/c/../b/skill 会被正确识别为同一个 skill。

为什么这个方案有效？

1. 基于真实使用数据：不是拍脑袋猜你用不用某个 skill，而是扫描实际的调用日志
2. 精确的预算计算：完全对齐 Codex 的 token 计算方式，数字是准的
3. 保守的执行策略：只建议不执行，给你完全的控制权
4. 跨目录扫描：Codex、plugin cache、repo siblings、personal skill roots 都能覆盖

适用场景

• skill 装了一堆：超过 20 个 skill，该审计一下了
• 感觉上下文不够用：可能 skill 预算占太多了
• 从多个来源安装 skill：容易产生重复
• 追求极致效率：每个 token 都想用在刀刃上

---

Skill Cleaner 不是一个「必须有」的工具，但如果你认真对待 AI 编程工作流的效率，它值得跑一次。

毕竟，省下的 prompt 空间，就是你和 AI 对话的余量。