我见过太多AI Agent项目死在什么都会一点但什么都做不精这个坎上。模型本身的能力越来越强但纯靠对话式Prompt去驱动它完成复杂任务结果往往是输出飘、流程乱、难以复用。而agent-skills这个方向恰好就是解决这个问题的它把Agent需要掌握的做事能力沉淀成一套可复用、可组合、可维护的技能包让Agent从会说变成会做。这篇文章我会从技能体系的设计思路、SKILL.md的标准写法、参考数据的组织方式到完整技能从零到一的全流程以一个实战项目的角度拆透这个主题全程经验向、可复制。1. 内容整体设计与思路拆解先说清楚一个概念Agent Skill到底是什么。很多人会把Skill和Prompt混为一谈觉得给模型写一段详细的Instructions就是在建技能。我跟你说这事儿没那么简单。Skill的本质是把一件具体任务的完整解法打包给Agent——这里面既包含一段清晰的执行指引也包含完成这件事所需要的领域知识、数据结构、模板样例、边界约束甚至配套的脚本或代码。你可以把它理解成给Agent发了一本岗位说明书外加一本工作手册而不只是一句好好干。为什么这个思路在Agent工程里越来越重要核心原因是模型的上下文窗口再大也是有限资源。你不可能把做每一件事所需要的所有背景知识都塞进System Prompt里。Skill的价值就在于——按需加载。Agent遇到某个任务时识别出对应的场景自动去调用那本手册里只属于这个场景的内容而不是每次都把所有知识背在身上。这一点解决的不只是上下文爆炸的问题更是让Agent的执行精确度上了一个台阶。再说说Skill和Tool、Workflow的区别。Tool通常是一个函数或APIAgent主动调用来获取外部能力Workflow是固定的流程编排死板但可控。Skill夹在两者之间——它是一套有弹性的执行策略有步骤框架但不至于僵硬到无法应变有工具调用但不只是单一接口。它更像是给Agent配备的专业技能库Agent在这个库里找方法而不是被绑死在某一条路径上。我当时在设计agent-skills这个项目时最先定下的不是细节而是一条主线要做成可插拔的技能架构。什么意思就是说任何技能都能独立开发、独立测试、独立维护然后在运行时挂载到Agent上。谁家Agent要用就给它装哪几个技能包不要的拆掉不影响其他部分。这样整个Agent系统会变得非常干净模型负责理解和决策Skill负责执行和经验沉淀Agent本体只是一个轻量调度壳。这个架构决策直接决定了后面的文件结构、触发机制、测试方式和文档规范。所以如果你也想做Agent方向的技能化改造我建议你一开始就克制住在Prompt里堆功能的冲动多花点时间把技能边界和组合关系想清楚后面能省掉大量返工。1.1 为什么Agent需要一套技能而不是一堆提示词讲个我踩过很多次的坑。早期做Agent我习惯把任务说明写成一个巨大的Prompt里面包含步骤、示例、语气、输出格式动辄两三千字。结果呢效果时好时坏。模型经常在步骤中间跑偏要么跳过某个关键环节要么输出格式七扭八歪。你反复调Prompt它换一个输入场景又崩给你看。后来我才想明白Prompt本质是一次性消费品它没有任何记忆和复用能力。你今天给模型写了一份处理客户邮件的Prompt明天换一个场景处理投诉工单又得重新写一份而且里面90%的基础方法论是重叠的。这种每次都从零教的模式模型的稳定性完全靠你Prompt写得有多详细运气成分很大。Skill模式从根上解决了这个问题。研发团队把处理客户邮件这件事拆出步骤框架先读取邮件内容再按业务线分类然后匹配应答策略模板最后生成回复并归档。这个框架作为一个技能包存好模型在遇到这个场景时加载它。下次遇到类似场景模型不需要重新摸索直接套用已经验证过的执行路径。执行质量从每次碰运气变成了稳定复现最佳实践。这是Skill最核心的竞争力它把单次经验变成可长期沉淀的资产。随着项目迭代你的技能库会越来越厚Agent的能力上限也会跟着水涨船高。相比之下单独维护一堆Prompt既难沉淀又难共享时间久了只会变成没人敢动的屎山。1.2 技能体系设计的三个关键决策第一技能粒度怎么切。这是最容易纠结的地方。切太粗一个技能里混杂多种任务类型模型执行时依然要自己分辨跟没有技能区别不大切太细技能数量爆炸Agent在触发判断上就会高概率选错或漏选。我的经验是按任务闭环来切粒度少按动作来切。比如撰写周报是一个任务闭环可以做成一个技能而生成图表汇总数据属于动作不要独立成技能它们应该是周报技能内部的一个步骤或者作为技能可调用的底层工具存在。第二技能之间的依赖关系怎么处理。有些技能天然会依赖另一个技能的执行结果。比如生成竞品分析报告这个技能内部可能需要抓取公开信息提炼关键变化生成对比表格这几个步骤其中提炼关键变化可能本身就是一个可复用的子技能。我在项目里定下的规矩是技能之间允许调用但调用关系必须在SKILL.md的依赖说明里讲清楚不允许隐式依赖。这样技能树才是可管理的。第三技能的触发判断权交给谁。这是新手最容易忽略的地方。现在主流做法是让模型自己决定当前任务该用到哪个技能所以每个SKILL.md的开头都要写清楚本技能的适用场景和不适用场景。如果这段写得太模糊模型很容易在不相干的场景里误用技能产出四不像的结果。我在项目里测试过适用场景写得越具体、关键词给得越明确技能的命中率和执行效果就越好。这又回到那个老问题你在设计阶段偷的懒都会在执行阶段加倍还给模型。2. 核心细节解析与实操要点进入实操环节之前先把skill包的标准结构讲清楚。现在业界包括几个主流Agent框架基本形成了一个共识性的文件组织方式你可以不照抄但理解这套结构能帮你少走很多弯路。一个标准的技能包通常包含SKILL.md技能的主描述文件相当于说明书执行手册Agent加载技能时首先读的就是它reference目录存放技能运行时可能需要的参考资料比如模板文件、领域术语表、示例输出、代码片段assets目录存放技能使用的静态资源比如图标、样张图片如果技能涉及程序化逻辑还会携带自己的脚本文件或模块这套结构的核心思想是一个目录即一个技能。目录名就是技能名SKILL.md是入口其他文件按需加载。这样做的好处是技能的完整性、独立性、可移植性都很好——直接把目录拷贝到另一个Agent系统里只要适配层不冲突技能就能无缝迁移。SKILL.md本身怎么写我单独拿出来说。它不是让你写一篇散文而是有固定信息的结构化文档。建议至少包含这几块内容技能名称和一句话说明适用场景触发条件越具体越好执行步骤分步骤写明必要时附上步骤间的判断分支输入要求说明这个技能需要哪些输入信息输出要求明确交付物的格式和质量标准边界与限制写清楚哪些事情这个技能不应该做依赖项需要调用哪些工具或其他技能很多新手写SKILL.md容易犯的毛病就是只写步骤不写边界。结果模型在边缘场景里疯狂试探既费token又费调试精力。边界写清楚对模型是一种保护。2.1 SKILL.md一份真正好用的Agent执行手册长什么样我给你看一个我实际在项目里用过的SKILL.md片段我觉得比讲一百句抽象理论都管用。这是一个会议纪要与行动项生成技能的主文件。先说名字我建议用连字符小写英文比如meeting-minutes-generator这样在文件系统、命令调用、跨Agent传输时都不容易出兼容问题。然后是适用场景这一节我会写得非常明确。比如适用于用户提供会议录音转写文本、会议笔记、聊天记录等材料要求输出正式会议纪要不适用于用户仅口头描述刚才开了个会但没有提供原始材料此时应先要求用户提供材料你看我把不适用于也写出来了这就是边界意识。模型看到这条规则后会主动向用户索要材料而不是脑补一份会议纪要出来。这样的错误在实际使用中是真实高频发生的靠Writing的好Prompt解决不了必须靠边界规则硬约束。执行步骤这一节我会细化到能让模型按部就班走完。大概会是第一步提取会议基本信息包括时间、参会人、主题第二步按讨论议题原文梳理讨论要点保持客观中立第三步识别每一项决议和对应的负责人、截止时间第四步按模板压缩并格式化输出。每一条都不是空泛描述而是带着明确的动作对象和产出物。模型拿到这个技能后基本是照着操作流程走自由发挥空间被压缩到最小输出质量自然就稳定了。2.2 参考数据与上下文压缩别让技能变成token黑洞技能包里的reference目录用好了是利器用不好就是灾难。我见过有团队把一个技能下挂了几十份文档Agent每次执行都要把全部文档读一遍光上下文输入就花掉几万token成本和延迟都扛不住。这个问题的根源在于把参考数据和必须全量读取的数据画了等号。正确的做法是按照需要精确逐字的和只需要语义检索的来分流。比如固定模板、字段定义表这类必须精确引用的直接放进reference目录执行时全量加载反正体量小。而知识库性质的材料比如产品历史FAQ、历史案例库不直接读全文而是在技能描述里写清楚当需要了解XX问题的处理先例时请从reference/history.md中检索相关内容。模型会按需到指定的参考文件里做局部检索而不是被动接收全文注入。这一招能帮我把单个技能的平均上下文占用压掉一半还多。另外注意reference里的文件别塞那种有了更好、没有也行的装饰性内容。凡是不能直接支撑执行步骤的材料都不要放进来。技能包应该像战术腰封只挂最用得上的东西不是行李箱什么都往里塞。3. 实操过程与核心环节实现这一部分应该是对大家最有用的。我完整复盘一个技能从设计到落地的全过程案例选一个通用性比较强的行业动态监测简报生成技能。这个技能的需求很常见用户给出一个行业或几家公司的名字Agent定期抓取公开动态做结构化梳理输出一份简报。第一步定义任务边界和目标输出物。我要做的这个技能最后交付的是一份包含动态摘要、影响判断、关注信号三块内容的简报。输入信息包括监测对象公司名、产品名或行业关键词、时间范围、简报语言。这个边界定下来后面的所有设计都围绕它展开。第二步写SKILL.md。我把流程指定为先解析监测对象和时间范围再触发联网搜索抓取公开信息然后按分类模板梳理动态最后判断每条动态的影响等级高/中/低和信号属性机会/风险/中性生成简报。执行步骤里我会强调只基于公开可验证信息不臆测。第三步准备reference模板。我建了一个dynamic-brief-template.md里面定义了简报的完整结构监测对象概况、本期重要动态列表每条动态包含时间、来源、事件概述、影响判断、趋势小结、下期关注信号。有了这个模板模型的输出格式就固定下来了不用每次临时发挥。第四步写边界规则。这个环节我特别重视——技能声明不面向特定个人或非公开信息进行挖掘不提供投资建议或倾向性结论信息采集仅面向合法公开途径。这不是在找麻烦反而是让技能在真实使用中更安全、更可信。Agent严格按照公开、合规的信息边界执行输出的简报才经得起验证和长期使用。第五步测试调优。我会准备三组测试输入一家名不见经传的初创小公司、一家成熟大公司、新能源电池这样的行业关键词。为什么选这三种因为它们的公开信息密度差异极大最容易暴露技能的执行问题。测试结果发现初创公司的信息量太少需要把时间范围自动放宽大公司的信息太多需要增加去重和优先级排序规则。这些小发现都反哺到SKILL.md里技能的鲁棒性就是这么磨出来的。3.1 触发条件与场景识别让Agent在正确时机加载技能精心做好的技能如果Agent用不上等于白做。触发条件设计是决定技能命中的关键。我建议在SKILL.md的适用场景里不要只写一句用户需要了解行业动态时使用这太模糊了。你要站在模型的视角想它怎么知道用户需要了解行业动态更好的写法是列出典型触发信号。比如用户明确提到监测一下XX帮我跟踪XX的最新变化XX最近有什么动静出一份XX的周报或者在对话上下文里出现了监测对象名称并且用户要求汇总梳理盘点近期信息。把这些信号写清楚模型的判断准确率会明显提高。还有一类触发场景容易被忽略——Agent在完成一个复杂任务的过程中发现自己缺少行业背景信息此时它天然需要调用这个技能来补充背景。所以技能描述里最好有一句话说明它在组合场景下的用途例如在输出市场策略建议之前如果需要对目标行业做动态梳理可调用本技能作为输入前置步骤。这一个设定能让技能天然嵌入到更复杂的任务流里价值会被放大很多。3.2 多技能协作编排如何让技能之间互相配合不打架技能多了以后一个新问题就浮出水面技能之间怎么分工协作我在项目里测试过的做法是主技能管流程子技能管环节。比如我要做一个市场策略建议技能它的执行步骤里会写明第一步调用行业动态监测技能获取背景信息第二步调用竞品分析技能分析竞争格局第三步基于前两步产出的结构生成策略建议。这三个技能之间的衔接完全靠SKILL.md里的依赖项声明。主技能知道自己需要什么样的输入数据子技能声明自己能产出什么格式的数据两者配对成功流程才能顺畅走通。我在实际测试里经常遇到的问题是子技能输出的字段命名和主技能预期的不一致。解决办法是在依赖说明里不仅写技能名还要写清楚传递的数据字段名的映射关系。这个细节在文档里只是几句话但在实际运行中能省掉大量排错时间。还有一点要注意尽量避免循环调用。就是技能A依赖技能B技能B又回头依赖技能A。这种依赖环一旦出现Agent很容易陷入反复调用的死循环。我建议在依赖声明里写清楚本技能是否会间接调用自身做一次环检测发现环就及时调整技能粒度或流程设计。3.3 实测调优记录一次完整的技能调试现场我印象很深的一次调试是在做合同关键条款提取技能的时候。第一版测试我喂进去一份标准租赁合同模型输出的提取结果在条款分类上出现大量错位比如把违约责任里的内容归到了付款条件里。我第一反应是要不要换更强的模型但冷静下来分析后发现根本不是模型能力的问题而是我对条款分类标准的定义太粗糙了。分类里的违约责任和付款条件本来就有语义重叠——催缴、逾期、滞纳金既可以算付款规则也可以算违约后果。模型没有明确标准它就按自己的理解随意归类。这个问题的解法是在reference目录里加一个条款判定规则文档里面用决策树的方式写清楚当条款包含金额支付时点优先归为付款条件当条款包含补偿、罚则、解除权时优先归为违约责任当两者都涉及按主导语义归类。加完这份规则之后同一份合同的提取准确率从不到六成直接升到九成以上。这次调试给我的启发很大技能调试的重点不是调模型而是找你没讲清楚的地方。每次出错几乎都能追溯到SKILL.md或reference文档里一个模糊的表述。把模糊变清晰效果立竿见影。所以我现在做技能的第一步就固定为先写清楚再测效果而不是先跑起来再修Patch。4. 常见问题与排查技巧实录做了一段时间Agent技能开发我整理了一份高频问题画像。这些问题在项目初期几乎每天都要踩一遍写出来希望能帮你提前避开。症状根因解决办法技能似乎从未被触发适用场景写得太笼统模型无法识别在SKILL.md里补充具体的触发信号关键词和典型用户问法技能被错误触发触发条件与相似技能重叠增加边界规则明确不适用场景必要时在主技能中设置排他判断执行结果时好时坏步骤描述模糊缺少分支逻辑细化步骤写明如果...则...否则...的条件判断输出格式混乱只写了流程没给输出模板在reference目录放一个明确模板让Agent严格套用上下文token急剧飙升参考数据全量加载把知识库类参考改为按需检索只保留模板和必读规则在参考资料中多技能协作时数据接不上依赖项的字段映射未定义在依赖说明里写明传递字段名和数据格式我特别想展开讲一下技能被错误触发这块。这个问题的隐蔽性很强而且常在系统上线一段时间后爆发。比如我做一个文档翻译技能本意是用来处理整篇技术文档。后来用户开始拿它翻译聊天消息你会发现它在逐句翻译时毫无问题但在处理带有上下文的信息时时常出错。原因在于技能内部规则是按处理整篇文档的场景设计的把它用在短消息场景里规则本身就失真了。我的解决思路是在技能描述中增加一段本技能不适用场景字数低于50字的消息翻译请使用通用翻译能力。这样就把技能和基础能力的边界重新分清楚。4.1 测试策略覆盖黄金路径还不够偏难怪场景才是分水岭很多团队做技能测试只测几条黄金路径比如用户正常提问、模型正常输出。我建议一定要补上几类恶意刁难的场景测试技能的质量高下立判。第一类是空输入测试。用户没说监测对象直接说出一份简报。这种情况下技能是应该报错还是自动提示用户补充信息我在设计里明确写成监测对象缺失时优先向用户询问不自行假设。写清楚之后Agent的行为就非常规范不会自作主张挑一个公司分析给用户看。第二类是复合意图测试。用户说帮我看看这几家公司最近在干嘛顺便整理一下它们的对比——这个任务里同时牵涉到动态监测和对比分析两个技能点。这时候Agent是在一个技能里完成还是串联两个技能如果整个链路没有测试过结果常常是不可控的。我会专门验证这类边界任务必要时在SKILL.md中补充当任务同时包含也...时的处理规则。第三类是信息缺失测试。用户要求生成简报但给出的时间范围极为模糊比如最近。我会在技能里定义最近的默认映射动态监测场景下默认近7天。这类规则的收益在真实使用中特别大因为用户永远比你想象中更随意。4.2 长期维护技能库如何持续迭代不腐烂技能开发和普通的功能开发有一个显著区别技能永远不会写完它会随着使用反馈不断迭代。因为模型能力在升级、业务场景在变化、用户的提问方式在演化。没有一套长期维护机制技能库很快会变成一堆过时的、失灵的、没人敢动的代码。我的维护策略有三个抓手。第一版本化。每一个技能包都内置VERSION字段内容发生重大变更时递增版本号。这样即使某个版本出问题也能快速回滚。第二变更日志。每次修改SKILL.md都要在CHANGELOG里记录改动内容和原因。不要觉得这是形式主义三个月后的你会感谢现在的你。第三干净移除。当一个技能一个月都没被触发过就主动检查它是否还能满足当前的需求场景或者是否有新的技能覆盖了它的职责。该归档的归档该合并的合并保持技能库的精简。技能系统的真正竞争力不在初始设计多漂亮而在于它能不能随着实践越来越聪明。从agent-skills这个项目出发我最大的体悟是做Agent不是做一个无所不知的万事通而是给模型套上一套越用越顺手的工具箱。如果你正打算构建自己的技能库记住两件事——边界写清楚经验沉淀好。做到这两点你的Agent离稳定可靠就不远了。