开头做AI Agent的项目有一个规律Demo阶段靠模型聪明落地阶段靠工程治理。跑通一个漂亮的原型很容易但当Agent要处理真实的业务场景时你会发现所有的问题都会汇聚到同一个点上——技能不够清晰、不够复用、不够可控。这也是agent-skills这类概念在一线开发者圈子里突然热起来的原因。简单说Agent Skills就是把Agent能够执行的能力从杂乱无章的提示词中剥离出来封装成有明确元数据、执行流程、输入输出规范和评估标准的独立单元。它解决的问题非常具体大上下文里的指令冲突、跨场景复用时提示词互相污染、以及能力边界模糊导致的不可控行为。这篇文章我会从技能单元的构成、设计原则、实操构建流程、技能库治理和实战踩坑五个维度展开适合正在做Agent产品落地、或者准备用Agent框架搭建自动化方案的开发者参考无论你用的是哪套框架这些方法论都能直接套用。1. 为什么Agent项目最后都会回到技能这个问题上1.1 从巨型提示词到能力单元的范式切换早期我做Agent的时候习惯把所有的指令都塞进一个System Prompt里。客户的业务规则、数据格式要求、输出偏好、工具使用方法全部用自然语言堆在一起。后果非常直观上下文越长模型对指令的遵循率越低规则之间开始互相打架改一处逻辑就要对整个提示词做回归测试。那种3000行System Prompt的项目后期维护成本高到让人绝望。后来接触到Skills的思路本质上是把Agent的能力做了一个函数化的拆解——每个技能就像代码里的一个函数有明确的名称、参数、返回值内部实现细节被封装起来外部通过描述来调用。这个转变看起来只是形式上的变化实际带来的收益是结构性的Agent不再被迫从一整篇混杂的规则中推理该怎么做而是先判断当前场景应该激活哪项技能再由技能内部定义好的流程去完成工作。这也解释了为什么大模型在2025年以后即使推理能力越来越强一线的Agent工程还是倾向于用技能库来组织能力。因为模型能力解决的是怎么回答得聪明而技能体系解决的是做事是否稳定可靠。对于生产环境来说后者往往更重要。1.2 技能体系的三个核心价值第一可复用。同一个技能可以在不同的Agent中使用比如文档摘要数据清洗JSON校验这类通用技能写好一次随处调用不必为每个Agent重新写一遍。第二可测试。技能有明确的输入输出接口可以围绕单个技能构建测试集回归时只需要跑对应的测试用例不用整个端到端流程都重新跑一遍。第三可演进。业务逻辑变化时只需要修改受影响的技能其他技能保持稳定Agent的整体行为变化是可预期、可控制的。1.3 为什么现在讨论这件事正当时我观察到一个很明显的趋势过去一年里开源社区和各路Agent框架都在往技能仓库的方向收敛。有些叫Tools有些叫Plugins有些叫Actions名字各异但底层逻辑惊人的一致——都是把Agent的原子能力标准化。这背后的驱动力是Agent的应用场景从聊天助手转到了自动化执行写代码、管订单、做分析、抓数据、发消息。这些场景要求Agent不仅会说还得会做而做的过程天然需要结构化封装。可以说技能是Agent从对话模型进化成执行系统的关键枢纽。2. agent-skills技能单元的完整构成不只是写一段提示词2.1 技能元数据让Agent知道什么时候该用我一个完整的技能单元第一层是元数据。元数据里最重要的就是技能名称和描述。千万别小看这两样它们直接决定了Agent在复杂场景里能不能正确召回这个技能。名称要符合直觉比如fetch_weatherparse_invoice让模型一看名字就知道用途。描述则要写得像给一个不太聪明的实习生看的需求说明什么时候触发、什么时候不触发、输入是什么、输出是什么、有哪些边界条件。举一个实际的例子我团队里有个query_database技能最初描述只写了查询数据库结果Agent经常在用户闲聊或者问不相关问题时也去调用它。后来我们把描述改成当用户明确要求查询或分析数据库中的数据且提供了表名、SQL或明确的数据字段时使用如果是普通的业务咨询不要调用本技能。这个改动的效果立竿见影误调用率从31%降到了6%。描述里的每一个不要都价值千金。2.2 执行流程技能的肉体技能的第二层是执行流程。这一层定义了技能被触发之后Agent具体要按什么步骤做事。流程可以简单也可以复杂但核心要求是路径清晰每一步都有产出。常见的流程结构包括前置校验、数据获取、中间处理、结果格式化、质量控制。举个例子一个生成月度报表技能执行流程大概是这样的先校验输入的时间范围和数据源配置是否合法再分批拉取数据接着做清洗和聚合然后把结果渲染成Markdown表格或图表最后检查数据完整性和关键指标是否在合理区间。每一步都有明确的输入和输出Agent在执行时就不容易跑飞。流程写得越细Agent的执行越稳定。但这里有一个度的问题——流程太细也会导致Agent失去灵活性遇到流程之外的边缘情况反而不知道怎么处理。我自己比较推荐的做法是把核心路径的步骤写清楚但对每步骤的内部实现不做限制给模型留出微调空间。2.3 上下文管理技能之间如何传接力棒技能的第三个构成是上下文管理。很多Agent项目死在多技能协作上原因就是技能之间数据传递混乱。技能A产出的结果技能B拿不到或者技能B需要的数据技能A根本没保存。这就像两个程序用全局变量通信时间一长谁改的、改什么了完全失控。我采用的方案是显式上下文契约。每个技能声明自己的输入需求和输出产物输入必须从全局上下文的某个固定字段读取输出也写入固定字段。技能之间不允许偷偷读写未声明的上下文。这样整个Agent的执行链路像一条流水线每个工位只碰自己该碰的物料然后把成品放到指定的托盘上。虽然听起来有点死板但真实场景下这种死板恰恰是稳定性的来源。2.4 质量评估与回退机制技能的最后一道防线最后是评估与回退。每个技能定义一份成功标准执行完成后Agent要自我检查输出是否符合预期。如果不符合技能内部要定义回退策略是重试一次还是降级处理还是直接报错让上层Agent决定。没有这一步技能就是盲飞。我自己习惯在每个技能的产出阶段加一句强制的自检提示请对照成功标准逐项检查输出若有偏差说明原因并修正若无法修正则返回明确的错误信息。3. 技能设计的三条硬性原则粒度、描述与边界3.1 粒度控制一个技能只做好一件事技能设计最容易犯的第一个错误是粒度失控。做粗了一个技能包罗万象内部逻辑堆成山跟巨型Prompt没什么区别做细了拆出几百个两三句话就能讲完的小技能Agent每次决策都要在几百个候选里挑召回率直线下降性能也撑不住。我的经验是拿代码函数的设计标准来做参照单一职责、高内聚低耦合同时还要考虑调用频率。如果一个动作在业务流程中反复出现比如数据清洗、格式转换、内容校验就值得单独拆成技能。如果一个动作只是某个大任务里的一小步单独拆出来反而增加检索负担那就让它在父技能的流程里自然完成。实际操作中我用一个三七开的经验法则一个普通业务Agent技能数量控制在20到50个之间。少于20个说明技能太粗Agent会频繁进入不知道下一步做什么的状态多于50个技能的召回率会明显下降而且技能间语义重叠的概率大增Agent经常选错。这个数字不是拍脑袋是实测过多个项目后的体感区间。3.2 描述写作给Agent一份好的说明书技能描述的质量直接决定Agent能不能在正确的时机调用正确的技能。我把描述写作拆成四个必需部分触发条件、输入要求、输出约定、禁忌边界。触发条件描述的是什么情况下用我越具体越好最好带上业务场景里的典型表达输入要求描述的是你需要准备哪些材料如果没有先去哪里获取输出约定描述的是我会给你什么格式的结果禁忌边界描述的是什么情况下绝对不要用我或者用了之后千万不要做什么。有个经验值得分享写描述的时候不要站在开发者自己的角度要站在模型的角度。模型判断是否调用技能时看到的是当前对话上下文与技能描述的语义匹配度。所以描述里应该多写面向场景的话少写面向实现的话。比如本技能用于判断用户表述中的时间模糊性虽然准确但不如当用户提到明天、后天、下周一、过两天、月底之前这类不确定的时间表达时使用本技能进行规范化来得实用。3.3 边界意识明确技能不做什么边界比能力更难定义但也更重要。一个只有能力描述、没有边界声明的技能就像一辆没装护栏的车——性能很强但随时可能冲到不该去的地方。纯技术层面的边界比如本技能只处理JSON格式的输入不接受XML这类容易定义。难的是业务层面的边界。我遇到过最典型的坑一个自动回复客户消息的技能能力描述写得天花乱坠但没写涉及退款、投诉、法律纠纷等敏感场景时必须将对话移交给人工客服。结果这个Agent真的在用户投诉时给出了不恰当的承诺给业务造成了麻烦。从那以后我把禁忌场景列为技能描述的必要字段每项技能必须明确写出不适用或需升级处理的场景。4. 从零构建一个Skill完整实操流程4.1 场景定义与需求拆解第一步先把业务场景拆成最小可执行的原子任务。以我最近做的一个合同审查辅助Agent为例客户的需求是帮法务看一下合同有没有风险。这个需求太大直接写技能根本没法写。拆解之后得到这些子任务合同文本解析、关键条款抽取、敏感信息识别、风险点标注、风险等级评估、审查报告生成、格式规范校验。拆解的原则是能否独立产生价值。每个子任务拆出来之后都要问一句如果只完成这一步对整体目标有没有贡献有贡献才值得做成技能。4.2 编写技能描述与元数据拆好任务后逐个编写技能的元数据和描述。这一步不要偷懒我会建议把描述当成产品文案来写。下面是我常用的一种模板结构输入本技能需要的问题类型、数据字段、前置条件以及若输入缺失时的处理方式。输出本技能会产出的结果内容与格式以及成功标准。触发条件在什么业务场景、什么用户意图下被调用。边界与禁忌不适用或禁止处理的情况以及遇到这些情况的回应方式。使用时需要注意的事项、针对特定模型行为或常见错误的处理提醒。这段内容我会反复打磨直到它的召回率稳定通过测试集。4.3 实现执行逻辑与工具调用第三步是写执行逻辑。执行逻辑有两种实现方式一种是纯提示词驱动在技能体里用文字描述步骤让模型自己执行另一种是绑定外部函数调用API、执行脚本、查询数据库。在实际生产中大多数技能是两种方式的混合外部函数负责确定性操作比如发送HTTP请求、执行SQL模型负责判断性操作比如决定查询条件、解析返回结果、判断是否满足成功标准。工具调用这块我强烈建议把所有外部接口封装成标准的输入输出协议。比如查询数据库的统一接口接收JSON格式的查询条件返回JSON格式的数据集。这样技能编写时不需要关心底层数据库是MySQL还是PostgreSQLAgent的执行逻辑也保持稳定后续替换底层实现不会影响技能本身。4.4 测试驱动的技能迭代技能写完之后不要直接上生产。我会为每个技能准备一份评估集评估集里包含三类样本应该触发技能的正样本、不该触发技能的负样本、以及触发后各种输入变化下的边界样本。跑一轮测试看三个指标召回率该触发时触发的比例、精确率触发时做对的比例、以及执行成功率触发后整个流程跑通且输出合格的比例。测试结果出来之后绝大多数情况不是技能的实现有问题而是描述和流程设计有问题。描述太模糊就改描述流程缺步骤就补步骤边界没写清楚就加边界。这个过程通常要迭代好几轮但每一轮都能看到指标实实在在的上升。我见过太多团队跳过了评估这一步直接凭感觉调提示词调了半天也不知道到底改了什么生效、改了什么拖后腿。5. 技能库治理组织、版本与可靠性的工程化方案5.1 技能库的目录结构与命名规范当技能超过二三十个之后靠记忆管理就不现实了。我把技能库按业务域和通用能力两层来组织。通用能力放底层比如数据清洗、格式化、HTTP请求、JSON校验业务域技能放上层比如合同审查、工单分类、报表生成。上层技能可以依赖下层技能但不允许跨业务域互相调用避免出现合同审查技能调用了工单分类技能这种匪夷所思的依赖。命名规范上采用动词对象的结构parse_contract、classify_ticket、generate_report。这样从文件名就能看出技能做什么也方便Agent在检索时理解技能的目的。5.2 技能注册与动态发现大型Agent系统不能靠把所有技能的描述都塞进Prompt这种方式工作token不够检索精度也不够。正确的做法是技能注册中心加动态发现技能的元数据注册到一个索引中Agent每次执行任务前先在索引中检索与当前意图最相关的少数几个技能通常3到5个再将被选中的技能的完整定义注入上下文。这里有一个关键的工程细节——检索条件不能只用一句用户原始输入去搜而要用当前Agent的任务描述已完成步骤的上下文摘要用户意图分类的组合去搜。比如用户说帮我把这个合同看一下有没有风险如果只用原话搜索合同审查辅助技能能搜到但敏感信息识别这类子技能就搜不到。用组合上下文检索之后匹配的准确率高很多实测下来召回率提升了二三十个百分点。5.3 版本管理与兼容性技能是会持续迭代的。同一个技能这周改了输出的字段格式下周改了触发条件月底可能整个流程重写。如果没有版本管理线上Agent用的技能版本无法追溯出了问题都不知道是哪个版本引起的。我现在的做法是每个技能包都带版本号并写入一个统一的变更日志技能更新先发到测试环境跑完评估集和回归集之后才上生产生产环境的Agent固定依赖某个技能版本升级需要显式操作而不是自动拉取最新版。这些看起来是基础的软件工程习惯但Agent项目里很多人因为觉得只是改改提示词就不遵守结果线上事故频发。5.4 监控技能调用的可观测性最后是监控。每个技能的执行情况都必须有日志何时被调用、调用时的输入是什么、执行是否成功、走了什么分支、耗了多少token、产出是否符合自检标准。我见过太多Agent系统是一个黑盒子用户问一个问题Agent内部调了哪些技能、每个技能做了什么完全不可见。这种系统出了错排查成本高到离谱。监控数据积累一段时间后还能反过来优化技能库。我每周会看一次技能调用的统计数据看哪些技能被高频调用、哪些技能经常失败、哪些技能被调用后又被回退。高频且稳定的技能可以考虑进一步优化性能频繁失败的技能得专项排查经常被回退的技能大概率是描述和实际能力不匹配要么改描述要么改实现。这样技能库就不是一潭死水而是一个持续进化的系统。6. 实战踩坑记录与优化手记6.1 技能描述太宽泛Agent乱调用坑一就是我前面提到的query_database事件。这个坑几乎每个人都会踩。技能描述写得宽Agent的召回逻辑就容易宁可错杀也不放过不该调用的时候也调用。排查的方法很简单——看调用日志找调用了但用户意图明显不匹配的记录然后把这类场景写进描述的边界与禁忌里。这是成本最低、见效最快的优化手段。6.2 技能粒度过细决策链路超时我还踩过一个反向的坑。早期做一个内容运营Agent我把识别标题风格判断情感倾向生成长度建议都拆成独立技能。结果Agent每处理一篇文章要先检索技能再注入技能定义硬生生把决策时间拉长了几秒而且技能之间频繁切换还容易丢失中间状态。后面我把这些捏合成一个文章风格分析技能内部流程三段走性能上来了效果也稳了。粒度的调整永远要结合真实的使用场景不能为了拆分而拆分。6.3 技能之间隐式耦合上下文互相污染第三个印象深刻的坑是上下文污染。当时两个技能都要读写一个叫current_data的上下文字段技能A写入的是清洗前的原始数据技能B却假设它拿到的已经是清洗后的数据。因为代码里字段名一样两个技能都能跑通但拼起来的结果完全错乱。排查了很久才发现是字段语义不匹配造成的。从那以后我给所有上下文字段加命名空间前缀技能内部使用的临时变量一律以技能名开头跨技能传递的数据必须走统一的数据缓冲区并明确标注数据状态。这个改造做完多技能协作的稳定性明显上了一个台阶。6.4 缺少评估集改一次坏一次最后一个教训是关于评估集的。早期我改技能完全靠这次感觉差不多来判断结果经常出现改A技能修好了场景甲的bug结果破坏场景乙上线后用户立刻反馈变差了。后来我开始给每个技能维护一个几十条的评估集每次改动后面先跑一遍回归。一开始会觉得麻烦但坚持两个月之后我的技能改动效率翻了几倍线上出问题的频率也大幅下降。如果你只能从这个系列文章里带走一个习惯我强烈建议就是为每个技能维护一份评估集。6.5 个人体验与建议做了这一路Agent项目之后我最大的感受是Agent Skills这套东西本质上是在用软件工程的思维去治理自然语言带来的不确定性。提示词的本质是不可控的你可以靠重试来祈祷它这次更好但技能体系的本质是可控的你可以靠设计、测试和监控来保证它稳定地输出。两者的心态完全不一样。如果你手里的Agent还在被巨型提示词压得喘不过气试着从最小的一个动作开始把它拆出来、封装成一个技能、给它配好描述、跑几轮评估你会很快体会到那种终于可控了的感觉。最后再分享一个实操中的小技巧技能库建成之后我会定期让Agent自己对着历史对话日志做一次技能覆盖度分析看看哪些高频场景其实还没有对应技能覆盖。这一步每次都能找出几个之前完全没注意到的能力缺口算是用Agent管Agent的一种低成本方式。