Skill描述怎么写？用触发关键词替代功能说明书

一个被普遍误解的设计细节

在使用大语言模型的 Skill（技能）系统时，很多开发者都会犯一个看似微不足道、实则影响深远的错误：把技能的"描述"（description）当成对功能的详细说明来写。

这看起来天经地义——描述当然要说明这个技能能做什么。但实际上，这种直觉恰恰与 Skill 机制的运作原理相悖。正如一位资深实践者所指出的：你应该把技能的描述看作"触发关键词"，而不是真正意义上的功能说明。

这个观点乍听有些反直觉，但一旦理解了 Skill 描述在模型上下文中的实际作用方式，你就会明白为什么这么写才是正确的。

Skill描述始终被注入上下文

理解这一点的关键在于：技能的描述文本是始终被插入到模型上下文中的，无论这个技能最终是否被调用。

换句话说，描述并不是在模型"决定使用某个技能"之后才加载的辅助文档，而是从一开始就常驻在上下文里。它的核心使命，是帮助模型判断"什么时候应该把这个技能拉进来使用"。

这意味着描述的每一个字都在消耗宝贵的上下文空间，同时也在影响模型的路由决策。如果你在描述里写了一大段功能说明，不仅浪费了 token，还可能让触发信号被淹没在冗长的文字中。

上下文成本是隐形的

对于只有一两个技能的场景，描述写得啰嗦一点或许无伤大雅。但当技能库扩展到几十甚至上百个时，每个技能的描述都会累加进上下文。此时，冗长的描述带来的成本会成倍放大——既包括直接的 token 开销，也包括模型在众多描述中做匹配决策时的准确率下降。

描述过详的悖论：技能反而没被调用

更有意思的是一个实践中反复出现的现象：有些技能的描述写得过于详尽，以至于描述本身就包含了完成任务所需的全部信息，模型根本不需要真正去调用那个技能。

这是一个典型的"用力过猛反成拖累"的例子。开发者本意是让描述更清晰，结果却在描述里把技能的完整逻辑、参数、甚至示例都塞了进去。模型读完描述后发现"我已经知道该怎么做了"，于是跳过了技能调用环节。

这带来两个问题：

• 技能内部真正封装的逻辑（可能包含更严谨的流程、工具调用或数据处理）被绕过了；
• 本应精简的描述变成了臃肿的说明书，白白占用上下文。

正确的写法：把Skill描述当作触发器

那么，一个好的技能描述应该长什么样？核心原则可以概括为一句话：描述里要包含"魔法关键词"，用来告诉模型何时应该拉入这个技能。

聚焦触发场景而非实现细节

与其写"本技能会解析用户提供的 CSV 文件，进行数据清洗、去重、格式转换，并输出统计摘要……"，不如聚焦在触发信号上，例如明确点出"处理 CSV/表格数据""数据清洗""统计汇总"这类会出现在用户请求中的关键词。

描述的任务不是解释技能"怎么做"，而是让模型准确识别"什么样的用户意图应该激活它"。真正的实现细节，应该放在技能被调用后加载的内容里，而不是常驻的描述中。

描述与技能本体的职责分离

这本质上是一种关注点分离：

• 描述层：轻量、以关键词为核心，服务于路由和触发决策；
• 技能本体：承载完整的执行逻辑和详细指令，仅在被调用时才进入上下文。

遵循这种分工，既能降低常驻上下文的开销，又能提高模型选择技能的准确性，同时确保技能内部的严谨逻辑真正被执行，而不是被一段过详的描述"短路"掉。

给开发者的实践建议

对于正在构建或维护 Skill 系统的开发者，这个洞见值得记在心里：

1. 审视你现有的技能描述——它们是在描述功能，还是在提供触发信号？如果读起来像一段产品说明，多半需要重写。
2. 控制描述长度——描述越短、关键词越精准，路由决策往往越准，上下文成本也越低。
3. 把细节留给技能本体——完整的执行说明属于技能内部，不应该出现在常驻上下文的描述里。
4. 警惕"描述即答案"的陷阱——如果描述本身就能让模型完成任务，说明你把本该封装的逻辑泄露到了错误的层级。

归根结底，Skill 的描述是一个精妙的触发机制，而非文档。理解这一点，能让你的技能系统在准确性、成本和可维护性上都获得实实在在的提升。