做Agent项目做久了你会发现一个规律第一版Demo跑通的时候最兴奋后面每一次往系统里塞新功能都是一次对耐心的考验。我在经历了“提示词越写越长、工具函数越堆越多、Agent偶尔聪明偶尔犯傻”的混乱阶段之后最终把注意力锁定在了一套叫 agent-skills 的工程化思路上。这套思路没有多玄乎本质上是把Agent可复用的能力拆成一个个独立、可描述、可测试、可版本管理的“技能单元”让Agent在需要的时候自己去选择合适的技能来调用。这篇文章把我从零搭建技能库的完整过程、踩过的坑、以及最后沉淀下来的方法都整理出来写给同样在做Agent应用、并且开始被“能力碎片化”问题困扰的开发者。不管你是刚接触Agent开发的新手还是已经在生产环境里跑过一阵子Agent服务的老手只要你的系统里出现了“工具函数数量失控”“同一个逻辑在多处复制”“模型经常选错调用对象”这类苗头我建议你花几分钟把这篇看完。我会从最基础的概念讲起一直讲到测试、评估和版本迭代尽量把能直接抄作业的部分都给你。1. 为什么Agent项目做着做着就变成了“技能泥潭”1.1 从“什么都能干”到“什么都干不好”的真相我最早做Agent的时候跟大多数人的路径一模一样先写个入口函数在系统提示词里把所有能调的能力列一遍然后让模型自由发挥。刚开始只有三五个函数的时候效果相当惊艳——模型像一个聪明的实习生你交代一句它自己就能把流程串下来。但等到业务方开始提需求今天加一个“查物流”明天加一个“算运费”后天加一个“解析合同模板”系统提示词从几百字膨胀到几千字工具列表越拉越长。问题开始冒出来模型开始把相似功能的工具搞混明明该调用“查询订单状态”它却调了“查询物流轨迹”启用新工具之后老工具的调用率被莫名其妙挤掉同一个业务逻辑因为不同调用方的参数格式不同被迫写了三个几乎一样的函数。这就是我说的“技能泥潭”。它的本质问题是我们把Agent的能力看成了一堆平铺的函数却没有给这些能力建立边界和认知。模型面对一个又长又乱的工具清单它的“选择能力”会迅速退化。你不是在开发一个Agent你是在维护一个越来越难用的函数库。1.2 技能Skill与工具Tool的本质区别很多人分不清“技能”和“工具”觉得只是换了个叫法。我一开始也这么想直到我按技能的思路重构项目之后才明白这两者的差异是结构性的。工具Tool通常是一个单一函数入参简单、职责具体比如“把字符串转成大写”“发送一个HTTP请求”。它是无状态的、原子的。技能Skill则是一整套能力封装它包含但不限于一个面向模型的能力描述告诉模型“这个技能在什么时候该用、什么时候不该用”一组输入参数定义以及每个参数的含义和约束一段完整的实现逻辑内部可以调用多个工具、多个步骤甚至调用其他技能相关的测试用例和使用示例供开发者和Agent共同参考打个通俗的比方工具是工具箱里的一把螺丝刀技能是一整套“换门把手”的作业指导书加配套工具加验收标准。模型拿到的是后者它不需要自己拆解步骤只需要知道“我要换门把手调用这个技能就对了”。这个区别带来的直接好处是模型的选择成本大幅降低了。它不再需要从几十个细碎函数里挑出几个来组装流程而是直接挑一个最匹配的技能剩下的事交给技能内部去处理。这也是agent-skills这套模式最核心的价值。2. 一个合格Agent Skill的内部结构应该长什么样2.1 让Agent“看懂”的第一层技能描述我见过太多人写技能描述的时候敷衍得像在写注释“获取订单信息的函数”。这种描述对机器理解毫无帮助。模型不是一个通过函数名猜功能的编译器它是一个需要通过自然语言建立“什么时候该做什么”认知的推理器。一份合格的技能描述至少包含三块内容能力概述这个技能做什么输出的结果形态是什么。适用场景什么样的用户意图、什么样的上下文条件下应该调用它。排除场景什么情况下不要调用它尤其是容易混淆的相邻场景。我举一个实际例子。假设你要做一个“客户工单摘要”技能不要写成“获取工单详情”而是写技能名称客户工单摘要生成 能力概述根据工单ID获取完整的工单对话记录、处理状态、客户等级和最近处理人 并生成一段不超过200字的工单摘要供客服快速接手。 适用场景用户要求总结一下这个工单、这个case现在什么情况、 我明天要接手这个工单给我个背景等意图时使用。 排除场景用户只询问工单状态如这个工单处理到哪一步了 此时应调用工单状态查询技能不要生成摘要。稍微偏长的描述没有关系关键是要把决策信息给足。模型会根据这段描述来判断自己该不该调用这个技能描述里的每个字都可能影响最终调用准确率。2.2 技能的参数定义与实现逻辑参数定义是技能的另一半关键。我推荐用JSON Schema来定义这样一方面可以做运行时校验另一方面主流Agent框架都能直接识别。参数设计上有一条铁律能少就少必填必须少。模型在调用技能的时候要靠自然语言去理解用户意图然后把这些意图映射到参数上。参数越多、越复杂模型填错值的概率就越高。比如一个发邮件的技能你把“邮件正文格式”“是否添加签名”“是否需要抄送上级”“优先级”全塞进去模型大概率会在某个边缘case里漏填或者填错。我一般控制在3~5个参数以内超过这个数就考虑拆技能。例如“给客户发邮件”这个技能参数就是收件人、主题、正文、是否需要附件。其他东西全部收进技能内部处理不让模型操心。实现逻辑上技能的代码可以简单也可以复杂但要注意一个原则技能内部不要直接跟模型交心。它就是一个黑盒输入参数输出结构化结果。内部可以调第三方API、查数据库、算分、组装Prompt再调一次LLM都可以但对外暴露的接口要稳定。这样后期替换实现方案的时候模型侧完全无感。2.3 一个可以直接套用的目录结构我目前在生产环境里用的技能目录结构长这样供参考skills/ ├── order_summary/ │ ├── SKILL.md # 技能描述给模型看的 │ ├── schema.json # 参数定义JSON Schema格式 │ ├── main.py # 技能实现主逻辑 │ ├── requirements.txt # 该技能独立依赖 │ └── tests/ │ ├── test_normal.py │ └── test_edge.py ├── send_email/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ └── tests/ └── ...每个技能独立文件夹自己的描述、参数、实现、测试全放一起。这样做最大的好处不是“看起来很规范”而是单个技能可以独立测试、独立部署、独立回滚。哪个技能出了问题直接把它摘掉或者换个版本重新加载不影响其他技能也不用动Agent的主流程。3. 技能库的搭建路线从轻量方案到框架级方案3.1 轻量路线文件夹加约定最不容易烂尾如果你的Agent还在早期验证阶段工具数量不到20个我不建议你一上来就引入重型框架。用最朴素的约定就能把技能库跑起来一个文件夹表示一个技能里面放SKILL.md和实现代码然后用一个简单的注册器扫描目录把技能自动挂载到一个统一接口上。这个方案的优点是零依赖、好理解、改起来快。缺点是技能多了之后需要自己处理能力发现、并发控制、依赖隔离这些事。不过对于早期项目来说这些都不是瓶颈先把迭代速度提上去最重要。我当时就是从这种“文件夹即技能”的方案起步的大概用了两个多月直到技能数量超过30个、协作开发的同事超过三个人才考虑切换到更结构化的方案。3.2 框架路线借助现成的Agent编排层当技能数量上来以后我就开始考察现成的Agent框架对技能的支持程度。现在主流的一些Agent框架都已经不是单纯的工具调用层而是原生支持“技能”这一抽象提供技能注册、选择策略、追踪、评估这些配套能力。这里我给出我当时对比的几个维度对比维度轻量自建方案框架级方案上手成本低一天搞定中高需要学习框架API技能发现自己写扫描器框架内置可观测性自己埋点框架自带追踪扩展能力一般强支持插件锁定期风险低中要跟着框架版本走选择标准就一条你的团队能不能接受框架的抽象和版本演进。如果能就上框架省下大量重复劳动如果团队里有人觉得框架太重那就先用轻量方案但一定要在设计初期就保持“技能文件夹”这个结构不变这样以后无论换什么框架迁移成本都只是写一个适配器。3.3 我的选型决策过程我自己最后是走了一条中间路线沿用文件夹即技能的结构但自己写了一个很薄的加载层把技能目录暴露成一个统一的调用接口然后在加载层内部接入了可插拔的“技能选择器”。这个选择器负责根据用户的请求和对话历史决定调用哪个技能。这样既保住了轻量方案的低成本又给后面加更聪明的技能选择策略留了口子。等你技能数量继续膨胀发现自己写的选择器扛不住了再在这一层替换成框架级能力也不迟。4. Agent如何“挑技能”选择策略与描述工程4.1 描述质量直接决定调用准确率技能库建好之后下一个核心问题就是模型到底怎么知道该调哪个技能如果技能数量少直接在系统提示词里把每个技能的描述列出来让模型看完再选这是可行的。但技能一旦超过15个左右单靠提示词列举就会遇到问题——上下文被大量技能描述占掉模型也容易在长列表里产生选择疲劳。这个时候我强烈建议换成“预筛精排”两步走的方案。第一步先用检索的方式把候选技能从全部技能里筛出最相关的5~8个第二步把这几个候选技能的完整描述交给模型来做最终决策。预筛阶段可以用关键词匹配、向量召回或者两者结合。我给每个技能都预计算了一个描述向量用户的请求来了之后先做向量相似度检索再配合几个硬性规则比如用户请求里包含特定实体时强制命中某类技能把候选集缩到很小。这样既节省了上下文空间也大幅提升了选中准确率。4.2 参数设计里的“防呆”技巧模型在填参数的时候不是每次都能理解用户的潜台词。为了减少错误我在参数设计上用了几个“防呆”手段。第一个手段是给参数加别名。比如“订单号”这个参数我在描述里明确写清楚它也可能被用户叫做“单号”“order id”“交易流水号”让模型在抽取的时候更宽松。第二个手段是给枚举型参数加默认值。比如“导出格式”这个参数默认值设为“CSV”如果用户没明确说就填默认值而不是让模型猜一个。第三个手段是对模糊参数做二次确认。比如时间范围如果用户只说了“最近”我会让技能内部把它解析成一个合理的默认窗口比如近7天而不是把解析压力抛给模型。这些细节单独拿出来都不起眼但是叠在一起技能调用成功率能提高不少。我实际测过一个订单查询技能加了别名和默认值之后参数抽取成功率从82%升到了94%左右。4.3 少样本示例怎么放进去如果你的技能是给大模型驱动的Agent用的还有一个很管用的东西少样本示例。在技能描述里附上2到3个“用户提问正确调用参数”的例子模型会更快地学会这个技能的使用边界。示例要覆盖两个方向一个是正常用法一个是容易出错的邻近场景。比如“工单摘要生成”技能正常示例是“帮我看看这个工单讲了什么”反例示例是“这个工单现在到哪一步了”并标注这种情况下应该调用“工单状态查询”。反例的作用是帮模型划清边界这比正面示例的效果还要明显。5. 技能不上线不算完测试、评估与灰度发布5.1 单技能验收测试不能只测正常路径技能写完了第一件事是跑单元测试。我要求每个技能必须覆盖三类用例正常调用、边界输入、异常输入。正常调用好理解。边界输入包括空字符串、超长文本、缺失参数、多参并发等场景。异常输入则模拟用户乱说话或不给全信息的情况验证技能能不能给出一个合理的错误提示而不是直接抛异常。这里特别提醒一个坑技能的测试数据不要用线上真实数据尤其是涉及用户隐私的业务。我见过有团队直接把真实工单内容灌进测试用例既违反隐私合规要求后续维护也麻烦。用脱敏数据或者构造数据就足够了关键是覆盖行为分支而不是追求数据真实。5.2 端到端评估看的不只是调用成功率单技能通过测试之后还要放到整个Agent流程里做端到端评估。我维护了一套评估问题集每个问题都标注了“期望调用的技能”和“期望的输出形态”。跑完一轮之后我会重点看三个指标技能选择准确率模型最终选中的技能是不是标准答案。参数抽取正确率选中技能之后参数值是不是被正确填充。任务完成率从用户视角看最终输出是否解决了问题。这三个指标经常出现分离的情况。比如模型选对了技能但参数填错了或者技能调用完全正确但Agent后续的对话策略把用户带偏了。只看任何一个单一指标都会骗自己必须三个一起看。5.3 灰度发布与回退机制技能更新是一个很容易被忽略但出事概率很高的环节。我个人的习惯是新版本技能先在小流量比如5%上跑一天同时开着全量日志观察技能选择分布和错误率有没有异常。如果新版本引入了回归直接回退到上一个版本整个过程要求在一分钟内完成。所以每个技能在加载层里都要做成可以独立切换版本的形态。不要直接覆盖main.py而是保留版本目录或者用配置中心来控制当前启用哪个版本。这种“技能级灰度”的成本很低但能避免很多线上事故。我有一次更新了邮件技能的正则表达式导致一部分合法邮箱被误判为非法就是因为没有灰度直接全量上了结果被用户投诉了一下午。自那以后配置中心里没有“技能版本号”这个字段我是不允许接线上发布的。6. 从单技能到技能生态沉淀过程中的几条避坑心得6.1 技能重叠是最大的隐形杀手技能库发展到一定规模最常出现的问题是技能边界重叠。比如你有“订单概览”技能和“订单明细”技能用户说“帮我看看这个订单”模型到底该调哪个如果两个技能的描述里都没有明确排除场景模型就会随机选调用行为变得不可预测。我的处理办法是每次新增技能之前先检索一遍现有技能库看有没有功能范围相交的技能。如果相交超过30%要么合并成一个技能要么在描述里把分工写死。这是技能库日常维护里最重要的一件事比写新代码还重要。6.2 技能文档与版本管理技能是代码资产更是团队协作资产。每个技能的SKILL.md我要求必须写清楚三个时间点创建日期、最近修改人、修改原因。不能只改代码不更新文档否则一个月后没人知道这个技能为什么长这样。版本管理上我直接给技能库单独开了一个Git仓库技能的每次变更都走独立的提交记录。发布的时候加载层读取的不是“最新代码”而是“某个指定版本号对应的快照”。这样技能库虽然长在同一个仓库里但每个技能的生命周期是独立的互不干扰。6.3 让新手也能安全地新增技能最后分享一个我摸索出来的协作小技巧给团队写一个“新增技能检查清单”里面列着“描述是否包含排除场景”“参数是否超过5个”“测试是否覆盖边界输入”“是否和现有技能冲突”“版本号是否递增”这几项。任何人提交新技能的时候照着清单过一遍就行。别指望每个人都能写出完美的技能描述但有了清单至少能拦住80%的低级问题。这个检查清单我现在还在持续更新。每踩一个新的坑就往里面加一条。技能库不是建完就结束的东西它是会随着业务和团队的成长一直演化的。你能做的最好的事情就是把它的地基打稳然后让每一个新增技能都有清晰的边界、可靠的测试和清楚的文档。