Skill越详细Agent越傻！砍到40词一次选对

在Agent系统的开发过程中，为Skill编写描述是一项基础但关键的工作。很多开发者会下意识地将描述写得尽可能详细，认为这样能帮助模型更好地理解技能的用途。然而，当你真正深入实践后会发现一个反直觉的现象：Skill描述越详细，Agent的表现反而越差。这不是模型的缺陷，而是我们人类在设计提示词时容易陷入的认知误区。

实际案例：从90词到40词，准确率立竿见影

Skill描述过长会同时触发三个严重问题。首先是token成本增加——Skill描述本身占据上下文长度，每多写一句话，Agent运行时就多计算一次token开销，对于高频加载的Skill而言这是一笔持续性支出。其次是上下文预算的挤压，以GPT-5.5为例，其272k token的上下文窗口中仅有约2%分配给所有Skill描述，系统拥有几十个Skill时很快就会触及上限，导致描述被截断，模型实际看到的内容已经残缺不全。第三是选择噪声的放大，Agent在决策调用哪个Skill时需要遍历所有描述，描述越长信息越杂乱，真正关键的动作词反而被淹没在这些冗余信息中。

实践工具与优化流程

一个来自一线开发者的案例非常有说服力。某技术团队将十几个运维操作封装为Skill时，为每个Skill都编写了几十到上百词的详细描述，逻辑完整得像一份说明书。结果上线后Agent频繁调用错误——需要执行deploy时却去执行inspect，需要verify时调用了release。团队起初怀疑模型能力不足，但在将描述全部压缩至40词以内、只保留核心动作词（如deploy、release、verify、debug、inspect、fix）之后，调用准确率立刻显著提升。该工程师事后总结道：模型其实不需要说明书，它只需要路标。这句话精准地点出了Skill描述设计的核心要义。

优秀的Skill设计应该遵循定位与执行分离的原则。描述部分仅承担定位功能——让Agent快速识别这个Skill是否适用于当前任务；具体的执行逻辑、异常处理、边界情况判断则应该写在代码脚本中。这种设计的优势在于：描述足够简洁，模型能高效扫描匹配；执行逻辑足够完整，系统运行稳定可靠。

市面上已出现专门用于Skill健康度诊断的工具，例如skill-cleaner这类自动化脚本能够对技能库进行完整审计。它会检查所有Skill描述占用的上下文预算、识别重复技能、筛查长期未使用的技能、统计各Skill的目录来源，并对冗长描述提出精简建议。这类工具使用的预算计算逻辑与主流Agent平台官方源码一致（UTF8字节数除以4向上取整），能够真实模拟Agent运行时的上下文分配情况。在使用这类工具时，建议按优先级查看报告：先看技能预算和描述优化建议，再看重复技能和未使用技能报告，最后根据根目录汇总信息做清理决策。注意不要直接删除目录，应先确认该Skill确实没有被任何脚本调用，避免误删导致系统异常。

立即可执行的优化建议

如果你正在维护Agent系统，可以按以下步骤进行Skill体检。第一步是全面统计现有Skill描述的长度分布，将超过40词的描述标记为优先优化对象，这些地方往往问题最为集中。第二步是使用专业的审计工具进行系统性分析，重点关注技能预算占比和未使用技能报告。第三步是精简描述内容，删除所有解释性句子，仅保留动作词。实施时建议先做文本预处理，统一格式并去除冗余标点，再用关键词识别场景类型，最后替换为标准短动作词。

如有侵权，请联系删除。