anthropics-skills | 04 - Skill 的触发机制：为什么 description 比正文更关键

系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第四篇。上一篇我们写出了一个最小SKILL.md知道了name、description和正文分别承担什么职责。这一篇单独展开其中最容易被低估的一行description。它往往决定了一个 Skill 有没有机会被正确使用。1. 先从一个反直觉的问题开始很多人第一次写 Skill 时会把主要精力放在正文里。这很自然。因为正文看起来才是“真正的指令”工作流、输出格式、质量标准、异常处理、示例全都写在正文里。但真实使用时你很快会遇到一个问题正文写得再好如果 Agent 没有加载这个 Skill它就完全看不到正文。这就是description重要的原因。它不是装饰性摘要也不是给人看的简介。它是 Skill 被召回的关键入口。一个 Skill 的执行链路大致可以理解成Agent 先看到所有可用 Skill 的元信息主要是name和description。Agent 根据用户当前任务判断哪些 Skill 可能有用。某个 Skill 被选中后Agent 才会读取它的SKILL.md正文。正文中如果指向脚本、参考资料或资源文件Agent 再按需读取或调用。所以description决定“有没有机会被加载”正文决定“加载之后怎么做”。如果 description 写弱了就会欠触发该用时没用。如果 description 写宽了就会误触发不该用时乱用。两者都会让 Skill 的实际效果大打折扣。2. Skill 的三层加载模型要理解 description先要理解 Skill 的加载方式。一个成熟 Skill 通常不是一次性把所有内容塞进上下文而是分层加载层级内容加载时机作用元信息name和description通常最先可见判断是否需要加载 Skill主说明SKILL.md正文Skill 触发后指导 Agent 执行任务附加资源scripts/、references/、assets/正文要求或任务需要时提供脚本、长文档、模板和资源这就是渐进式加载的基本思想。它的好处是显而易见的Agent 不需要一开始读完所有 Skill 的全部正文更不需要把所有脚本和参考资料都塞进上下文。但它也带来一个设计要求第一层元信息必须足够准确。否则后面的正文和资源都没有机会发挥作用。description就是第一层里最重要的字段。3. description 的职责是什么一个好的 description 至少承担三个职责。3.1 描述能力它要说明这个 Skill 能做什么。例如description:Generate structured outlines for Chinese technical articles.这句话说明了能力生成中文技术文章结构化大纲。但它还不够因为它没有说明什么时候该用。3.2 描述触发场景它要覆盖用户可能怎么提出需求。例如description:Generate structured outlines for Chinese technical articles. Use when the user wants to turn a technical topic,rough notes,or source material into a blog outline,article structure,or writing plan for engineering readers.这就比前一句好很多。它不仅说了能力还覆盖了几类触发场景技术主题。粗略笔记。源材料。博客大纲。文章结构。写作计划。工程师读者。用户不一定会说“生成结构化大纲”他可能说“帮我整理成博客结构”“这个主题怎么展开”“帮我设计一篇文章的章节”。description 需要覆盖这些表达背后的任务意图。3.3 描述排除条件它还要说明什么时候不应该用。例如description:Generate structured outlines for Chinese technical articles. Use when the user wants to turn a technical topic,rough notes,or source material into a blog outline,article structure,or writing plan for engineering readers. Do not use for final long-form drafting,translation-only tasks,or non-technical marketing copy.这段 description 明确排除了最终长文起草。单纯翻译。非技术营销文案。排除条件非常重要。没有排除条件的 Skill 容易变得贪心最后什么都想接管。4. description 与正文的分工很多人会问既然正文里可以写 Scope为什么 description 还要写触发场景因为它们出现在不同阶段。内容出现阶段作用descriptionSkill 被加载前帮 Agent 判断要不要加载正文 ScopeSkill 被加载后帮 Agent 确认任务边界并执行如果触发信息只写在正文里就会出现一个尴尬问题Agent 需要先加载 Skill 才能看到“什么时候用它”但它又需要先知道“什么时候用它”才会加载 Skill。所以所有“什么时候应该使用”的关键信息都应该优先写进 description。正文可以继续补充更细的范围、流程和边界但不能替代 description 的触发职责。可以把它们的关系理解成description 是门牌和路标。正文是进入房间后的操作手册。参考资料和脚本是操作手册里按需调用的工具。如果门牌写错了房间里装修得再好也没人能找到。5. 欠触发该用时没有用欠触发是 Skill 最常见的问题之一。表现是用户提出了适合这个 Skill 的任务但 Agent 没有加载它。5.1 欠触发的常见原因原因通常有几类。第一description 太短。description:Helps with documents.这句话太泛Agent 很难判断它到底是写文档、改文档、读文档还是生成文档。第二只写能力不写触发场景。description:Create technical article outlines.它描述了能力但没有覆盖用户可能说的“博客结构”“写作计划”“系列选题”“素材整理”等表达。第三只覆盖标准说法没有覆盖真实说法。description:Use for article outline generation.真实用户不一定会说“outline generation”。中文场景下用户可能说帮我搭个文章框架。这个主题怎么写成博客这些素材帮我整理成大纲。适合拆成几篇帮我规划一下章节。如果 description 只覆盖标准术语就容易漏掉真实表达。第四没有写文件类型或任务对象。例如文档处理类 Skill如果 description 没写.docx、Word document、Word 文档用户提到具体文件时就可能无法稳定触发。5.2 如何减少欠触发减少欠触发的核心方法是让 description 更贴近真实用户表达。可以从四个角度补充用户会怎么说。任务对象是什么。输入通常是什么。期望产物是什么。例如description:Generate structured outlines for Chinese technical articles. Use when users ask to create a blog outline,article structure,writing plan,series outline,or to turn rough technical notes into developer-facing content.这段 description 没有堆很多流程但覆盖了更多真实表达。6. 误触发不该用时乱用另一个问题是误触发。表现是用户任务和 Skill 只沾了一点边但 Agent 还是加载并使用了它。6.1 误触发的常见原因第一description 太宽泛。description:Use this skill whenever the user writes anything.这个范围太大。任何写作任务都可能触发它。第二只写正向触发不写排除条件。例如一个“技术文章大纲”Skill如果没有排除“最终长文起草”“营销文案”“翻译任务”它可能在这些场景下被误用。第三用了过多通用词。例如description:Helps create content,improve structure,and produce high-quality output.content、structure、high-quality output都太通用几乎任何任务都能匹配。第四Skill 本身边界不清。如果一个 Skill 既想写文章又想做文档审查还想生成 PPT 大纲那 description 很难写得准确。误触发往往不是 description 单独的问题而是 Skill 职责本身过大。6.2 如何减少误触发减少误触发需要写清边界。可以使用这些表达Do not use for final long-form drafting. Do not use when the primary deliverable is a spreadsheet file. Skip when the user is asking for translation only. Use only when the task involves a .docx file. Do not use for general coding tasks unrelated to document generation.排除条件不需要覆盖所有可能但要覆盖最容易混淆的相邻场景。例如大纲生成 vs 最终长文起草。技术文章 vs 营销文案。表格文件处理 vs 数据库脚本。PDF 处理 vs Word 文档处理。Claude API vs 其他模型供应商。相邻场景越容易混淆越应该在 description 中写清楚。7. description 的推荐结构一个实用的 description 可以按这个公式写[能力描述] [触发场景] [输入/对象] [期望产物] [排除条件]不一定每次都五项齐全但这个公式可以帮助你检查是否漏了关键信息。7.1 能力描述回答这个 Skill 做什么例如Generate structured outlines for Chinese technical articles.7.2 触发场景回答用户怎么说时该用例如Use when the user asks for a blog outline, article structure, writing plan, or series outline.7.3 输入或对象回答任务通常围绕什么材料例如Use when turning a technical topic, rough notes, source material, or project context into developer-facing content.如果是文件处理类 Skill输入对象尤其重要Use whenever a .docx file, Word document, or tracked changes in Word are involved.7.4 期望产物回答最终要产出什么例如The expected output is a Markdown outline with target audience, core question, section structure, and practice task.description 不一定每次都写完整输出格式但如果任务容易混淆写产物会很有帮助。7.5 排除条件回答什么时候不要用例如Do not use for final long-form drafting, translation-only tasks, or non-technical marketing copy.排除条件越精准误触发越少。8. 好 description 和差 description 对比下面用“技术文章大纲生成”这个 Skill 举例。8.1 版本一太弱description:Help with writing.问题能力太泛。没有触发场景。没有任务对象。没有边界。这个 description 几乎无法稳定触发。8.2 版本二只写能力description:Generate article outlines.比第一版好一点但仍然不够。问题不知道是不是技术文章。不知道是不是中文。不知道面向什么读者。不知道用户哪些表达应该触发。不知道是否包括最终长文起草。8.3 版本三较完整description:Generate structured outlines for Chinese technical articles. Use when the user asks for a blog outline,article structure,writing plan,series outline,or to turn rough technical notes into developer-facing content. Do not use for final long-form drafting,translation-only tasks,or non-technical marketing copy.这版已经比较可用。它覆盖了能力生成结构化大纲。语言和领域中文技术文章。触发表达blog outline、article structure、writing plan、series outline。输入材料rough technical notes。目标读者developer-facing。排除条件长文起草、翻译、营销文案。这就是一个适合进入测试的 description。9. 从真实 Skill 看 description 写法这个仓库里有不少可以参考的 description。9.1 文档类 Skill强调文件类型和操作范围例如docx的 description 覆盖了Word 文档。.docx文件。创建、读取、编辑、操作。目录、标题、页码、信头等格式需求。tracked changes、comments、图片替换等具体任务。排除 PDF、表格、Google Docs 和无关代码任务。这类 description 的特点是文件类型很关键。用户可能不会说“使用 docx Skill”而是说“帮我改这个 Word 文档”“提取这个.docx里的内容”“接受修订并生成干净版本”。如果 description 不覆盖这些表达就容易欠触发。9.2 表格类 Skill强调主输入或主输出xlsx的 description 特别强调spreadsheet file 是 primary input or output。.xlsx、.xlsm、.csv、.tsv都覆盖。打开、读取、编辑、修复、清洗、格式化、图表、公式都覆盖。如果主要交付物是 Word、HTML report、Python script、database pipeline就不要触发。这个设计很值得学习。它不是简单地说“处理表格”而是写清楚“当电子表格是主要输入或输出时才用”。这能减少很多误触发。9.3 文档共创 Skill强调任务类型doc-coauthoring的 description 覆盖了documentation。proposals。technical specs。decision docs。structured content。writing docs、drafting specs 等触发表达。这类 Skill 的关键不是文件类型而是任务形态用户正在开始一个较完整的文档写作任务。9.4 Claude API Skill强调供应商和排除条件claude-api的 description 很长因为它面对的是高风险的 API 漂移问题。它不仅写了 Claude、Anthropic、Opus、Sonnet、Haiku、anthropic、anthropic-ai等触发信号还写了 OpenAI、GPT、Gemini、Llama、Mistral、Cohere、Ollama 等跳过条件。这说明一件事当误用成本很高时description 需要更明确地写排除条件。如果用户正在做 OpenAI 项目却错误加载 Claude API Skill可能会直接写出错误代码。这种场景就必须把 skip 条件写清楚。10. 如何覆盖真实用户表达写 description 时不要只站在 Skill 作者视角而要站在用户视角。用户通常不会用你的内部术语。他们会用自己的表达。10.1 覆盖同义词以“技术文章大纲”为例可以覆盖大纲。框架。结构。章节。写作计划。系列规划。选题拆分。素材整理。对应英文表达可能是outline。structure。writing plan。blog plan。series outline。article skeleton。description 不需要把所有词都堆进去但要覆盖最常见的说法。10.2 覆盖文件后缀和自然语言叫法文件类 Skill 尤其要注意。用户可能说.docx。Word 文档。word document。这个合同。带修订的文档。这个表格。CSV 文件。如果 description 只写.docx可能漏掉“Word 文档”只写 spreadsheet可能漏掉.csv。10.3 覆盖任务动作同一个对象可能有很多动作。例如 PDF读取。提取文本。提取表格。合并。拆分。旋转。加水印。OCR。填表。加密或解密。如果一个 Skill 的能力确实覆盖这些动作description 应该列出常见动作帮助触发。如果不覆盖也要写排除条件。10.4 覆盖任务意图不要只覆盖关键词还要覆盖意图。用户说“这篇文档别人看不懂帮我重整一下”可能是文档共创任务用户说“这个主题太大了帮我拆成几篇”可能是系列大纲任务用户说“这个页面按钮点了没反应帮我验证一下”可能是 Web 测试任务。description 要尽量让 Agent 识别这些意图而不是只匹配单个词。11. description 需要“积极”但不能“贪心”在 Skill 设计里有一个微妙平衡。如果 description 太保守Skill 会欠触发。如果 description 太贪心Skill 会误触发。所以更准确的原则是description 应该积极覆盖真实适用场景但要精确排除相邻误用场景。例如技术文章大纲 Skill 可以积极一点description:Generate structured outlines for Chinese technical articles. Use whenever the user asks to plan,outline,structure,split,or organize a technical topic into developer-facing article content,even if they do not explicitly say outline.这能减少欠触发。但它也要补边界Do not use for final long-form drafting,translation-only tasks,or non-technical marketing copy.这能减少误触发。积极不是说“所有写作都用我”。积极是说“这个 Skill 真实覆盖的场景不要因为用户换了说法就漏掉”。12. 多能力 Skill 的 description 怎么写有些 Skill 能力比较宽比如文档处理类 Skill 可能覆盖读取、编辑、创建、转换、校验。这时 description 不能只写一句“处理文档”而要按“对象 动作 边界”组织。例如description:Use this skill whenever the user wants to create,read,edit,or manipulate Word documents (.docx files). Also use when extracting content,replacing images,working with tracked changes or comments,or producing formatted Word deliverables. Do not use for PDFs,spreadsheets,Google Docs,or coding tasks unrelated to document generation.这个结构很清楚对象Word documents、.docx。动作create、read、edit、manipulate、extract、replace、work with tracked changes。产物formatted Word deliverables。排除PDF、spreadsheets、Google Docs、无关代码任务。如果一个 Skill 覆盖多个子场景就用这种方式列出常见动作而不是抽象成一句泛泛的能力描述。13. description 不能承载完整流程description 很重要但它不是正文。不要把完整工作流、输出格式、长示例都塞进 description。不推荐description:Generate article outlines. First ask the user for the topic,then identify the audience,then extract the core question,then create six sections,then add a practice task,then review for marketing tone,then output Markdown...问题是太长。触发重点被流程淹没。后续维护困难。正文职责被混到 description 里。更好的方式是description:Generate structured outlines for Chinese technical articles. Use when the user asks for a blog outline,article structure,writing plan,series outline,or to turn rough technical notes into developer-facing content. Do not use for final long-form drafting or non-technical marketing copy.流程放正文## Workflow 1. Identify the topic, audience, and writing goal. 2. Extract the core problem. 3. Draft the outline. 4. Add a practice task. 5. Review for vague claims and marketing tone.分工清楚后续才好维护。14. description 写作步骤可以按下面的步骤写 description。14.1 先写一句能力问自己这个 Skill 做什么Generate structured outlines for Chinese technical articles.14.2 列出真实触发表达问自己用户可能怎么说blog outline, article structure, writing plan, series outline, rough notes, source material, developer-facing content14.3 列出任务对象和产物问自己输入是什么输出是什么technical topic, rough notes, source material - Markdown outline or writing plan14.4 列出相邻但不该接管的场景问自己哪些任务容易混淆final article drafting, translation-only tasks, marketing copy14.5 合并成一段自然语言最后合并description:Generate structured outlines for Chinese technical articles. Use when the user asks for a blog outline,article structure,writing plan,series outline,or to turn a technical topic,rough notes,or source material into developer-facing content. Do not use for final long-form drafting,translation-only tasks,or non-technical marketing copy.写完后再做一次检查读者能不能看懂它做什么Agent 能不能知道什么时候用是否覆盖了真实用户表达是否排除了最容易误用的相邻场景是否没有把正文流程塞进去15. 如何测试 descriptiondescription 写完后不要只靠感觉。可以设计一组测试 prompt观察 Skill 是否应该触发。15.1 正向触发测试这些 prompt 应该触发 Skill。例如技术文章大纲 Skill帮我把“Agent Skills 的触发机制”整理成一篇技术博客大纲。这个主题太大了帮我拆成一个系列写作计划。我有一些关于 MCP 和 Skill 的笔记帮我整理成面向工程师的文章结构。15.2 负向触发测试这些 prompt 不应该触发 Skill。把这段英文翻译成中文。帮我写一段产品官网营销文案。直接帮我生成一篇完整长文不需要大纲。15.3 边界触发测试这些 prompt 用来检查边界是否清楚。帮我优化这篇技术文章的结构。这份技术方案有点乱帮我重新组织一下。帮我把这个主题做成一页分享提纲。边界测试没有绝对答案。关键是你要提前决定这些任务到底是不是这个 Skill 的职责。如果是就补充触发表达如果不是就补充排除条件。16. description 迭代方法description 很少一次写对。它通常通过真实失败案例迭代。16.1 记录欠触发案例当用户任务明明适合这个 Skill但 Agent 没用时记录用户原话。例如这个主题怎么拆成几篇比较合理如果这个表达没有触发技术文章系列规划 Skill就说明 description 需要覆盖“拆成几篇”“系列规划”这类表达。16.2 记录误触发案例当用户任务不适合这个 Skill但 Agent 错用了也记录下来。例如帮我把这篇文章翻译成英文。如果触发了文章大纲 Skill就说明需要增加Do not use for translation-only tasks.16.3 每次只改一个方向不要一次性大改 description。更好的方式是如果欠触发就补真实触发表达。如果误触发就补排除条件。如果边界混乱就重新收窄 Skill 职责。每次修改后重新跑测试 prompt。这样才能判断某次修改是否真的有效。17. 常见错误17.1 把 description 写成标题description:Technical Writing Outline这只是标题不是触发说明。17.2 把 description 写成宣传语description:A powerful and professional writing assistant for high-quality content.这像产品介绍不像 Agent 可以使用的触发条件。17.3 只写内部术语description:Use for TWG outline normalization.如果TWG是团队内部缩写Agent 和新同学都可能不理解。description 应该尽量使用用户真实会说的话。17.4 没有排除条件只写 Use when不写 Do not use很容易误触发。尤其是文件处理、API 集成、写作、设计这类边界容易重叠的 Skill排除条件很重要。17.5 试图覆盖所有任务description:Use this skill whenever the user needs help with writing,coding,testing,documents,APIs,or workflows.这不是强大而是失控。Skill 越宽description 越难准确正文也越难保持清晰。18. description 自查清单写完 description 后可以用这张表检查。检查项问题能力是否说清 Skill 做什么触发是否说清什么时候使用真实表达是否覆盖用户常见说法而不只是内部术语任务对象是否包含关键文件类型、输入材料或任务对象产物是否说明期望输出或交付物排除是否写清最容易混淆的不适用场景精度是否避免过宽的词比如 anything、content、help长度是否没有把完整流程塞进 description维护后续新增场景时是否容易补充如果这张表里有三项以上答不上来description 大概率还需要调整。19. 小结这一篇我们只讲了一件事为什么description比很多人想象中更关键。可以记住三句话description 决定 Skill 有没有机会被加载正文决定加载后怎么执行。一个好的 description 要同时写清能力、触发场景、真实表达和排除条件。description 要积极覆盖真实适用场景但不能贪心接管相邻任务。如果第三篇解决的是“一个 Skill 最小结构怎么写”那第四篇解决的就是“这个 Skill 怎样在正确场景下被发现”。下一篇我们会继续往下拆当 Skill 内容越来越多时如何通过渐进式加载控制上下文成本避免把所有资料都塞进SKILL.md。20. 实践任务请拿第三篇实践任务中写出的最小 Skill专门优化它的description。按下面步骤做写出 5 条应该触发这个 Skill 的用户表达。写出 5 条不应该触发这个 Skill 的相邻任务。从正向表达里提取关键词、文件类型、任务对象和任务意图。从负向表达里提取排除条件。写出 3 版 description。比较哪一版最容易做到“该触发时触发不该触发时不触发”。可以使用这个模板## Skill 名称 [填写 Skill name] ## 正向触发表达 1. [用户表达 1] 2. [用户表达 2] 3. [用户表达 3] 4. [用户表达 4] 5. [用户表达 5] ## 负向排除表达 1. [相邻但不该触发的表达 1] 2. [相邻但不该触发的表达 2] 3. [相邻但不该触发的表达 3] 4. [相邻但不该触发的表达 4] 5. [相邻但不该触发的表达 5] ## description v1 [偏短版本] ## description v2 [覆盖更多真实表达的版本] ## description v3 [同时包含触发场景和排除条件的版本] ## 最终选择 [选择哪一版为什么]做完这个练习你会更直观地感受到Skill 的触发质量往往不是靠“写更多正文”解决的而是靠更准确地描述它应该在什么场景下出现。