你的 Agent 技能（Skill）描述写得太长，不仅浪费 Token，还会降低 Agent 选择技能的准确率。有人把 90 多词的描述砍到 40 词以内后，Agent 反而一次就选对了技能。

"龙虾之父" Peter 看不下去了，开源了一个给所有 Skill 做"体检"的工具：skill-cleaner。

为什么要给 Skill 减肥

Skill 提示词的问题，表面看是文案长短，实际影响三件事：

• 成本：多加一句描述，Agent 每次调用就多付一笔 Token 账单
• 延迟：Agent 看到的信息越多，选择时的噪声也越多
• 准确性：信息过载导致 Agent 选错工具

Peter 的主张很明确：Skill 要像路标，目的是让 Agent 找到路，不该把整本说明挂在路标上。这个 skill-cleaner 本身就是最好的示范 -- Skill.md 只有 56 行提示词，而调用的脚本足足近千行代码。

五大核心功能

1. 技能提示词预算审计

分析每个 Skill 占用的上下文 Token 空间，计算预算占用比例，给出优化方案。脚本使用 Codex 官方源码同款的提示词预算核算逻辑，读取本地模型缓存配置获取 GPT-5.5 上下文窗口参数（默认 272K Token），严格遵循 Codex 计费规则（UTF8 字节数/4 向上取整）。

2. 重复技能检测

跨 Codex 内置库、插件缓存、代码库、个人技能根目录扫描同名技能、描述/内容高度相似的重复技能，标记冗余项。

3. 未使用技能筛查

基于历史日志，识别长期未被调用、未被提及、无使用痕迹的闲置技能，提供清理候选清单。

4. 技能根目录审计

统计所有技能的来源根目录，标注已启用/禁用状态，梳理技能加载链路。

5. 描述精简优化

找出冗长的技能描述，通过三步流程进行精简：

• 文本预处理：统一格式，全部小写、剔除标点符号
• 场景识别：内置预设场景关键词词库，识别技能所属业务领域
• 标准化替换：用预设的短动作词组替换冗长描述

例如：调试类替换为 debug, inspect, fix；部署发布类替换为 deploy, release, verify。

使用方法

开始前的准备

• Node.js 环境
• 已有的 Agent Skills 目录

第一步：安装

# 克隆仓库
git clone https://github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner

# 安装依赖
npm install

第二步：运行审计分析

在技能目录或仓库根目录运行脚本：

node skill-cleaner.js --dir /path/to/skills

支持的参数：

• --time-range: 指定分析的时间范围
• --log-depth: 日志分析深度
• --budget-threshold: 预算阈值
• --custom-root: 自定义技能根目录

第三步：查看报告并优化

按顺序阅读核心报告：技能预算 -> 描述优化项 -> 重复技能 -> 未使用技能 -> 根目录汇总。

优化时的安全原则：

• 优先保留 Codex 内置技能
• 不删除未确认的无关目录
• 修改前验证保留文件有效性

验证效果

优化后你可以关注两个指标：

1. Token 预算使用率：看每个 Skill 占用上下文的比例是否下降
2. Agent 调用准确率：描述精简后，Agent 是否能更准确地选择正确的技能

常见问题

• 问：精简描述会不会丢失关键信息？ 答：skill-cleaner 的策略是用标准化短词组替换冗长描述，保留的是"动作"而不是"解释"。Agent 需要的是准确的路标，不是详细的说明书。

• 问：是否支持非 Codex 的 Agent 框架？ 答：核心逻辑是通用的，但计费规则和预算基数默认按 Codex 标准计算。如果你用其他框架，需要自行调整预算参数。

GitHub: https://github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner