这几天把“agent-skills”这个项目从头到尾梳理了一遍感触挺深的。说实话最早看到这个标题我还以为是又一轮概念包装但实际做下来发现它解决的是一个特别具体、特别疼的问题为什么你的Agent看起来什么都能聊一落到具体任务就翻车为什么同一个Agent换个场景就不会干活了为什么团队里每个人都在给Agent加指令加到最后系统变得又笨又慢这些问题根子上都和“技能”这件事有关。这篇东西我会把我自己从设计、实现、测试到维护Agent技能的全过程摊开讲。不是纯理论是拿真实项目做底子的经验整理。适合正在做Agent应用开发、或者想在团队里把Agent从“玩具”推向“生产力工具”的人。看完你至少能回答三个问题Agent Skills到底是什么为什么它是刚需以及怎么从零构建一套不会被模型用错的技能体系。1. 先搞清楚Agent Skills到底是什么1.1 一个真实的需求场景我先说一个我自己遇到的场景。之前做一个企业内部的文档处理Agent接了好几个工具有解析PDF的、有做向量检索的、有调外部API查数据的。刚开始觉得挺简单工具都现成的让模型自己选着用不就行了结果一上线就露馅。比如用户说“把这份合同里所有关于违约责任的条款摘出来顺便看看有没有超过法律上限的赔偿金”。模型倒是知道该用PDF解析工具但解析完之后它不知道该清理文本、不知道该按条款语义去分块、更不知道该去查法律上限。它把PDF内容直接扔给用户一长串乱码一样的排版用户当场就崩溃了。后来我意识到模型缺的不是“工具调用能力”而是“完成这个任务的方法论”。工具是散的方法论是打包的。而agent-skills这个项目要做的就是把方法论打包成标准化的技能单元让模型拿到一个任务的时候脑子里有一个清晰的、经过验证的执行路径。你如果把Agent想象成一个新入职的实习生工具就好比公司给他配的电脑和软件而技能则是“老员工带他跑通一遍的标准操作手册”。你光给实习生电脑他当然不知道活儿该怎么干但你要是给他一份写清楚了“第一步做什么、第二步判断什么、遇到什么情况走什么分支”的操作手册他就能稳定地产出。1.2 技能、工具、工作流三者到底差在哪聊Agent Skills很多人会把它和“工具Tools”“工作流Workflow”搞混。我在项目里也纠结过一阵后来用一句话把它们拆开了工具是你给Agent提供的“手”解决的是“能做什么”的问题比如能调API、能读文件、能发请求。工作流是你自己写死的“流程”解决的是“按固定顺序做什么”的问题比如先查数据、再生成报告、再发邮件。技能介于两者之间它是“完成某类任务的可复用方法”包含的不只是调哪个工具还包括怎么判断、怎么处理中间结果、什么情况下停止。我做一个生活化的类比。工具是一把菜刀工作流是今天这张菜单——回锅肉、麻婆豆腐、酸菜鱼你按顺序做。技能则是“切菜的刀法”什么食材该切片、切丝还是拍碎切的时候怎么下刀更安全切完怎么处理边角料。有了刀法哪怕菜单换了你也能应付。所以技能最大的价值是“复用”和“泛化”。它不是为某一个具体任务写死的而是为某一类任务提炼出来的可迁移能力。这一点在我实际写技能的时候体会特别深很多技能表面上是在解决一个任务拆开之后本质上是在教模型一套通用的思考方式和操作习惯。2. 为什么Agent Skills会成为刚需2.1 从“会思考”到“会干活”的关键一跳过去两年大家疯狂卷模型本身的推理能力以为模型聪明了Agent就能干活了。但真正做应用的人心里都清楚推理能力和执行能力之间有一道巨大的鸿沟。模型再聪明它也不知道你公司的报销流程是先走财务系统还是先贴发票它也不知道你们合同的编号规则是什么它更不知道“这个字段为空的时候应该去查上一个流程的审批记录而不是直接报错”。这些“组织内部的隐性知识”不会长在模型里只能通过技能的方式给到它。我在做agent-skills的过程中最大的感受就是技能不是在教模型“变得更聪明”而是在教它“更懂你们这边的规矩”。一个模型接三家公司同样的能力三套完全不同的技能配置最后跑出来的效果天差地别。这就像是同一个职业选手换了教练、换了战术手册之后赛场表现能差出一个量级。2.2 技能体系解决的核心矛盾你可以把Agent项目拆成两层一层是模型和框架一层是业务逻辑。行业里大部分团队把精力怼在第一层结果就是模型换了一版又一版Prompt调了一轮又一轮Agent还是不稳定。为什么会这样因为业务逻辑是复杂且持续变化的你把它塞在Prompt里Prompt会越来越长越来越互相冲突最后模型根本不知道该听谁的。技能体系解决的核心矛盾就是把“业务逻辑”从“对话上下文”里剥离出来变成一个一个结构清晰、边界明确的独立模块。我做过一个对比测试同样的任务一组用“一段超长Prompt 一堆工具”实现另一组用“结构化技能 精简Prompt”实现。结果前者的成功率大概是72%后者能到91%。更关键的是前者改一次需求要动Prompt里的一大段话牵一发动全身后者只需要增删一个技能文件其他完全不受影响。所以如果你觉得自己的Agent项目“越调越乱”大概率不是Prompt技巧不行而是你缺了一层“技能管理”的架构。2.3 技能工程的生态位再往大了说agent-skills踩中的其实是“技能工程Skills Engineering”这个大趋势。现在业界已经慢慢形成一个共识Agent的能力天花板取决于你给它构建了多少高质量技能而不只是你用了多强的模型。这就像一支球队球星决定了球队的下限但战术体系和训练方法决定了球队的上限。模型是球星技能体系是战术板。你可以花大价钱买最好的球星但如果没有战术体系场上依然会踢成一盘散沙。对于个人开发者来说技能工程还意味着另一件事你的资产不再只是Code和Prompt而是你沉淀下来的技能库。做过的项目会结束代码会重构但一套成熟的技能库可以跨项目复用、迁移、迭代。我做agent-skills这段时间最上瘾的就是这个——每一次给技能加测试、加边界处理都是在给自己的技术资产增值。3. 技能怎么设计才不会被模型用错3.1 技能骨架一个完整的技能长什么样我在agent-skills里实践的技能结构参考了当前社区比较流行的做法核心是一个带特定结构的目录。一个规范的技能通常包含这样几个部分skills/ pdf-contract-review/ SKILL.md scripts/ parse_and_chunk.py extract_clauses.py references/ legal_limits_guide.md tests/ test_sample1.docx test_sample2.docx先说SKILL.md这是技能的灵魂。它用自然语言写清楚“这个技能是什么、什么时候用、怎么用、有什么注意事项”。模型不会先读代码再理解技能它先读的就是这份Markdown。所以这份文件写得好不好直接决定模型会不会在正确的时候用出正确的技能。然后是scripts存放具体的实现代码。这部分不是给模型“读”的而是给模型“执行”的相当于技能的手脚。references是参考资料和最佳实践模型在执行过程中可以查阅。tests是测试文件用来验证技能有没有达到预期效果。一个常见的误解是技能就是“带自然语言描述的API”。我以前也这么想但实际用下来发现区别很大。API只告诉模型“这个函数能做什么”而技能还告诉模型“这个任务的完整执行路径是怎样的、中间会遇到什么坑、什么情况下该放弃”。技能自带“经验”这是它和工具最本质的区别。3.2 写好技能描述一半的工程在写提示词我给团队定了一个规矩写技能之前先花一半时间写SKILL.md里的描述尤其是前面的frontmatter。一个技能的元数据最少要有两个字段name和description。name要短、要唯一description要写出“什么时候用”和“什么时候不用”这部分决定模型能不能在合适的时机把技能选出来。举个反例。我早期写过一个技能description是“处理Excel文件”。听起来没问题对吧结果模型在用户说“帮我把这个表格转成PDF”的时候也调了它在用户说“算一下这个表的总和”的时候也调了它甚至用户说“打开某个Excel文件”它也调它。原因就是描述写得太笼统模型不知道这个技能到底擅长什么。后来我改成这样--- name: excel-data-cleaning description: 用于对Excel表格数据进行清洗和标准化处理包括去重、缺失值标记、格式统一、异常值识别。适用于需要对表格数据做分析和加工的场景。不适用于简单的文件格式转换、表格阅读和基础筛选。 ---改完之后命中率明显上来了。模型对“什么时候不该用”这条信息非常敏感你一定要给它划清楚边界。另一个心得是技能描述里不要写太多“你是一个专家”这类虚话多写“遇到什么情况、按什么顺序、做什么操作”。模型需要的是操作指导不是身份认同。3.3 技能粒度太大没人调太小没价值技能的粒度是设计阶段最纠结的问题。一开始我倾向于做“大技能”比如做一个“财务分析技能”想着一个技能解决财务领域所有问题。结果模型调用的时候犹豫不决因为这个技能的任务范围太广它不知道当前这个具体任务该不该用、用起来要改哪些参数。后来我改成“中粒度”拆成“财务报表读取”“财务比率计算”“异常波动检测”三个技能。每个技能的任务边界清晰模型更容易判断。但也不要拆得太细我试过把“读取报表”和“解析PDF”拆成两个技能结果模型经常漏掉第二个导致流程中断。我现在的经验是一个技能应该对应“一个完整的小任务”。什么是完整的小任务就是“给定某个输入能产出一个明确的、可验收的结果”。比如“从PDF合同里提取违约条款并输出结构化JSON”这是一个完整小任务。而“了解PDF合同”这不是任务是领域不适合做技能。4. 从零构建一个技能实操全流程4.1 场景选型什么值得做成技能构建技能的第一步不是写代码而是选场景。不是什么活儿都值得做进技能里的。我总结了三问判断法这个任务是不是频繁出现只出现一次的场景写Prompt临时解决就行沉淀成技能反而增加维护成本。这个任务是不是有固定的方法论如果每次处理方式都不一样做成技能也难以标准化。这个任务是不是经常因为“经验不足”而失败如果模型做这个任务经常漏步骤、做不对说明它需要技能里的经验加持。我用这三个问题卡过一堆候选场景最后留下的不到三分之一。比如“生成周报”就非常适合做技能高频、有固定结构、但模型经常写得空洞或者漏掉关键指标。而“帮用户起一个公司名字”就不适合太发散没有标准路径技能帮不上忙。4.2 技能文件怎么组织确定要做之后第一步是创建技能目录。我个人的习惯是给技能分类建文件夹再按技能名建子目录。目录名用短横线分隔全部小写比如pdf-contract-review、excel-data-cleaning。这个命名规范虽然简单但在多技能场景下能减少很多混乱。SKILL.md是整个技能的核心我建议按这个模板来组织内容--- name: 技能短名称 description: 一句话说明技能用途包含适用场景和不适用场景。 --- # 技能名称 ## 什么时候用 ## 核心步骤 ## 注意事项 ## 失败时的兜底策略 ## 参考示例注意核心步骤一定要写清楚“顺序逻辑”不要写成“可以做什么”的清单而要写成“先做什么、再做什么、如果什么就怎么做”的流程。我见过很多人把SKILL.md写成功能列表那对模型来说一点用都没有它需要的是决策路径。代码部分我一般放在scripts目录里。我的建议是一个脚本只干一件事函数入口要简单输入输出尽量用JSON而不是直接读文件。原因是模型在调用脚本时容易在参数处理上出错入口越简单出错的概率越低。4.3 测试与评估你说能用不算模型用起来才算这一步是我在agent-skills项目里吃过最多亏的地方。早期我写技能从来不做正式测试写完了自己跑一遍觉得没问题就上线。后来发现我作为人觉得“没问题”和模型在实际场景里调用时“没问题”完全是两码事。后来我养成了一个习惯每个技能上线之前至少准备10个测试用例覆盖正常情况、边界情况和故意刁难的情况。测试时不光要看结果对不对还要看模型“走的路”对不对。比如有的技能模型最后输出的结果是好的但是中间调错了一个脚本绕了一大圈这种也要记下来因为说明SKILL.md里的引导不够清晰。我分享一个具体的测试方法把测试用例输入给Agent开启完整日志重点看三件事。模型有没有在正确的时机选择这个技能模型有没有按照SKILL.md里写的步骤走模型遇到中间报错时是按兜底策略处理还是自己瞎编三个都过技能才算过关。最理想的是让不同的人或不同版本的模型测试同一个技能因为不同模型对提示的理解习惯不一样能发现很多单模型测试发现不了的问题。4.4 把技能接入Agent技能接入Agent的方式取决于你用的框架。我在agent-skills项目里用的是最通用的做法把技能列表注入到系统提示词中并给模型提供一个动态发现技能的入口。具体来说我在系统提示词里不会把所有技能完整贴出来那样太占上下文。我只会贴一个技能清单包含每个技能的名称和一句话描述。当模型判断某个任务需要某个技能时再通过“读取技能详情”的动作加载完整的SKILL.md。这样既保证了模型知道有哪些技能可用又不会让上下文爆炸。接入之后还不能算完。我一般跑一周左右的“灰度期”把技能只开放给部分用户同时录下所有调用日志。一周后拉数据看调用次数、成功率、失败原因分布。如果调用次数很少那就是description写得不好模型没发现它如果失败率很高那就是SKILL.md里写的步骤有问题模型执行不下去或者中途走偏。5. 一线踩坑技能不生效、冲突、退化怎么办5.1 常见问题速查表我在做agent-skills这段时间把踩过的坑整理成了一张速查表。这些问题在社区里也经常看到基本属于“人人都可能遇到”的范畴。现象根本原因解决办法技能模型从来不调用description太笼统或太长重写description加适用边界该调技能的时候不调不该调的时候乱调技能命名或描述有歧义删掉模糊词汇增加反例描述技能执行一半就停SKILL.md里没有兜底策略补充失败分支和退出条件多个技能互相冲突行为不稳定技能边界重叠合并技能或明确优先级技能刚上线效果好过几天变差依赖的模型版本或外部API变了记录技能依赖版本定期回归测试上下文很长模型读取技能超时SKILL.md太长精简步骤把详细内容移到references技能内部脚本经常报错入参校验太宽松脚本加严格参数校验和清晰报错这里面我想单独拎出来说一个技能刚上线效果好过几天变差。这个坑最隐蔽也最容易甩锅给模型“变笨了”。但真相往往是你技能里依赖的外部接口更新了或者模型的默认行为因为底层版本调整发生了变化。所以我现在对所有技能都做“依赖锁定”SKILL.md里写清楚技能依赖的模型版本、外部API版本每次大版本升级后强制回归测试。5.2 技能维护与版本迭代很多人都把技能当成一次性资产写完就不管了。这是大忌。技能是需要维护的而且维护成本比代码更高。因为技能本质上是在“和模型对话”你在SKILL.md里写的内容换了模型版本之后可能就不再有效了。我自己的经验是每次模型框架升级都要对核心技能做一次回归测试看描述命中率、执行成功率有没有变化。给技能做版本管理也很重要。我的做法是每个技能目录下放一个CHANGELOG.md记录每次改了什么、为什么改、测试结果如何。别看这个文件小它能救大命。有一次一个技能行为异常我翻日志查到是三天前改了一个参数再往前翻CHANGELOG两分钟定位到问题。技能还有一个很反直觉的特点更新的频率不能太勤。我一开始发现模型用技能时出了点小偏差就赶紧改SKILL.md结果今天改一下、明天改一下技能越改越乱模型行为反而更不稳定。后来我改成“攒问题批量改”把一周的问题记录下来周末集中梳理一次性改掉然后统一回归测试。这个方法让技能稳定性好了很多。5.3 技能安全与权限边界最后聊一个容易被忽视但非常致命的问题技能安全。技能的运行权限比普通Prompt大得多因为它包含代码。一旦技能被模型在错误场景下调用可能造成不可预期的后果。我在项目里给技能设置了三层安全边界技能清单准入新增任何技能都要过代码审查不允许线上Agent无约束地加载新技能。脚本运行沙箱技能内部的脚本一律在隔离环境运行禁止直接访问外网和敏感目录必须显式申请权限。高风险操作二次确认比如删除文件、发送邮件、提交订单这类操作技能只能生成“操作建议”真正执行前必须由用户手动确认。有一件事我印象很深。早期我写了技能去自动整理用户网盘里的文件分类、重命名、建目录。理想情况是把文件都整理得漂漂亮亮但这个技能有一次误判把用户一个项目的文件当成了重复文件差点批量删掉。从那以后我就把“删除”类操作全部降级为“移动到回收站”并且强制二次确认。这让我意识到技能越强权限边界越要收紧否则一个看起来很有用的技能可能变成定时炸弹。另一个要点是技能内部尽量不要写“万能操作”代码。比如“执行任意Shell命令”这类能力绝对不要出现在技能实现里。模型对代码的掌控力没有你想的那么强给它的能力越大失控的风险就越大。做技能要有“最少权限原则”——只给模型完成这个任务必要的能力多一点都不给。6. 写在最后的几句心里话做agent-skills这段时间最大的体会是Agent技能的构建本质上不是技术问题而是“知识显性化”的问题。我们每个人、每个团队都有大量做事的经验和规矩这些事情靠语言很难一次说清但可以通过技能的方式一条一条沉淀下来变成模型能理解和执行的东西。这个过程有点像带新人。你带第一个新人的时候要反复教、反复纠正但如果你把这些经验写成一本好的操作手册后面再来十个新人都能上手很快。技能就是Agent世界的“操作手册”写手册的时候多花点心思后面能省下十倍甚至百倍的解释成本。最后再分享一个小技巧如果你刚开始尝试技能工程不要急着把已有的Prompt和工具全部改造成技能。先挑一个你做得最熟、最频繁的场景老老实实做一个技能跑通全流程再逐步扩展。技能工程最忌讳的就是贪多嚼不烂一个打磨到位的技能比十个粗制滥造却无人调用的技能有价值得多。
