1. 从一次踩坑说起为什么SKILL值得单独拿出来讲去年年底我接手了一个内部知识库的改造项目核心诉求是让团队里的AI助手能稳定输出符合我们业务规范的文档。一开始我的做法很粗暴——把所有规则、模板、示例全部塞进一个超长的系统提示词里。结果呢模型在前几轮对话还能记住格式要求聊到第五轮之后就开始放飞自我标题层级乱了、术语用错了、连最基本的输出结构都开始漂移。更头疼的是每次新增一条规则我都得重新调整整个提示词改一处崩三处维护成本高得离谱。后来接触到Anthropic官方提出的SKILL机制才意识到问题的根源不在于模型能力而在于我组织知识的方式。SKILL本质上是一种模块化、可渐进加载的能力封装方式它把原本臃肿的单一提示词拆解成一个个独立、可复用、按需加载的技能单元。每个SKILL有自己的触发条件、执行逻辑和输出规范模型只在需要的时候才去读取对应的SKILL内容而不是一次性把所有信息都灌进去。这篇文章适合三类人看一是正在做AI应用开发、被提示词维护折磨的工程师二是想把团队经验沉淀成可复用资产的业务负责人三是对Agent能力扩展感兴趣、想搞清楚SKILL和普通提示词到底有什么区别的技术爱好者。我会从SKILL的核心概念讲起拆解它的文件结构、渐进式披露机制然后手把手带你写一个能真正跑起来的SKILL最后分享我在实际项目中踩过的坑和总结出的排查技巧。整篇内容基于Anthropic官方最佳实践结合我自己的落地经验尽量说人话、给干货。2. SKILL到底是什么拆解核心概念与设计哲学2.1 一句话说清楚SKILL和普通提示词的区别普通提示词是你一次性告诉模型“你要做什么、怎么做、按什么格式输出”所有信息在对话开始前就已经全部加载到上下文里了。SKILL不一样它更像是一个按需调用的能力包——模型先看到一个简短的技能索引知道“有这么个技能存在”当对话内容触发了这个技能的使用场景时才去加载完整的技能定义。打个比方普通提示词像是你把整本操作手册复印一份贴在墙上每次干活都得从头看到尾SKILL像是你书架上的一排工具书平时只看到书脊上的书名需要查哪个章节了再抽出来翻。这个区别在技能数量少的时候不明显但当你需要管理几十个甚至上百个技能时差距就是天壤之别。Anthropic官方把这种机制叫做渐进式披露Progressive Disclosure核心思想是不要让模型在不需要的时候承载无关信息。上下文窗口是稀缺资源每一轮对话都塞满所有规则不仅浪费token还会稀释模型对当前任务的注意力。2.2 SKILL.md的文件结构长什么样一个标准的SKILL就是一个文件夹里面至少包含一个SKILL.md文件。这个文件用Markdown格式编写头部有一段YAML格式的元数据用来告诉系统这个技能叫什么、什么时候该用它。下面是一个最简化的结构示例--- name: weekly-report-generator description: 当用户需要生成周报、日报或项目进度汇总时使用此技能。支持按模板填充数据、自动计算完成率、生成可视化图表描述。 --- # 周报生成技能 ## 触发条件 当用户提到周报日报进度汇总项目汇报等关键词时激活。 ## 执行步骤 1. 询问用户本周完成事项、进行中事项、下周计划 2. 按标准模板组织内容 3. 计算任务完成率并标注风险项 4. 输出Markdown格式的周报 ## 输出模板 ...name字段是技能的唯一标识建议用英文小写加连字符方便系统索引。description字段最关键它决定了模型能不能在正确的时机想起这个技能。我见过很多人把description写得很笼统比如“一个有用的技能”这种写法等于没写——模型根本不知道什么时候该调用它。2.3 渐进式披露的三层加载机制Anthropic的设计里SKILL的加载分为三个层次理解这三层是写出优秀SKILL的前提。第一层是元数据层也就是YAML头部里的name和description。这部分内容始终存在于模型的上下文中体量很小通常只有几十个token。它的作用是让模型知道“有这么个技能”但不知道具体怎么执行。第二层是技能主体层也就是SKILL.md正文部分。当模型判断当前任务需要用到这个技能时才会把正文加载进来。正文里写的是执行步骤、注意事项、输出格式等核心内容。第三层是附属资源层包括技能文件夹里的参考文档、模板文件、示例数据等。这些内容不会自动加载而是在技能执行过程中模型根据需要主动去读取。比如一个代码审查技能可能在文件夹里放了一份详细的编码规范文档只有当审查到具体某类问题时才去查阅对应章节。这种分层设计的精妙之处在于它模拟了人类专家解决问题的方式。你找律师咨询律师不会一上来就把整本民法典背给你听而是先了解你的问题然后针对性地查阅相关法条。SKILL的渐进式披露就是在复现这个认知过程。2.4 为什么SKILL比传统提示词工程更适合复杂场景我总结下来有三个核心优势。第一是可维护性每个技能独立成文件修改一个技能不会影响其他技能团队协作时也可以分工作业。第二是可组合性一个复杂任务可以拆解成多个SKILL模型按顺序调用每个SKILL专注做好一件事。第三是上下文效率只有被激活的技能才会占用上下文窗口这意味着你可以同时挂载几十个技能而不会把模型“撑爆”。还有一个容易被忽略的好处SKILL让非技术人员也能参与AI能力建设。业务专家不需要懂编程只需要按照模板写清楚操作步骤和判断标准就能把自己的经验封装成一个SKILL。这在传统提示词工程里是很难做到的因为提示词往往和代码逻辑纠缠在一起。3. 动手写一个SKILL从零到可运行的完整流程3.1 先想清楚这个SKILL解决什么问题写SKILL之前我习惯先问自己三个问题这个技能在什么场景下被触发它需要完成什么具体任务它的输出应该长什么样这三个问题分别对应SKILL的触发条件、执行逻辑和输出规范。以我实际做过的一个“会议纪要整理”SKILL为例。触发场景是用户上传会议录音转写文本或粘贴会议记录具体任务是提取决议事项、待办任务、责任人、截止时间输出格式是结构化的Markdown表格加一段摘要。想清楚这些之后写SKILL就是填空题了。注意不要试图用一个SKILL解决所有问题。我见过有人写了一个“文档处理”SKILL里面涵盖了格式转换、内容摘要、翻译、校对等七八种功能结果模型每次调用都抓不住重点。一个SKILL只做一件事做精做透。3.2 元数据编写让模型在正确的时候想起你description字段的写法直接决定了SKILL的触发准确率。我的经验是采用“场景描述 关键词列举 能力说明”的三段式结构。举个例子description: 当用户需要将会议记录、访谈录音转写文本整理成结构化纪要时使用。触发关键词包括会议纪要访谈整理录音转写会议记录。支持提取决议事项、待办任务、责任人分配、截止时间并生成摘要和行动项表格。第一句说清楚使用场景第二句列举触发关键词帮助模型匹配第三句说明具体能力边界。这样写下来模型在遇到相关任务时能准确识别遇到不相关的任务也不会误触发。还有一个细节description里不要写“这个技能很好用”“非常强大”之类的自夸词汇模型不看这些它只看功能描述和触发条件。把篇幅留给具体的能力说明。3.3 正文结构步骤化、可执行、有边界SKILL.md的正文部分我推荐用固定的结构来写这样模型读起来逻辑清晰执行起来也不容易跑偏。我的模板通常包含以下几个板块触发条件再次明确什么情况下激活这个技能和description形成呼应。前置检查执行前需要确认哪些信息已经具备哪些需要向用户询问。比如会议纪要技能需要确认是否有参会人名单、会议主题、时间范围。执行步骤用有序列表写清楚每一步做什么步骤要具体到可操作的程度。不要写“分析会议内容”这种模糊指令要写“逐段阅读转写文本识别包含‘决定’‘同意’‘确认’等动词的句子提取为决议事项”。输出格式给出明确的模板或示例。模型对格式的遵循能力很强但前提是你得把格式写清楚。用代码块包裹模板示例效果最好。边界与例外说明哪些情况不在这个技能的处理范围内遇到时应该怎么处理。比如“如果转写文本中无法识别责任人标注为‘待确认’不要自行推断”。3.4 附属资源的组织方式当SKILL需要引用外部文档时不要把所有内容都塞进SKILL.md正文而是放在独立文件里在正文中用相对路径引用。比如## 参考文档 - 详细的会议纪要格式规范见 references/format-spec.md - 常见决议事项分类示例见 examples/decision-types.md模型在执行过程中如果需要查阅这些文档会主动去读取。这样做的好处是SKILL.md保持精简加载速度快同时附属资源可以写得很详细不受篇幅限制。我通常会把以下几类内容放到附属文件里详细的格式规范、大量示例数据、领域知识参考、常见错误对照表。而执行步骤、触发条件、输出模板这些核心逻辑则保留在SKILL.md正文中。3.5 一个完整SKILL示例会议纪要整理下面是我实际在用的会议纪要SKILL的简化版本你可以直接参考这个结构来写自己的技能--- name: meeting-minutes-organizer description: 当用户需要将会议记录、访谈录音转写文本整理成结构化纪要时使用。触发关键词包括会议纪要访谈整理录音转写会议记录。支持提取决议事项、待办任务、责任人分配、截止时间并生成摘要和行动项表格。 --- # 会议纪要整理技能 ## 触发条件 用户提供会议转写文本、会议记录草稿或明确要求整理会议纪要时激活。 ## 前置检查 1. 确认会议主题和日期 2. 确认参会人员名单如未提供从文本中提取人名 3. 确认输出语言和格式偏好 ## 执行步骤 1. 通读全文标记出所有包含决策动词的句子 2. 提取决议事项按主题归类 3. 识别待办任务提取责任人、截止时间、交付物 4. 生成一段不超过200字的会议摘要 5. 按输出模板组织内容 ## 输出模板 ### 会议摘要 [200字以内的摘要] ### 决议事项 | 序号 | 决议内容 | 相关讨论 | |------|----------|----------| | 1 | ... | ... | ### 行动项 | 序号 | 任务描述 | 责任人 | 截止时间 | 状态 | |------|----------|--------|----------|------| | 1 | ... | ... | ... | 待开始 | ## 边界与例外 - 无法识别责任人的任务责任人栏填写待确认 - 转写文本中语义模糊的句子不要强行解读标注原文待确认 - 如果会议内容涉及多个独立主题按主题分节输出这个SKILL写完之后我测试了二十多份不同风格的会议记录触发准确率和输出格式遵循率都在90%以上。关键就在于步骤写得足够具体模型不需要“猜”你想让它做什么。4. 写出优秀SKILL的核心心法4.1 触发描述的精准度决定一切SKILL能不能在正确的时机被调用90%取决于description写得好不好。我踩过的坑是早期写description太注重“能力描述”忽略了“触发场景”。比如我写过一个“数据分析”SKILLdescription是“支持数据清洗、统计分析、可视化建议”结果模型在用户只是问了一个简单的数学计算时也去调用它因为“统计分析”这个词太宽泛了。后来我改成“当用户提供结构化数据集CSV、Excel、数据库查询结果并需要生成分析报告时使用”误触发率立刻降下来了。description里要写清楚输入是什么、输出是什么、什么场景下用而不是泛泛地描述能力。还有一个技巧在description里列举用户可能说的原话。比如“帮我看看这份数据”“分析一下这个表格”“这份报表有什么问题”把这些口语化的表达写进去模型匹配起来更准。4.2 步骤要细到“另一个人类能照着做”判断一个SKILL写得好不好我有个简单标准把SKILL.md发给一个完全不了解背景的同事他能不能照着步骤独立完成任务如果他说“这里我不确定该怎么做”那就说明步骤还不够细。举个例子“提取待办任务”这个步骤如果只写这一句模型可能会漏掉隐含的任务。我会写成“逐句检查文本识别包含‘需要’‘应该’‘负责’‘跟进’‘完成’等动词的句子将主语识别为责任人将时间状语识别为截止时间将动词宾语识别为任务内容。”这样写虽然啰嗦但模型执行起来准确率会高很多。实操心得写步骤的时候想象你在给一个刚入职的实习生写操作手册。他不会读心术你写多细他就能做多细。4.3 输出格式用示例说话模型对格式的遵循能力很强但前提是你得给它一个明确的参照。我习惯在SKILL.md里直接放一个完整的输出示例用代码块包裹标注清楚每个部分应该填什么。这比用文字描述“输出应该包含标题、表格、摘要”有效得多。如果输出格式比较复杂我会在附属文件里放多个示例覆盖不同场景下的输出样式。比如会议纪要技能里我放了“决策型会议”“头脑风暴型会议”“项目汇报型会议”三种示例模型遇到不同类型时会参考对应的样式。4.4 边界条件要提前堵住模型有个特点遇到不确定的情况时倾向于“编一个合理的答案”而不是承认不知道。所以在SKILL里必须明确写出边界条件告诉模型什么情况下应该停下来询问什么情况下应该标注待确认什么情况下应该拒绝执行。我在会议纪要SKILL里写了这么一条“如果转写文本中某句话的语义无法确定不要根据上下文推测直接标注‘原文语义待确认’并保留原句。”这条规则帮我避免了很多因为模型“自作聪明”导致的错误。4.5 版本管理与迭代节奏SKILL不是写完就一劳永逸的。我在实际项目中会给每个SKILL维护一个版本号每次修改都在文件头部记录变更内容。迭代的触发条件通常是发现新的误触发场景、输出格式需要调整、用户反馈了新的边界情况。迭代节奏上我建议小步快跑。不要攒一堆问题一次性大改而是发现一个问题就修一个每次修改后立刻用几个测试用例验证。这样能快速定位是哪个改动导致了新问题。5. 常见问题与排查技巧实录5.1 SKILL不被触发怎么办这是最常见的问题。排查思路按优先级来先检查description里的触发关键词是否覆盖了用户的实际表达方式再检查SKILL的name是否和系统里已有的技能冲突最后确认SKILL文件是否被正确加载到了技能目录。我遇到过一次诡异的情况SKILL文件明明放在正确位置但模型就是不调用。后来发现是YAML头部的格式有问题——description字段的值里包含了冒号但没有用引号包裹导致YAML解析失败。这种问题很隐蔽建议写完SKILL后用YAML校验工具过一遍。5.2 SKILL被过度触发怎么处理和上一个问题相反有些SKILL因为description写得太宽泛导致模型在不相关的场景也去调用。解决办法是在description里增加排除条件。比如“当用户提供结构化数据集并需要生成分析报告时使用。注意不适用于简单的数学计算、不适用于纯文本内容分析。”另外可以在SKILL正文的触发条件部分写清楚“以下情况不激活此技能”给模型更明确的边界。5.3 输出格式不稳定的排查方法模型有时候遵循格式有时候不遵循这种不稳定的情况通常有三个原因。一是输出模板不够具体模型在“自由发挥”二是SKILL正文太长格式要求被淹没在大量文字中三是多个SKILL同时被激活格式要求互相冲突。我的处理方式是把输出模板放在SKILL.md的靠前位置用醒目的代码块包裹如果正文确实很长把格式要求单独提取到一个附属文件里在正文中用引用块强调检查是否有其他SKILL的触发条件与当前SKILL重叠如果有调整description让它们互斥。5.4 附属资源加载失败的常见原因附属资源加载失败通常是因为路径写错了。SKILL.md里引用附属文件时路径是相对于SKILL文件夹根目录的不是相对于SKILL.md文件本身。比如SKILL.md在my-skill/SKILL.md附属文件在my-skill/references/format.md引用路径应该写references/format.md而不是../references/format.md。还有一个坑是文件名大小写。有些系统对文件名大小写敏感Format.md和format.md会被当成两个不同的文件。建议统一用小写字母加连字符命名。5.5 多SKILL协作时的冲突排查当多个SKILL同时被激活时可能会出现指令冲突。比如一个SKILL要求输出用表格另一个要求用列表。这种情况下模型通常会遵循后加载的SKILL但行为不稳定。我的做法是在设计阶段就规划好SKILL的职责边界确保任意两个SKILL的触发条件不重叠。如果确实需要协作在其中一个SKILL里明确写“当同时激活XX技能时输出格式以XX技能为准”。另外控制同时激活的SKILL数量一般不超过3个太多了模型也处理不过来。问题类型典型表现排查方向解决手段不被触发模型完全不知道技能存在description关键词覆盖不足补充用户口语化表达过度触发不相关任务也调用技能description过于宽泛增加排除条件和边界说明格式漂移输出结构时好时坏模板不够具体或正文太长前置模板、拆分附属文件资源加载失败引用文档读不到路径错误或大小写不一致统一小写命名、检查相对路径多技能冲突指令互相矛盾触发条件重叠明确优先级、控制激活数量5.6 我总结的SKILL自检清单每次写完一个SKILL我会用下面这个清单过一遍确认没有遗漏description是否包含了场景、关键词、能力边界三个要素触发条件是否和description一致有没有矛盾执行步骤是否具体到另一个人能照着做输出模板是否用代码块包裹是否放在显眼位置边界条件是否覆盖了“不知道怎么办”的情况附属文件路径是否正确文件名是否统一小写是否和其他SKILL的触发条件有重叠是否用至少三个不同风格的测试用例验证过这个清单帮我省了很多返工的时间。尤其是最后一条很多人写完SKILL只用一个理想化的例子测一下就觉得没问题了实际上真实场景里的输入千奇百怪多测几个边界情况才能发现隐藏的问题。6. 从能用到好用进阶优化思路6.1 用测试用例驱动SKILL迭代我现在的习惯是每写一个新SKILL先准备一组测试用例包含正常场景、边界场景、异常场景各两到三个。每次修改SKILL后跑一遍测试用例确认没有回归问题。测试用例不用很复杂就是几段模拟的用户输入加上期望的输出要点。比如会议纪要SKILL的测试用例包括一份标准会议记录、一份没有明确责任人的记录、一份包含多个独立议题的记录、一份转写质量很差的记录。跑完这四个用例基本能覆盖大部分真实场景。6.2 把领域知识沉淀到附属文件SKILL.md正文保持精简把领域知识、格式规范、示例数据放到附属文件里。这样做的好处是正文加载快模型执行核心逻辑时不受干扰附属文件可以写得很详细不受篇幅限制更新领域知识时只需要改附属文件不用动SKILL主体。我有个做法律文档审查的SKILL正文只有触发条件、执行步骤和输出模板三部分但附属文件里放了合同条款分类表、常见风险点清单、审查意见模板等五六个参考文档。模型在执行审查时按需查阅效果比把所有内容塞进正文好得多。6.3 监控SKILL的实际调用情况SKILL上线之后我会记录每次调用的触发场景、执行结果、用户反馈。如果发现某个SKILL经常在非预期场景被触发或者执行结果经常需要人工修正就说明description或执行步骤需要调整。这个监控不需要很复杂的系统初期用表格手动记录就行。关键是养成习惯把每次异常都当成优化SKILL的线索。我坚持记录了两个月积累了三十多条优化记录SKILL的准确率从最初的70%提升到了95%以上。6.4 团队协作中的SKILL管理规范当团队多人维护SKILL时需要一套命名和版本管理规范。我的建议是SKILL文件夹用领域-功能的命名方式比如legal-contract-review、hr-interview-summarize每个SKILL维护一个CHANGELOG.md记录变更历史修改SKILL前先在测试环境验证确认没问题再合并到主目录。另外团队里最好有一个人负责审核新提交的SKILL检查description是否准确、步骤是否完整、边界条件是否覆盖。这个审核角色不需要是技术专家但需要对业务场景有深入理解。6.5 什么情况下该拆分SKILL一个SKILL如果出现以下信号就该考虑拆分了执行步骤超过15步、输出格式有多个差异很大的变体、触发条件里用了大量“或”连接的不同场景、维护时经常改一处影响另一处。拆分的原则是按任务阶段或输出类型来分。比如一个“项目报告生成”SKILL如果同时处理周报、月报、结项报告可以拆成三个独立SKILL共享一个附属文件存放通用格式规范。这样每个SKILL的触发条件更精准执行步骤也更聚焦。6.6 关于SKILL编码的常见误解社区里经常看到有人问“SKILL编码193”“SKILL编码247”是什么意思这里顺便澄清一下。这些编码通常是指某些平台或工具内部对SKILL的分类编号并不是Anthropic官方规范的一部分。SKILL的核心规范就是SKILL.md加YAML头部加Markdown正文没有复杂的编码体系。你不需要记住任何编码只需要把description和正文写好就行。另外SKILL和传统意义上的“插件”也不是一回事。插件通常需要编程接口和运行时环境SKILL本质上是一份结构化的自然语言文档模型读取后按照文档指示执行。这也是SKILL门槛低、易上手的原因——你不需要写代码只需要把操作步骤写清楚。6.7 我个人的几条实战建议第一先写再优化。不要指望第一版就完美先写一个能跑的版本然后在实际使用中迭代。我最早写的SKILL现在回头看简直惨不忍睹但正是那个粗糙的版本让我理解了SKILL的运行机制。第二多读别人的SKILL。GitHub上有不少开源的SKILL示例读十个不同领域的SKILL你对“什么算好SKILL”的直觉会大幅提升。第三保持SKILL.md精简。正文控制在500行以内超出的内容往附属文件放。模型加载正文时是有上下文预算的太长了反而影响执行效果。第四测试用例比SKILL本身更重要。一个好的测试用例集能帮你发现80%的问题而且每次修改后都能快速回归验证。第五别把SKILL当银弹。SKILL解决的是“能力封装和按需加载”的问题它不能替代模型本身的能力边界。如果任务本身超出了模型的能力范围写再多SKILL也没用。先确认模型能做这件事再用SKILL把做法固化下来。最后分享一个我最近在用的技巧给每个SKILL写一句“一句话简介”放在description的最前面。这句话用最直白的语言说清楚“这个技能是干什么的”比如“把会议记录变成结构化纪要”。模型在匹配时对这句话的敏感度很高而且你自己维护时一眼就能想起这个SKILL的用途。这个习惯帮我省了很多翻看正文的时间。