把Agent技能做厚：从一次"agent-skills"落地实践聊起的工程经验
做AI应用开发的朋友，最近应该都绕不开"Agent技能"这个词。我在某跨平台智能助手项目里负责Agent侧的能力建设，前后折腾了大概三个月，把一套名为agent-skills的技能体系从无到有搭了起来。这篇内容不聊高大上的架构图，就讲我实际踩过的坑、调过的参、推翻重来的设计，以及最终沉淀下来的一套可复用方案。如果你正在做Agent技能编排、工具调用、Prompt模板管理相关的工作，或者准备在项目里引入Agent能力，这篇文章应该能帮你少走不少弯路。
先说清楚agent-skills到底解决什么问题。大模型本身的能力是通用的，但实际业务场景里，用户要的是"这个Agent会做某件事"——比如自动整理周报、查询业务数据并生成分析、按格式输出合同初稿。通用模型不会自动掌握这些细分技能，而agent-skills就是把这层"技能"显式地定义出来、封装好、可插拔、可复用。换句话说，它像是给Agent配了一套可扩充的"职业能力目录"，让Agent不只是能聊天，而是能干活。
这套方案适合谁？适合正在做Agent应用开发的工程师、AI产品经理、以及想从单一Prompt工程往系统性Agent工程迁移的团队。无论你是用现成的Agent框架，还是自己从零写编排逻辑，这里面的设计思路都能直接借鉴。我尽量讲得贴近实际操作，不会默认你已经读过多少论文，但也不会把基础概念反复啰嗦。
1. 内容整体设计与思路拆解
1.1 从Prompt到Skills，到底多了一层什么
最早我们团队做Agent，和大多数人一样，就是写Prompt。把系统提示词越写越长，往里塞指令、塞示例、塞规则。起初效果还行，但随着任务变多、场景变复杂，问题就来了：一个超长Prompt里塞了十几种任务逻辑，模型经常顾此失彼，调了这个任务的表现，另一个任务就退化。更麻烦的是，每次新增功能都要在同一个Prompt上动刀，测试回归成本高得吓人。
agent-skills的核心思路，是把"模型需要做什么"重新组织为"一组可独立定义、独立维护、独立调用的技能单元"。每个技能单元有自己完整的定义：触发条件、输入参数、执行步骤、输出格式、所需工具、约束规则、示例。Agent在收到用户请求后，先判断命中了哪个技能，然后加载那个技能的完整配置来执行，而不是所有逻辑都堆在一次对话里。
这样说可能有点抽象，打个比方。Prompt方式像是一个全能店员，你给他一本非常厚的操作手册，让他在任何时候翻到对的章节按章执行。手册越厚，翻找越慢，还容易翻错页。agent-skills方式则像是给店员配了一套标准化工卡，每张卡对应一种服务，来什么客人抽什么卡，卡片上的步骤清晰明确，做完归档。整体效率和准确性都会好很多。
1.2 技能粒度怎么切，是第一步也是最关键的一步
技能拆分粒度这个问题，我们一开始没想清楚，走了不少弯路。太粗，一个技能里塞了好几个任务逻辑，本质还是大Prompt换了个马甲。太细，技能数量爆炸，匹配和检索都变难，还增加了维护成本。
我后来的经验是，按"用户意图的原子性"来切。一个技能应该对应一个不能被继续拆分的任务意图。比如"生成周报"是一个技能，"把周报发给指定收件人"是另一个技能，"汇总本周项目数据"又是另一个技能。后面两个虽然服务于第一个，但它们本身是可以独立被用户请求的任务。
实际操作中，我们用了两层结构来平衡粗和细。第一层是技能目录，按业务域分类，比如"内容生成类""数据分析类""日程管理类"。第二层才是具体技能，每个技能只做一件事。这样Agent在匹配技能时，先粗分类再精匹配，准确率和效率都有保障。
1.3 为什么先定义元数据结构
技能定义不能随手写，需要一个稳定的元数据结构。我们是先定了技能描述文件的结构，再写具体技能内容。回头来看，这个顺序太重要了，如果没有一个统一的元数据结构，后续的技能注册、动态加载、效果评估全部都会乱套。
我们的技能描述文件基于JSON格式，核心字段包括技能ID、技能名称、描述、触发条件、输入参数Schema、调用工具列表、执行工作流、输出约束、示例集合、版本号。每个字段都有严格的规范，描述字段必须说明技能适用场景和边界，参数Schema遵循标准JSON Schema格式，示例至少三组且覆盖正常和异常场景。
等你意识到没有元数据结构时，往往已经写了十几个技能，每个风格都不一样，要返工统一，那个成本很高。所以如果让我给一个最实在的建议，我会说：第一个技能还没写之前，先把元数据结构定下来，哪怕之后要改，也比完全没有规范强。
2. 核心细节解析与实操要点
2.1 技能描述怎么写才不会被误匹配
技能描述这个字段看着简单，实际是决定整个技能匹配效果的关键。模型不是靠技能ID来匹配的，它靠的是对技能描述的理解。描述怎么写，直接决定用户意图能不能被准确路由到正确的技能。
实践下来有几个写法要点。描述要包含三部分：技能适用场景、关键操作对象、典型请求句式。适用场景说明什么情况下应该触发这个技能，关键操作对象说清楚针对什么东西，典型请求句式给模型提供匹配参照。比如"生成周报"这个技能，描述里我只写"根据用户提供的工作内容和时间范围，生成结构化周报"，但示例里就要写上"帮我写一下这周的周报""生成上周工作总结"这类具体句式。
还有一个容易踩的坑：不要在一个技能描述里用"以及""或者"这类词扩展出多个职责。比如"生成周报以及整理会议纪要"，这听起来像是两个技能，但放一起，训练和匹配都容易糊。一个技能描述应该只有一种意图，出现多个意图就要拆。
2.2 参数Schema设计的两种模式
技能要执行，一定需要输入参数。参数Schema设计有两种模式，我们分别称为"显式参数模式"和"上下文提取模式"。
显式参数模式适合参数明确、用户请求里基本会直接给出的场景。比如会议纪要技能，参数就是会议时间、参会人、会议主题、讨论内容。这种模式下，Agent从用户请求里抽取参数值，填进Schema，交给技能执行。
上下文提取模式适合参数不明确、需要依赖多轮对话上下文的场景。比如"检查项目风险"技能，参数是项目ID和检查维度，但用户可能不会明确说出来，需要Agent从对话历史里推断。这种模式对Agent的推理能力要求更高，也更容易出错。
我的建议是：能显式尽量显式。上下文提取虽然灵活，但不可控因素太多，经常会因为推断错误导致技能执行失败。如果非要支持，一定要在技能定义里写清楚推断逻辑，并且提供默认值兜底。
2.3 技能内部的工作流编排
技能不能只是定义参数和输出格式，中间的执行步骤才是核心。我们把技能内部的工作流设计为一系列步骤节点，每个步骤节点可以是：调用一个工具、调用一次模型推理、执行一段既定逻辑、或者等待用户确认。
举个例子，"生成数据分析报告"这个技能的工作流：第一步提取数据查询条件，第二步调用数据查询工具获取原始数据，第三步执行数据预处理逻辑，第四步调用模型生成分析文本，第五步按模板组装报告，第六步输出结果。每个步骤的输入输出都被明确定义，一个步骤的输出就是下一步骤的输入。
工作流编排最难的是容错。模型调用可能失败，工具可能超时，数据可能为空。每个步骤都需要定义失败处理策略：重试多少次、直接报错还是走降级方案。我们最初的编排完全没有考虑这些，一旦中间某一步挂了，整个技能直接崩溃，用户体验很差。后来每个步骤节点都加上异常处理策略，情况才稳定下来。
3. 实操过程与核心环节实现
3.1 技能定义文件的长什么样
直接放一个我们实际在用的技能定义示例，字段和描述方式可以参考。这里展示"周报生成"技能的简化版本：
{ "skill_id": "weekly_report_generator", "skill_name": "周报生成", "description": "根据用户提供的工作内容、时间范围与关键成果，生成结构化周报。适用于周报、双周报、项目进展汇报等场景。", "version": "1.2.0", "trigger_conditions": [ "用户请求生成周报或工作总结", "用户提供工作内容并要求整理为周报格式" ], "parameters": { "type": "object", "properties": { "time_range": { "type": "string", "description": "周报覆盖的时间范围，格式为YYYY-MM-DD至YYYY-MM-DD" }, "work_items": { "type": "array", "items": {"type": "string"}, "description": "本周完成的工作事项列表" }, "key_results": { "type": "array", "items": {"type": "string"}, "description": "关键成果与数据指标" }, "next_plan": { "type": "array", "items": {"type": "string"}, "description": "下周工作计划" } }, "required": ["time_range", "work_items"] }, "tools": ["current_date_lookup", "calendar_query"], "workflow": [ { "step": 1, "action": "parameter_collect", "description": "从用户请求中收集参数，缺失项在步骤2中集中询问" }, { "step": 2, "action": "user_confirmation", "description": "向用户确认收集到的参数，允许用户补充修改" }, { "step": 3, "action": "tool_call", "tool_name": "current_date_lookup", "description": "获取当前日期，用于自动计算默认时间范围" }, { "step": 4, "action": "model_generate", "description": "调用模型按周报模板生成正文内容" }, { "step": 5, "action": "format_output", "description": "按markdown格式组装周报，包含工作回顾、成果展示、问题风险、下周计划四个部分" } ], "output_schema": { "type": "object", "properties": { "report_content": {"type": "string", "description": "Markdown格式周报正文"}, "generated_at": {"type": "string", "description": "生成时间"} }, "required": ["report_content"] }, "examples": [ { "user_input": "帮我把这周的工作整理成周报，主要做了首页改版和性能优化", "expected_output": "包含首页改版进展与性能优化数据的结构化周报" } ] }这里有个关键细节：工具列表里我只放了调查日期和查日历，没有直接放大型模型本身。在我们的设计里，模型是默认执行引擎，技能定义里只需要声明外部工具调用。当然这只是一个约定，具体怎么分看你自己的框架。
此外，技能描述里我用了"适用于"这个限定词，就是为了帮助模型更好地判断什么场景用它。真实场景里用户说话千奇百怪，比如"给我写个汇报"，到底是不是周报？如果没有清晰的场景限定，匹配就容易出错。
3.2 技能注册与动态加载机制
技能文件写好了，还需要一套机制把它加载进Agent系统。我们采用的是"技能注册中心+懒加载"方案。所有技能启动时注册到技能中心，注册信息包括技能ID、名称、描述、参数Schema、版本号。Agent在运行时先做用户意图与技能描述之间的匹配，命中了就去加载对应的技能文件，然后实例化执行。
这个过程中有一个需要特别注意的点：技能文件本身是静态数据，但技能执行是动态过程，所以技能定义和技能实例要解耦。我们实现了技能实例池，每个技能同时可能有多个实例在不同的会话中执行，互不干扰。
懒加载的好处是启动速度快，不会因为技能数量增加而拖慢系统初始化。坏处是第一次调用某个技能时需要额外加载时间。我们的解决方式是预热策略——系统启动后，后台异步将高频技能预加载到内存。这样线上调用时基本感知不到加载延迟。
3.3 技能匹配准确率提升的实战调优
技能匹配是整个agent-skills体系里最影响体验的环节。匹配错了，后面全错。我们摸索了一套多级匹配方案，准确率从最初的六成左右提升到现在稳定在九成以上。
第一级是关键词粗匹配，对用户输入做分词，计算与每个技能标签的命中率。这一级速度最快，但准确率一般。第二级是语义匹配，将用户输入嵌入化后与技能描述嵌入化做相似度计算。第三级是模型重排，候选技能在两条以内时，让模型做最终判断，选择最合适的技能。
三级之间有阈值控制，粗匹配如果置信度足够高就直接返回，不再做后续计算，降低延迟。如果模棱两可，就往下走。模型重排虽然准确率最高，但延迟也高，所以只在必要时才用。
实际调优过程中发现，语义匹配的效果严重依赖技能描述的写法。描述写得越接近用户真实请求的表达方式，匹配率就越高。所以我们在每个技能上线的第一周，都会收集实际匹配失败的Case，反哺修改技能描述。这是一个持续迭代的过程，不是一劳永逸的。
4. 常见问题与排查技巧实录
4.1 技能触发不了，问题往往出在描述上
技能触发不了是最高频的问题。排查思路是：先看匹配日志，确认用户请求最后命中了哪个技能。如果连候选技能里都没有目标技能，那就是描述和用户表达之间的语义差距太大。处理方式是补充典型请求句式到描述里。
还有一个场景很典型：多个技能描述之间存在重叠。比如"写邮件"和"写周报邮件"，两个技能描述都提到了邮件，用户说"写封邮件给老板汇报周报"，触发哪个就随机了。这种问题只能从描述边界入手，明确各自的适用场景。
4.2 技能执行中断与恢复机制的演进
技能执行到一半挂了，最常见的原因是工具调用超时或者模型返回格式异常。最初我们遇到这种问题就直接给用户回一句"技能执行失败"，后来发现用户根本不知道发生了什么，也没有办法恢复。
后来我们给技能执行加了状态持久化。每个步骤执行完，把状态快照写入会话上下文。一旦中途失败，用户可以选择从断点重试，而不是从头再来。对于多步骤技能来说，这个体验提升非常明显。
另外，工具超时不能只靠重试解决，要分析超时的根因。有一段时间我们的数据查询技能频繁超时，后来发现不是查询本身慢，而是查询条件构造太宽泛，导致底层数据服务压力过大。定位到根因后，优化了参数校验逻辑，超时率显著下降。
4.3 技能回归测试怎么组织
新增技能或者修改技能描述，很容易影响其他技能的行为。我们做了一个专项回归测试集，里面收集了大量用户问题样例，覆盖每个技能的典型请求和边界情况。每次技能变更之后，全量跑一遍回归，比较技能执行结果是否在预期范围内。
这里想提醒一点：LLM的输出有随机性，回归测试不能只看一次结果就下结论。同一个Case至少跑三遍，取多数结果来判断。我们甚至专门做了一个结果比对工具，自动对比不同版本技能在相同Case上的输出差异，差异超过阈值就提示人工确认。
回归测试集要持续扩充，每次线上出现匹配错误或者执行异常，相关的用户输入和临时修改后的技能定义追加到测试集里。这样测试集越来越厚，系统的质量和稳定性也随之提升。
4.4 性能优化清单：延迟、并发与成本
Agent技能体系的性能压力比想象中大。技能匹配、流程编排、模型推理、工具调用，每个环节都有延迟，叠加起来用户感受就很明显。我们做了一系列优化，列几个见效最快的。
技能匹配阶段增加缓存，用户短时间内类似的请求直接命中缓存结果，避免重复计算语义向量。工具调用阶段使用连接池和超时控制，避免单次调用拖垮整个技能。模型调用阶段优先复用上下文，减少重复传参造成的Token浪费。并发控制方面，技能实例池限制了单个技能的最大并发数，超出部分排队等待，防止系统资源被某个高频技能占满。
成本优化主要靠两个思路。一是减少无效调用，技能工作流里如果某个步骤的结果可以预判就不调用模型；二是模型分级，简单任务用低成本模型，复杂任务才用高性能模型，技能定义里可以指定模型等级。
5. 从技能到能力体系的扩展思考
5.1 技能间如何协作形成复杂流程
单个技能只能完成单一任务，但用户的实际需求往往是复合的。比如"生成周报并发送给主管"，这涉及周报生成技能和邮件发送技能。在agent-skills的框架下，我们支持技能间协作，基本形式是"技能编排"。
我们引入了编排层，通过一个主技能定义子技能的执行顺序、传递参数和结果汇总逻辑。主技能本身不直接干活，只负责调度。这样既保持了每个技能的独立性，又能组合出复杂能力。
编排层的设计有一个原则：子技能之间的数据传递必须通过明确的上下文对象，不能隐式共享全局状态。否则两个技能之间的参数冲突和污染问题会让人崩溃。
5.2 技能的效果评估闭环
技能不能上线就完事，需要持续追踪效果。我们建立了一套效果评估机制，从四个维度衡量：触发准确率、执行成功率、用户反馈满意度、性能开销。每个指标都定义好计算方法，在技能运行日志的基础上做统计分析。
触发准确率看的是用户请求是否被正确路由到目标技能。执行成功率看的是一个技能从头到尾执行完的比例，以及各步骤的成功率。用户反馈满意度通过用户的后续行为隐式判断，比如是否继续追问、是否接受输出结果。性能开销则包括延迟、并发占用和Token消耗。
这套评估机制的价值在于，它能提前暴露问题。有一次某个技能的执行成功率突然下降，查日志发现是参数Schema变更引起的兼容性问题，好在评估机制提前发出了告警，否则影响面会更大。
5.3 多语言与跨平台技能的抽象
我们这套agent-skills体系一开始是针对文本场景的，后来扩展到多语言和跨平台，做了一些抽象设计。核心思路是让技能定义与执行引擎分离。技能文件只描述能力，由不同平台的执行引擎按各自方式执行。
比如，同一个"日程查询"技能，在手机助手端调用本地日历接口，在Web端调用云端日历服务。技能定义不变，执行适配层不同。这个抽象带来的复杂度提升不小，但避免了每个平台重新开发一遍技能的尴尬。
多语言支持方面，技能描述和参数Schema支持多语言版本，匹配阶段会根据用户语言选择对应的描述版本。这里有个细节要注意：用户明明说的是中文，技能描述只有英文版本的，语义匹配效果会受影响。所以至少保证常用技能有主流语言的描述版本。
6. 实际落地后的经验与建议
6.1 推行agent-skills最容易遇到的三类阻力
技术方案本身是一回事，团队落地的阻力是另一回事。我们团队在推行agent-skills过程中，遇到过三类阻力，可能也有参考价值。
第一类是原有Prompt的惯性依赖。已经调好的Prompt，大家不愿意拆成技能。这需要从维护性和可测试性的角度说服团队，通过对比同场景Prompt和技能方案的效果差异来建立信心。
第二类是技能质量参差不齐。不同成员写的技能风格不统一，导致整体效果忽高忽低。解决方式是建立技能编写规范和Review流程，核心技能必须经过另一名同学确认才能上线。
第三类是评估体系缺失。没有一套客观的评估标准，技能好不好全凭感觉。这也是为什么我把效果评估机制放在前面讲，它应该和技能开发同步推进，而不是事后补。
6.2 团队协作时的技能版本管理
技能文件本质上是代码资产，需要用版本管理的方式维护。我们的做法是把技能定义文件放在独立的仓库里，遵循严格的提交规范和审批流。每个技能都要求写变更记录，这样回溯问题时能定位到具体版本。
版本管理要和线上发布衔接起来。我们设计了金丝雀发布机制，新版本的技能先在少量流量上生效，观察效果后再全量推广。如果发现问题，可以快速回滚到上一个版本。这个机制在技能变更频繁的迭代期极其有用，几乎每周都会用到。
还有一个容易被忽视的点：迁移到agent-skills框架后，旧的Prompt文件不会立即消失，中间会有一段新旧并存的过渡期。过渡期的兼容问题要提前规划。我们最初就是同步维护旧的Prompt流程，确认新技能完全稳定后才逐步下掉，整个过程持续了两周左右。
6.3 后续可以这样扩展
agent-skills这套体系的扩展空间比较大。我目前在看的方向包括：技能效果数据如何反哺技能描述优化，让技能迭代过程更偏向数据驱动而不是手工调整。另一个方向是技能的跨团队复用，各业务线内部都有一些通用技能，把这部分技能抽成公共层，能节省大量重复开发。
还有一个值得关注的点是技能定义的自动化生成。现在编写一个技能还是要靠人工，比较耗时。理想中的状态是，给定几个正反示例，自动生成技能定义草稿，人工只需要做审核。我们这边已经做了一些实验，效果尚可但还达不到完全自动化的程度。
如果让我用一句话总结这几个月做agent-skills的感受，就是：Agent的体验下限取决于模型，上限取决于技能体系。模型能力再强，如果没有把技能做扎实，用起来的体验照样会拉胯。相反，技能体系做扎实了，即使换一个稍弱的模型，整体体验也不会差太多。这也解释了为什么我这么愿意在技能定义和编排上下笨功夫——因为这里投入的每一分精力，最后都会体现在用户能感知到的稳定性和准确性上。
