推荐语
精简Skill描述让Agent更聪明，40词以内精准调用，避免token浪费与选择错误。
核心内容：
1. Skill描述过长导致Agent调用错误的三大原因
2. 实际案例：压缩描述后调用准确率显著提升
3. 核心原则：为模型提供“路标”而非“说明书”
杨芳贤
53AI创始人/腾讯云(TVP)最具价值专家
很多人在给Agent写Skill描述时，默认一个前提。写得越详细，Agent越容易理解。
这套思路在人类协作里没问题，可一旦换成模型，情况完全反过来。
很多Agent选错技能、反复调用、token越烧越多，其实都卡在同一个地方。Skill写太长。
一个开发者分享过一个很典型的例子。
他给某个Skill写了90词描述，逻辑很完整，像一段小说明书。结果Agent老是选错技能。
后来他干脆把描述砍到40词以内，只保留最核心的动作词。
结果第一次调用就选对了。
很多人看到这个案例的第一反应是惊讶。
但如果你真的做过Agent系统，很快会意识到，这事一点不奇怪。
1
很多Agent开发者把Skill.md当文档写。
问题就从这里开始。
Skill描述一旦写长，就会同时触发三件事。
token成本增加、选择噪声增加、注意力被稀释。
先说最现实的一件事，钱。
Skill描述本身就在上下文里。
多写一句话，Agent每次运行就多读一次，多算一次token。
只要这个Skill被频繁加载，你就在持续付费。
再看上下文预算。
GPT-5.5默认上下文窗口是272k token。
听起来很多，对吧。
但真正分配给技能描述的预算只有2%。
注意，是所有Skill一起分这2%。
如果你的系统有几十个Skill，很容易就把预算挤满。
一旦超过限制，模型会截断技能描述。
很多人以为自己写得很清楚。
模型看到的版本其实已经被截断。
第三个问题更隐蔽。
选择噪声。
Agent在决定调用哪个Skill时，会同时扫描所有Skill描述。
描述越长，信息越杂，判断信号就越模糊。
你写了一堆解释性文字。
模型只需要几个动作词。
结果就是。
真正关键的信息被淹没。
Codex内部的计费逻辑也很直接。
严格按UTF8字节数除以4向上取整计算token。
写长一句话，看起来没什么。
运行几万次之后，就是一笔真实的成本。
所以很多团队后来才意识到。
Skill描述越长，系统越慢，钱烧得越快。
2
我印象里有个挺典型的案例。
一个做Agent开发的大厂P7工程师，技术方向是自动化运维。他在内部做工具链，把十几个运维操作封装成Skill。
每个Skill的描述都写得很认真。
几十到一百词不等。
上线以后问题马上出现。
Agent经常调用错技能。
比如需要deploy的时候，跑去执行inspect。
需要verify时，又去调用release。
团队开始怀疑模型能力。
后来他们做了一件很简单的事。
把Skill描述全部压缩。
平均长度从接近90词降到40词以内。
保留动作词，删掉解释句。
deploy
release
verify
debug
inspect
fix
上线测试之后，调用准确率直接明显提升。
那位工程师后来复盘时说了一句挺有意思的话。
模型其实不需要说明书，它只需要路标。
说实话，这种情况挺常见的。
这事跟你写代码水平没太大关系，很多工程师第一次做Agent都会踩这个坑。
因为人类写文档的习惯，很难一下子改过来。
3
有个做法在Agent圈子里越来越多人用。
Peter的skill-cleaner就是典型例子。
Peter也叫steipete，很多人认识他的原因是那套agent-scripts工具。
他在设计skill-cleaner时做了一个很极端的选择。
Skill.md只有56行提示词。
真正干活的脚本接近近千行代码。
提示词只干一件事。
让Agent找到这个能力。
具体逻辑、异常处理、边界情况，全写在代码里。
Peter自己总结这套方法时说得很直白。
install skill
agent smart
user happy
很多人第一次看到这种写法会觉得太简单。
但实际跑起来反而很稳定。
原因很简单。
Skill描述只承担定位功能。
真正的执行逻辑在脚本。
skill-cleaner的设计思路也围绕这一点展开。
它会先扫描你的技能库，然后做一轮完整体检。
第一个模块是技能提示词预算审计。
脚本会计算所有Skill描述占用多少上下文预算，并给出优化建议。
第二个模块是重复技能检测。
它会同时扫描几个来源。
Codex内置库
插件缓存
代码仓库
个人技能根目录
如果出现重复Skill，会标出来。
第三个模块是未使用技能筛查。
脚本会读取历史日志，找出长期没被调用的Skill。
第四个模块是技能根目录审计。
系统会统计每个Skill来自哪个目录，同时标记启用或禁用状态。
第五个模块是描述精简优化。
脚本会找出冗长描述，然后用短动作词进行替换。
比如调试类Skill。
推荐统一动作词。
debug
inspect
fix
部署类操作。
deploy
release
verify
检索类操作。
search
sync
summarize
这些词非常短。
但模型识别效率反而更高。
整个脚本内部使用的预算计算逻辑，和Codex官方源码一致。
也就是UTF8字节数除以4向上取整。
脚本还能模拟真实运行环境。
如果预算不足，会直接告诉你。
多少字符被截断
多少技能会被省略
以及当前预算使用率、剩余预算、上下文占用比例。
很多团队跑完第一次报告都会吓一跳。
原来Skill描述已经把上下文预算吃掉一大块。
4
如果你现在在做Agent系统，其实可以立刻给自己的Skill做一次体检。
skill-cleaner就在GitHub上。
地址是 github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner
整个流程很简单。
第一步。
在技能目录或者仓库根目录运行Node.js脚本。
脚本支持很多参数，比如时间范围、日志深度、预算阈值、技能根目录路径。
第二步。
看报告。
一般建议按这个顺序看。
技能预算
描述优化项
重复技能
未使用技能
根目录汇总
第三步。
再做清理。
有几个经验比较重要。
Codex内置技能尽量保留。
本地副本如果重复，可以删掉。
仓库里核心运维Skill建议留着。
它们通常和项目环境绑定。
还有一点很多人会忽略。
不要直接删目录。
先确认这个Skill确实没有被任何脚本调用。
描述精简也有个简单流程。
先做文本预处理。
统一格式，全部小写，去掉多余标点。
再用关键词识别场景。
判断是调试、部署还是检索。
最后替换成标准短动作词。
这样一轮下来，大多数Skill描述都能明显变短。
很多人做完这一步都会发现一个问题。
之前写的那些长描述，几乎没有提高任何效果。
只是让上下文更拥挤。
5
如果你现在正在维护一套Agent系统，可以先做三件事。
1 把所有Skill描述统计一遍长度。
超过40词的先标出来。很多问题就在这些地方。
2 跑一遍skill-cleaner。
重点看技能预算占比和未使用技能报告。
3 把描述里的解释句删掉，只留下动作词。
debug、deploy、search这类词往往就够了。
别慌。
Agent开发的很多坑，其实都在这些细节里。
Skill写短一点。
系统反而更聪明。
粤ICP备14082021号
免费POC，
零成本试错
