AI Agent Skills机制实战：从提示词到可复用技能包

如果你也和我一样每天要给同一个智能助手反复解释“应该怎么做事”那你一定对最近频繁出现的 Skills 机制感兴趣。简单来说Skills 就是把一套可复用的技能包——包括触发条件、执行步骤、输出模板和示例——固化成一个独立文件让模型在遇到匹配任务时自动加载。我最初觉得这不过是另一种写提示词的方式直到我在一个内部项目里被高频任务反复折磨才意识到问题的关键不是模型不够聪明而是我从来没有好好教它。这篇笔记会从零开始记录我学习编写 Skills 的完整过程包括文件结构、最小可运行示例、踩坑经历以及让小技能组合复用的进阶思路。无论你刚刚接触技能这个概念还是已经写过几个但总感觉不对这篇都值得花十分钟读一遍。1. 为什么我突然开始研究 Skills被“从零调教”逼疯之后1.1 每天重复交代同一件事是效率最低的用法我有一个实际的场景给内部的问答机器人整理项目会议纪要。最初我只会在对话框里临时写提示词比如你是会议纪要助理。请提取所有决策、行动项、负责人和截止时间用 Markdown 表格输出不要遗漏细节注意语序通顺……这段提示词有三个问题。第一它太长每次都要重新想一遍第二哪怕我只改动几个字最终格式也可能不同第三模型把“当前提示词”当作临时上下文这一轮说完下一轮又回到原样。结果就是同一个会议记录我跑三次三次的排版和内容取舍各不相同。有一次我偷懒只写了“整理一下”模型直接输出了一段流水账连行动项都没有分出来。真正让我崩溃的不是模型笨而是我每天都在做一件毫无积累的事重复地“从零教它”。后来我仔细想了想如果这件事是交给一个真实的人类助理我肯定会在第一天就写好一份《会议纪要整理规范》让他照着执行。任务流程是稳定的输出格式是固定的那我为什么要让模型每次都靠猜这就是我开始研究 Skills 的直接原因。1.2 Skills 解决的真正问题把隐性流程变成显性资产Skills 最重要的价值不是让你写一个更长的提示词而是把任务的完成经验打包成一个可以在多个对话里复用的资产。它至少包含三个部分什么场景下触发、具体按什么步骤执行、期望输出什么格式。你可以把它理解成给模型的一套“新员工培训手册”。假设团队里来了一个新人你不会每天重新给他讲一遍报销流程而是把流程文档丢给他让他照着做。模型也是一样。与其每次在临时提示词里重新描述不如把流程、边界、示例统统写进一个独立文件。这样你可以把注意力放在业务本身而不是反复解释基本规则。我见过不少人对 Skills 有一个误解认为它只是“提示词的收藏夹”。其实两者的差别很大。提示词是放在当前对话里的临时指令不会自己判断该不该生效而 Skills 通常会带有一个描述字段模型会根据任务内容判断是否加载它。这意味着你不需要手动把技能内容粘进来只要说出你的需求模型就会在合适的时机调用合适的技能包。这一步的自动化才是真正提高效率的地方。1.3 学习之前先泼一盆冷水不是所有场景都适合做成 Skill在动手写第一个 Skills 之前我建议你先做一次任务筛选。我自己会拿一张检查表来判断顺序如下这个任务是否高频出现任务的输入是否可以被明确描述任务的输出是否可以被固定成一种模板任务的核心流程是否有相对稳定的先后顺序如果四个问题你都答“是”那这个任务非常适合做成 Skill。比如会议纪要整理、项目周报生成、代码变更说明、常见数据清洗都属于这一类。但如果任务本身高度创意化比如“帮我想一句品牌文案”或者“给产品起名”每次的需求方向都可能完全不同把流程写死反而会限制模型发挥。这就像给一个写诗的人发了一份标准操作流程他确实会照着写但写出来的东西大概率非常平庸。另外即使适合做成 Skills也不要幻想一个文件就能解决所有问题。好的技能往往是一个持续迭代的过程后面我会专门讲这个。2. Skills 文件到底长什么样从目录到内容的一次完整拆解2.1 最小目录一个文件夹加一个 Markdown 文件我第一次研究 Skills 时最想搞清楚的就是“文件到底放哪里”。其实最小结构非常简单skills/ └── meeting-minutes/ ├── SKILL.md └── examples/ ├── input.txt └── output.mdskills/是技能的总目录meeting-minutes/是这个技能的文件夹核心文件叫做SKILL.md。有些平台也支持skill.md或别的命名但原理一致模型启动时加载器会扫描这个目录读取SKILL.md里的元信息和正文。文件夹命名我强烈建议使用小写字母加短横线例如meeting-minutes而不是Meeting Minutes或meeting_minutes。原因很简单文件夹名通常会作为技能的标识小写短横线可以避免大小写问题和路径转义问题。如果你在日志里排查加载失败你会发现一个不该存在的空格会浪费很多时间。examples/目录不是强制要求但我后续会解释它几乎是让技能输出稳定的关键。里面放至少一组“输入样例”和“输出样例”模型在执行时会把它们当作格式参考。2.2 frontmatter 字段决定模型什么时候该调用你打开SKILL.md文件最顶部通常是一段 YAML 格式的 frontmatter。我自己的最小配置长这样--- name: meeting-minutes description: 将口语化的会议记录整理成结构化会议纪要输出包含背景、决策、行动项和负责人的 Markdown 文档。适合在用户提供会议文字记录并要求整理时使用。 version: 1.0.0 ---这三个字段里最容易被忽略也最重要的是description。它不是写给你看的而是写给你背后的模型看的。模型会拿当前用户请求和这一段描述做匹配判断要不要加载这个技能。我见过两种典型错误。一种是描述写得太短比如“整理会议纪要”结果模型在用户提到“总结一下今天讨论的事”时也强行触发因为它把“总结”和“整理”看作一回事。另一种是描述写得太长把执行步骤全都塞进去这样一方面浪费 token另一方面会让模型在加载技能前就被一大段指令干扰。有效的description应该回答三个问题输入是什么什么时候使用输出是什么描述类型示例我的评价过短整理会议纪要边界模糊容易被误触发过长把完整步骤写进 description浪费上下文干扰判断有效说清输入类型、适用场景、输出结构模型能精准决定是否加载2.3 正文部分不是说明文档是操作手册frontmatter 下面是正文这部分才是模型真正执行任务时读取的指令。很多人会像写产品说明书一样把正文写成“这个技能用于整理会议纪要它可以帮助用户……”的抒情散文。但我试过几次之后发现模型更需要的是一份可执行的操作手册而不是背景介绍。我的正文结构一般会包含四块角色定位、执行步骤、输出模板、注意事项。下面是一个简单的片段# meeting-minutes 你是会议纪要整理专家。收到用户的会议文本后按以下步骤处理 1. 通读全文提取会议主题、时间、参会者。 2. 找出所有已经确定的决策记录为列表。 3. 找出所有行动项对每条标注负责人与截止时间原文未提及就写“待确认”。 4. 按固定格式输出 Markdown。 ## 输出模板 ## 会议主题 ... ## 决策 - ... ## 行动项 | 行动项 | 负责人 | 截止时间 | |--------|--------|----------| | ... | ... | ... | ## 注意事项 - 不要新增原文没有的信息。 - 口语化内容需要转换为书面语。你会发现它非常像一个给新人看的 checklists。模型对“先做什么再做什么”的指令响应相当好只要步骤是线性且明确的输出稳定性就会明显提升。2.4 示例文件给模型一份“标准答案”我之前一直不理解为什么要在技能旁边放示例后来一次实测让我彻底明白了。只给步骤和模板模型仍然有可能在具体措辞上摇摆不定。比如模板里写“行动项”它可能输出“待办事项”你说“Markdown 表格”它可能用另一个风格的表格。这些细节靠文字很难完全约束但给一个输入文件和对应输出文件模型就能快速对齐。examples/input.txt里可以放一段真实的会议速记越“脏”越好最好包含口语、重复、无关对话。examples/output.md就是你希望它最终输出的样子格式要非常规范甚至可以故意展示一个情况原文没写负责人输出里要写“待确认”。这样模型在推理时会下意识地参照示例而不是自己临时编一套规范。我自己的经验是示例不必多一组高质量的例子胜过五组普通例子。如果你能有“一个输入、一个输出”的对照已经足够起步。3. 手写一个“会议纪要整理”Skill从任务拆解到真正跑通3.1 先别动手写文件把任务拆成模型能执行的步骤很多人一开始就打开编辑器写 Markdown结果写了一堆正确的废话。我建议先拿白纸把任务拆一遍。同样以会议纪要为例我会拆成四步通读原文划出主题和时间信息。识别所有决策类内容比如“决定采用方案 A”。识别所有行动项比如“张三下周五前完成接口联调”。把以上信息按固定模板输出并对缺失字段标注“待确认”。拆解的过程看起来“不像在写技能”但它非常重要。因为模型是逐步执行任务的你的任务步骤越清晰它就越不容易跳步或合并步骤。如果连你自己都说不清这个任务该怎么做那你写出来的 Skill 大概率也只是把混乱的流程固化下来。3.2 写一份带示例的完整 SKILL.md拆完步骤后我把它翻译成一个完整文件。注意这里我会把 frontmatter、正文和注意事项都写全方便直接复制改造--- name: meeting-minutes description: 将口语化的会议记录整理成结构化会议纪要输出包含会议主题、背景、决策、行动项和负责人的 Markdown 文档。适合在用户提供会议文字记录并要求整理时使用。 version: 0.1.0 --- # 会议纪要整理 你是会议纪要整理专家。你擅长从杂乱的口语记录中提取关键信息并输出固定格式。 ## 执行步骤 1. 通读全文提取会议主题、时间、参会者。 2. 列出所有明确决策每条用一句话概括。 3. 找出所有行动项标注负责人和截止时间。 4. 按下方的输出模板输出。 ## 输出模板 ### 会议主题 ... ### 决策 - ... ### 行动项 | 行动项 | 负责人 | 截止时间 | |--------|--------|----------| | ... | ... | ... | ## 注意事项 - 不新增原文没有的信息。 - 如果原文没有明确负责人请填写“待确认”。 - 口语化内容转换为书面语但不要改变原意。这个版本只有最核心的规则没有塞入复杂的“高级玩法”。我更推荐你从一个最小版本开始而不是一开始就想把各种边界情况写满。因为只有跑过之后你才知道哪些规则是必需的哪些只是你的想象。3.3 放进技能目录跑三条测试输入写完后把这个文件夹放到skills/目录里然后开始测试。我通常会准备三类输入第一类完整但口语化的会议记录信息密度高。第二类碎片化聊天记录只有零星几句很多字段缺失。第三类包含大量无关讨论的会议转写需要过滤干扰。这三类输入能覆盖大部分真实情况。我第一次测试时发现模型对第二类输入特别容易出错它会把“我们下周二再看”当成行动项但实际上这句话只是随口一说。这是因为我没有在规则里写清楚“行动项必须包含明确的人名和可执行的动词”。发现问题后我在注意事项里加了一条“只提取有明确责任人和动作的条目否则不列入行动项。”这里的优化过程需要反复进行。你每跑一次就观察一次输出和理想结果的偏差然后在 SKILL.md 里增加或调整一条规则。正常情况下三轮测试之后输出稳定性会有明显提升。3.4 版本管理Skill 也会被“改坏”Skills 文件看起来只是一个小小的 Markdown但它同样需要版本管理。我遇到过的情况是为了让某个边界情况更好我增加了一条规则结果正常情况下的输出反而变差了。由于没有保留旧版本我只能凭记忆改回去浪费了不少时间。从那以后我每改一个 Skill 都会保留一个简短的变更记录。你可以用 Git也可以直接在文件末尾加一个“变更记录”小节## 变更记录 - 0.1.0初始版本建立基础流程。 - 0.2.0增加行动项判定规则过滤无关口头约定。这么做还有一个好处当你积累了很多技能后回看变更记录能帮你提炼出一些通用的编写规律。4. 我踩过的四个坑路径、引用、格式和过度提示词4.1 路径写错模型找不到文件却不会直接告诉你我第一次写的技能里正文引用了examples/input.txt我写的是请参考 skills/meeting-minutes/examples/input.txt 中的格式。结果运行起来模型相当于完全没看到这句话继续自由发挥。排查时我发现模型的加载日志里根本没有出现任何提示文件缺失的内容。这是因为路径查找通常发生在加载器层面而模型本身只是无声无息地跳过了这个引用。我的排查链路是这样的先确认技能是否真的被加载再检查日志里有没有load skill相关的记录最后逐个核对正文里的路径。后来发现是我把路径写错了正确写法是相对于技能根目录的路径请参考 ./examples/input.txt 中的格式。记住一个原则在 SKILL.md 里引用任何一个本地文件都先问自己“这个路径相对于什么位置”。不要从上到下凭感觉写最好的办法是直接复制目录结构里的路径。4.2 用了相对路径换个环境就崩和上面那个坑紧密相关另一个更隐蔽的问题是我习惯用相对路径。比如写../examples/input.txt看起来没问题但一旦技能被移动到别的位置或者被另一个目录下的脚本调用这个相对路径就会失效。我有一个实际案例一个技能在本地跑得好好的放到另一台机器的同一个平台后输出格式立刻乱了。后来才发现平台读取技能的方式是先把整个技能目录挂载到某个固定路径而我写的相对路径指向了错误的位置。更稳妥的做法是使用平台提供的“技能目录变量”或者把示例内容直接嵌入到 SKILL.md 正文中避免引用外部文件。如果你使用的平台不支持变量那就尽量把关键的示例以代码块形式放在 SKILL.md 里而不是放在examples/目录中。外部文件更适合保存大量、不常变动的参考资料而格式模板这类内容直接嵌入正文反而更稳。4.3 YAML 和 Markdown 的格式暗坑frontmatter 看着简单但踩坑概率非常高。第一个暗坑是 YAML 里的冒号。我写过description: 整理会议纪要: 提取行动项这一行会因为冒号后没加引号而解析失败。正确写法是description: 整理会议纪要: 提取行动项第二个暗坑是 frontmatter 前不能有空格或空行必须从文件第一行开始。有些编辑器会自动加个 BOM 头也会导致加载器识别失败这个问题看起来很小排查起来却极其消耗耐心。第三个暗坑是 Markdown 正文里的表格。如果你在表格中使用了竖线以外的一些符号比如|本身需要用\|转义。我第一次写包含 URL 的表格时就因为这个原因导致整行格式错乱。错误写法正确写法description: 整理纪要: 提取行动项description: 整理纪要: 提取行动项frontmatter 前有空行文件第一行就是---表格单元格里有 不转义4.4 提示词写得“太满”反而限制了模型发挥我踩过最典型的坑是在技能里写了大量“绝对化”的命令。比如你必须把行动项放在最后。 你不要输出任何多余文字。 你只能使用我给的模板。结果模型变得极其机械遇到一个稍微复杂的情况就会忽略重要信息或者生硬地套模板。有一次输入里有三个决策但因为其中一个决策“看起来不像决策”模型就把它当成普通讨论跳过了。原因是我的限制太强让模型把注意力放在了“遵守约束”而不是“理解内容”上。后来我调整了策略保留必要的规则但给自己留出解释空间。比如“务必输出行动项清单但如果你认为某句话不是行动项可以忽略”就比“你必须把每句话都归入行动项”要合理得多。提示词的本质是在引导模型不是写一份法律条文。边界越多越容易适得其反。5. 让 Skill 真正“好用”的进阶操作从小而专到组合复用5.1 一个 Skill 只做一件事我一开始写过一个大而全的技能叫write-docs想着什么文档都能生成结果非常难用。因为它的 description 只能写“生成各类文档”模型无法判断到底什么时候该加载它加载之后内部又因为指令太多而互相冲突。最后我把它拆成了meeting-minutes、weekly-report、changelog三个独立技能反而每个都变稳定了。单一职责的原则和写函数有点像如果一个函数什么都做你很难测试也很难复用。Skills 也是同样的道理一个技能只负责一种高频任务的完整链路能让description写得更准确也能让步骤更聚焦。5.2 用“输入-处理-输出”三段式设计接口我在后面写技能时会刻意用类似接口设计的方式去思考。一个技能就是一个小服务你要定义清楚它的输入、处理和输出。## 输入 - 一篇口语化的会议记录文本可以包含大量无关讨论。 ## 处理 - 提取决策、行动项、负责人与截止时间。 - 对缺失信息标记为“待确认”不自动补全。 ## 输出 - 固定 Markdown 结构包含会议主题、决策列表、行动项表格。这套三段式写进 SKILL.md 里之后模型的任务边界会非常清晰。尤其是“不自动补全”这一条能避免模型为了输出好看而编造内容。你不需要额外解释为什么模型大概率能理解这个约束和业务严谨性有关。5.3 把共用步骤拆成可被调用的子 Skill当技能数量多起来之后你会自然发现有些步骤是重复的。比如说“提取行动项”这一步会议纪要需要项目周报也需要。如果每个技能里都复制一遍后续如果格式标准改了你得逐个改很容易漏。如果你使用的平台支持技能间互相引用可以把它拆成一个独立的extract-action-items技能然后让其他技能在步骤里引用它。比如3. 调用 extract-action-items 技能提取行动项并返回结构化表格。平台不支持互相引用也没关系那就把共用规则放在一个公共文档里然后在每个技能里用相对路径引用公共文档。最差的办法才是直接复制。因为复制带来的不是效率而是维护负担。5.4 版本记录与迭代节奏技能的迭代节奏我总结下来是“小步快跑”。不要指望一次性写出完美版本也不要频繁大改。我现在的习惯是每准备改一个技能先写清楚这次要解决什么问题改完后跑三条旧用例确认旧功能没有被破坏再跑一条新用例验证新需求。如果新规则让旧用例连续两次不稳定我就回滚到上一个版本。这听起来有点工作量但对于真正会高频使用的技能来说这点投入完全值得。技能文件是所有智能体能力的底座它一旦变乱你所有依赖它的任务都会跟着乱。保持版本清晰相当于给混乱的未来买保险。最后再分享一个我自己的小技巧每个技能写完后我都会在文件末尾加一个“快速自测清单”列出三条最基础的验证指令。以后不管过了多久只要想让这个技能重新跑一遍我直接把这三条指令发给助手就行。不用重新翻文档也不用回忆当初是怎么写的。这个方法让我省了很多返工时间也希望同样能帮到你。