description字段

description是SKILL.md中最具战略价值的字段——它直接决定了Agent能不能找到你、会不会用你。如果说name是Skill的"身份证号"，那description就是它的"简历摘要"，Agent在海量 Skill中筛选时，完全依赖它来判断"这个Skill跟当前任务有没有关系"。

一、description在Agent执行过程中的作用

1. 渐进式披露中的"匹配钩子"

Agent启动时采用渐进式披露机制，仅预加载所有Skill的name+description，形成一个轻量级索引。当用户提出请求时，Agent会将用户意图与每个Skill的description进行语义匹配，决定是否激活：

 关键点：description 写得好不好，直接决定了Skill的召回率（该被激活时能不能被找到）和精准率（不该被激活时会不会被误触发）。

2. 上下文窗口的"守门人"

大模型的上下文窗口是有限的。Agent不可能同时加载所有Skill的完整指令，否则会造成：

• 上下文溢出：Skill太多，超出token限制
• 注意力稀释：无关指令干扰Agent的判断质量
  description 就是"守门员"：只有描述匹配成功，完整的Skill指令才会被加载。因此，description 的质量直接决定了Agent的执行效率和准确率。

3. 多Skill协作时的"调度依据"

当一个任务可能涉及多个Skill时，Agent会根据各description的语义相关度进行优先级排序，决定加载顺序和执行策略。写得模糊的description会导致Agent调度混乱。

二、description的书写规范

• 字符必须是1~1024个字符
• 应该能描述技能的作用以及何时使用。
• 应包含具体关键词，帮助Agent识别相关任务

三、编写 description 的实战技巧

技巧一：采用"做什么 + 什么时候用"的双段结构

• 第一句：一句话说清"这个Skill做什么"
• 第二句：列举典型触发场景（"当用户需要……时使用"）
• 例如：

name:
	pdf-form-filler
description:
	填写和导出PDF交互式表单。当用户需要填写PDF表单字段、批量导入数据到PDF模板、或将填好的表单导出为可提交格式时使用。

技巧二：嵌入高频触发关键词

Agent的语义匹配本质上是在做关键词 + 语义相似度的混合检索。你需要在description中自然嵌入用户可能说出的高频词汇：

关键词覆盖策略：

• 覆盖同义词：用户可能说"转成PDF"、"导出PDF"、"生成PDF"
• 覆盖文件格式：docx、md、html等具体格式名
• 覆盖动作动词：转换、导出、合并、压缩
  例如：

description: 
  将Word、Markdown、HTML 文件转换为PDF格式。 7当用户需要将docx、md、html文件转为PDF，或需要合并多个PDF、压缩PDF大小时使用。

技巧三：明确划定边界，防止误触发

好的 description 不仅要告诉 Agent"我做什么"，还要暗示"我不做什么"，避免被错误激活：
例如：

description: 
  填写和导出PDF交互式表单字段。
  仅处理表单填写场景，不涉及PDF文本编辑、
  页面裁剪或OCR识别任务。

技巧四：控制长度，精炼表达

description不是写文档，而是写精准短述。建议控制在2-4句话（约50-150 字），太长会：

• 浪费预加载时的上下文空间
• 降低语义匹配的精准度（噪声词太多）

# ❌太长（像说明书）
description:
  这个Skill是一个功能强大的 PDF 表单处理工具，它支持多种操作系统和浏览器环境，可以处理各种复杂的表单类型，包括文本输入框、下拉菜单、复选框、单选按钮等等。
  它还支持批量处理功能，可以一次性处理多个文件……（省略200字）

# ✅精炼（像简历摘要）
description:
  填写PDF交互式表单并导出结果。
  支持文本框、下拉菜单、复选框等表单元素，支持批量处理。
  当用户需要填写PDF表单或导入数据到PDF模板时使用。

技巧五：用"当……时"句式锚定触发条件

这是一种非常实用的模式，直接告诉 Agent 在什么场景下应该激活：

description:
  生成符合品牌规范的社交媒体配图。
  当用户需要制作公众号封面、小红书配图。

这种写法的好处是：

• Agent能快速判断"当前任务是否属于这些场景"
• 用户的具体表达（如"做个公众号封面"）能直接命中