去年年底我在复盘一个内部Agent项目时发现一个很有意思的现象同样一个模型、同样一套工具接口Agent的最终表现却千差万别。同一个工具花半小时写清楚描述、设计好参数与返回值结构和直接往system prompt里塞一段“调用说明”实测效果能差出两三倍。这个差距的根源几乎都落在“技能Skills”这一层上。所谓agent-skills本质上就是我们在模型能力之外为Agent单独构建的一套可复用、可评测、可持续维护的行为能力封装。它不是一段临时的提示词也不只是把几个API塞给模型去调而是把“模型能做什么”和“Agent该怎么做”彻底解耦让Agent在面对具体任务时像工具箱里取用成型的工具一样精准、稳定地把技能拿出来用。这篇文章我不会讲太虚的概念主要围绕我在实际项目中搭建Agent技能层的完整思路为什么要把技能单独抽出来、一套技能系统应该包含哪些组成、怎么管理技能的演化和冲突以及最关键的一点——怎么量化评估“技能到底好不好使”。如果你正在做一个稍具规模的Agent项目或者你发现自己写的Agent逻辑完全堆在提示词里、改一改就崩那这篇内容应该能给你一些直接能落地的参考。1. 为什么必须把“技能层”单独拆出来很多人刚接触Agent开发时会有一个错觉模型已经足够聪明了只要把工具文档丢给它它自然就会用。这个想法在Demo阶段确实成立但一旦进入真实业务你会发现提示词越长模型越容易“选择性失明”——工具一多它要么反复调用同一个低效工具要么干脆漏掉关键步骤。把技能从提示词中抽离出来单独成层是我认为解决这个问题的第一前提。1.1 大模型能力不等于Agent能力我见过太多团队把“模型很强”直接等同于“Agent很强”。实际上模型只是Agent大脑里的一个推理组件它需要一套外部结构来承载任务拆解、状态管理、工具选择、结果校验这些事。技能的独立性越强Agent的推理负担就越小。举一个生活化的类比你雇了一位顶级厨师他不会自带锅碗瓢盆和食材清单但他知道中餐里“爆炒”需要猛火快翻、“炖汤”需要文火慢煮——这些就是技能。你作为后厨管理者要做的是把每道工序的操作规程、用料标准、出锅判定写成规范卡片厨师照着执行并凭专业判断微调。Agent里的技能层就是这套规范卡片。如果所有规范全糊成一团塞进提示词就好比把整本菜谱一次性摊在厨师面前他当然也能做但效率、稳定性、可维护性都不行。你要的不是一个“什么都会但每次发挥不稳定”的Agent而是一个“能力边界清晰、行为模式稳定”的Agent。1.2 提示词模板与技能封装的本质区别有人会觉得我把一段结构化提示词写成函数再调用不就是技能吗差的还很远。真正意义上的技能封装至少要同时满足三个条件可被独立描述技能有名称、有用途说明、有适用场景和禁用场景模型可以在运行时做“要不要用这个技能”的判断可被稳定调用技能的输入输出有明确的协议约束Agent调用技能时传参有格式、返回值有结构代码层和模型层解码的是同一套语言可被单独评测技能本身好不好用可以脱离整个Agent单独打分而不是每次都要端到端跑完整个任务才能发现问题。满足这三条技能才具备“资产”属性——可以被复用、沉淀、迭代。不满足的话它只是提示词的又一次搬运。以我自己的经验早期项目里我把“搜索资料”和“网页内容抽取”拆成两个独立技能描述也写得很细但Agent经常在搜索结果还没返回时就并发调用了网页抽取导致抽到一堆空页面。后来我给“搜索资料”的返回结果里加了content_available字段并明确在技能描述里标注“只有该字段为true时才可以调用网页抽取”问题才彻底消失。这个例子说明技能之间的依赖关系、前置条件必须写进协议里而不是指望模型“自己领会”。2. 技能系统的基本组成从命名到返回值的四件套一套成熟的技能封装核心由四部分构成技能名称、技能描述、输入参数约束、返回值结构。听起来很简单但每一环都有大量细节踩过的坑不少。2.1 技能名称一个“会说话”的标识符技能名称看似不起眼实际上直接影响模型的调用命中率。我见过有人用tool_search_weather这种驼峰命名也有人直接用search-weather更常见的是transform_data这种毫无语义感的名字。模型在推理时是靠语义匹配来决定调用哪个技能的名字越贴近人类自然表达命中率越高。我的建议是名称为“动词加名词”的英文短横线风格例如search_web_pages、extract_article_content、calculate_invoice_amount。动词决定了动作类型名词决定了操作对象模型很容易在推理时把任务描述“帮我算一下这张发票的金额”映射到calculate_invoice_amount上。同时技能名尽量不要带版本号、下标或缩写。曾经我把同类技能按处理逻辑拆成parse_html_v1和parse_html_v2结果模型经常调用v1版本因为描述里v1的写法更详细。版本信息应该放到技能元数据里由调度层统一管理而不是体现在命名上。2.2 技能描述决定模型能否在正确时刻做出判断技能描述是整套封装里唯一完全面向模型自然语言理解的部分它的质量直接决定了Agent的选择正确率。我在实践中总结出一套高转化率的描述模板大致包含四层信息技能定位这个技能做什么用一两句话说清楚动词开头避免抽象名词堆砌适用场景什么类型的任务适合调用它尽量举例说明让模型能对齐自己手头的子任务禁用场景什么时候绝对不要用这个技能这条很多人忽略但它对防止模型胡调用至关重要使用前提调用这个技能前需要满足什么前置条件比如“只有完成登录后才可以调用”“数据量超过100条时优先使用批量接口”。举一个具体案例。我给“发送邮件”这个技能写描述时最初版本只有一句“发送一封邮件参数包括收件人、主题、正文”。结果模型经常在未获得收件人确认时就发送甚至在对话刚开场用户还没说出需求时就主动调用。后来我改成发送邮件给指定收件人。 适用场景用户明确表达需要发邮件并提供收件地址或联系人姓名时。 禁用场景用户只是提及“邮件”但未明确指示发送时不要调用收件人信息缺失时不要调用。 使用前提发送前必须向用户二次确认收件人、主题、正文摘要得到肯定答复后才可以执行。同样的底层函数改动描述后误调用率大概下降了60%。模型的判断力很强但你需要给它足够清晰的判断依据。2.3 输入参数为模型提供“填表式”的引导参数设计要遵循一个原则越结构化越好越少依赖模型的自由发挥越好。能枚举的用枚举能设默认值的给默认值能自动推导的不要留给模型。我们做过的一个人力资源Agent里需要让模型生成员工转正评估报告草稿。最初参数里只有employee_name一个字符串字段模型每次都要自己去对话上下文里找员工姓名经常找错。后来我把参数拆成employee_id、employee_name、department、onboard_date并为employee_id提供了一套模糊匹配规则模型只需从上下文里提取姓名系统自动反查ID准确率显著提升。参数类型方面我强烈推荐偏好的顺序是枚举类型 布尔类型 数字类型 字符串类型。字符串对模型而言自由度太高容易生成格式不规范的输入。比如日期参数如果允许模型自己填它可能给你2024/1/5、2024年1月5日、2024-01-05各来一遍。正确的做法是要求模型只传date_range这种枚举值实际具体日期由代码层解析上下文后补齐。2.4 返回值除了数据本身还要带上状态和提示信息返回值结构是技能封装里最容易被低估的部分。很多人直接返回原始接口的JSON字段又多又乱模型拿到后反而不知所措。我给返回值设计了三段式结构status执行状态标记至少包含success、failed、partial三种data真正的业务数据只保留对下一步决策有用的核心字段多余字段宁可截断message面向模型的可读摘要用一两句话总结“发生了什么、下一步该做什么”。比如一个“查询库存”的技能原始接口返回了SKU、条码、仓库编码、最近入库时间、供应商编号等二十多个字段模型根本无从下手。封装后返回变成了status: success data: sku: A12345 available_stock: 32 reserved_stock: 5 message: 商品A12345当前可用库存32件另有5件被预占当前满足下单需求。模型要做决策时看一眼message基本就够用了不需要再费力解析一堆原始字段。这也是为什么我会说技能层的本质是“帮模型减负”而非“给模型加负担”。3. 技能生命周期管理命名、版本、去重与退役技能从来不是写完就一劳永逸的。随着业务演进技能会新增、调整、废弃如果缺少一套管理机制技能库很快就会腐化成一锅粥。这一节讲我在这方面的实操经验。3.1 技能去重同一个意图只保留一个“最优解”技能多了之后最常出现的问题就是功能重叠。比如你可能同时有search_web和search_newsAgent经常随机挑一个用或者两个都用结果返回内容高度重复还消耗了大量上下文窗口。我建议每新增一个技能前先对着已有技能清单过一遍“三个问题”这个技能要解决的场景是否已经被现有技能覆盖如果覆盖了一部分差异点足以支撑独立的技能身份吗两个技能合并为一个并在内部做参数路由会不会更合适实践中我的结论是超过70%的“新技能需求”最后都该归并到已有技能里通过增加分支参数解决而不是新开技能。技能数量越少模型的选择负担越小整体表现就越稳定。当然去重不是简单的删除。如果确实要合并需要跑一遍历史日志确认哪些场景在调用旧技能再平滑迁移到新技能并保留一段时间的兼容重定向。3.2 版本迭代与灰度策略技能升级最容易翻车的场景是新版本在单测里完美运行一上生产就出问题于是紧急回滚但Agent已经在新旧版本间反复横跳了。解决方案是给每个技能加版本号并在调度入口做灰度控制。我习惯的做法是所有技能在定义时都带有version字段Agent实际调用的是default_version所指向的版本。升级时先在测试集上对比新旧版本的完成率和错误率达到阈值后再将一部分流量切到新版本。具体切流量不需要很复杂的平台用配置中心的开关就能实现——把default_version指向旧版把candidate_version指向新版用请求ID哈希决定走哪个版本。这个灰度方案我用了很久很稳定唯一的代价是技能注册表里会暂时存在两份配置需要在灰度结束后清理。3.3 权限隔离与沙箱执行技能一旦涉及操作类动作——发消息、下单、改数据——就必须有权限控制。我见过不少项目把所有技能一视同仁地开放给Agent结果Agent在错误的场景里执行了高权限操作酿成事故。我的经验是按风险等级将技能分成三类风险等级典型技能处理方式低风险查询、检索、计算直接放行仅记录日志中风险写入草稿、生成文件、配置模板需要用户显式确认后才可执行高风险发送消息、支付、订单变更必须二次验证身份且操作前展示完整决策链这个分类不是一成不变的。同一个技能在不同上下文里风险等级也可能不同比如“发送邮件”给内部同事算中风险给外部客户发合同附件就算高风险。更稳妥的做法是权限判断放在技能调用链的入口处由规则引擎动态读取上下文信息再做裁决而不是写死在技能定义里。沙箱方面凡是能通过子进程或容器执行的技能我都建议默认跑在受限环境里文件系统只读、网络仅按白名单放行、内存设额度。即使某个技能只是“转换文件格式”也不要让它直接跑在宿主机上——技能代码的更新频率远高于核心服务是供应链攻击最容易打进来的口子。4. 让Agent正确编排技能上下文预算与冲突处理技能单个的质量再高如果编排层不会用一切白搭。这一节聊我在编排上碰到的两个老大难问题上下文的预算分配以及多技能并行调用时的冲突处理。4.1 上下文窗口的“预算管理”每个模型都有上下文长度上限而技能描述、参数结构、返回结果都在消耗这个预算。技能库大了以后不可能把所有技能的完整描述一次性塞进system prompt否则光描述就能占掉上万token留给推理的预算少得可怜。目前主流的解法是“动态技能检索”不把所有技能塞进去而是根据当前用户的输入先做一次相关性召回挑出可能用到的Top N个技能把它们的描述注入本次会话的上下文。这个过程类似搜索系统的召回加精排只是排序信号变成了“当前对话意图与技能描述之间的语义相似度”。我项目里的实现不复杂把所有技能定义存到一个向量库里用户每次发起新任务时把任务描述向量化检索出相似度最高的5到10个技能再将它们的完整描述组装进system prompt。实测效果远好于一次性全注入尤其在技能总数超过30个以后上下文预算的压力会体现得特别明显。同时要注意不同技能描述的长度差异很大有的技能描述写了上千字有的只有两行。检索注入时我给描述设置了预算上限比如每个技能的描述截断到400字符保证单次最多注满3000字符的描述预算剩下的空间留给推理链条和返回结果。4.2 技能并行调用的依赖关系与冲突处理Agent在拆解复杂任务时经常会同时想到多个技能。比如“把这份合同里的金额提取出来加总后存到表格里”Agent可能会同时想调用extract_numbers、sum_numbers、write_spreadsheet三个技能。这里存在两类问题一类是技能之间存在严格的先后依赖必须先提取才能加总另一类是技能之间的资源冲突同时写同一个文件。我的做法是在技能定义里显式声明依赖关系而不是让模型猜。具体来说我给每个技能增加一个requires字段它是一个前置技能列表。Agent的调度层在发起并行调用之前会先检查依赖图只把没有依赖关系或依赖已完成的技能放入并发池其余技能按拓扑顺序排队执行。这套机制让我彻底摆脱了“模型偶尔能把顺序排对、偶尔不能”的不确定性。资源冲突则更隐蔽。两个技能可能在逻辑上毫无关系但都会写同一个临时目录。解决思路是给技能声明资源锁比如write_spreadsheet申请独占写锁read_spreadsheet申请共享读锁。调度层根据锁的类型决定并发还是串行。这些细节看起来重但其实实现起来只是给技能元数据加两个字段收益却极其直观。4.3 失败重试与结果校验技能再稳也要有兜底技能封装得再好也会有失败的时候。超时、接口限流、参数格式被模型生成错了……这些都不是“模型聪明一点”就能解决的必须有明确的失败处理策略。我常用的兜底有三层参数自检层代码层对模型传入的参数做校验不符合约束的直接拒绝并生成一条“参数异常说明”返回给模型模型往往会自己修正后重新调用重试层针对网络类错误和限流使用带指数退避的重试策略最多重试两次避免无限重试把问题放大降级层当技能彻底失败时返回一个人工兜底指令比如“调用失败建议引导用户联系人工客服”而不是让模型在没有结果的情况下硬编一个答案。这些年我观察到一个规律Agent的稳定性提升更多来自“失败时能不能优雅收场”而非“顺利时跑得多顺畅”。技能层必须把失败当作一等公民来设计重试策略、降级文案、错误码体系缺一不可。5. 量化评估怎么判断一套技能到底“好不好用”技能建了、Agent也能跑起来但你怎么知道这套技能是真的好还是只是偶尔运气好这是我见过最容易被忽视的环节。没有量化评估技能优化就成了拍脑袋。我在这块的做法是三层评测。5.1 第一层单技能准确率剔除模型干扰直接测技能自身做法很简单绕过Agent决策过程直接向技能发起一批标准测试用例检查返回结果的正确性。比如测试“查询天气”技能就准备50个城市名、日期、语言偏好组合断言返回的天气数据和天气API的原始数据一致。这层评测的目的是确保技能本身没有“内在缺陷”。如果单技能准确率不达标后面一切白测。它测的是枪准不准而不是射手会不会开枪。5.2 第二层技能选择准确率检验模型能否在正确时机调用正确技能这一层专门测Agent的决策能力。构建一批“任务上下文”每个上下文里都包含明确的技能调用预期然后跑Agent看它最终调用了哪些技能。我常用的评估指标有两个选择准确率正确调用的技能数占应调用技能数的比例主要衡量“有没有漏调用”误调用率错误调用的技能数占实际调用技能数的比例主要衡量“有没有多调用、错调用”。举一个典型的失败案例任务是“帮我把昨天销售额超过5000元的订单导出成Excel”。Agent正确调用了query_orders但在没有做聚合计算的情况下就直接调用了export_excel导致导出的Excel里全是原始订单行而非“销售超过5000元的订单汇总”。这就是技能选择正确、但调用时机不对的典型。这一类问题靠单技能评测根本发现不了必须靠端到端的任务级评测才能暴露。5.3 第三层任务完整度评分把技能调用串成完整链路打分单技能和选择决策都测完了最后还要看整个任务的完成质量。我参考任务型对话领域里常用的完成度评分做了一套简化版评分项权重说明目标满足度40%最终产出是否真正满足用户的原始需求过程合规度30%技能调用顺序、前置条件是否合规是否存在越权/误操作资源消耗度15%完成同样任务花费的token数、技能调用次数是否合理异常处理度15%任务中遇到异常时是否走上了合理的降级或重试路径每项按0到100打分加权求总分。这套框架跑下来的数据可以作为技能迭代的北极星指标如果总分下降排查各分项找出原因如果某个技能版本升级后总分提升再考虑推向全量。我建议至少积累两百条以上带有标注的任务样本再开始做第三层评测。样本太少时分数波动极大容易被单条异常样本带偏。样本来源可以从真实生产日志里抽也可以人为构造典型场景总之要覆盖正常路径、边界路径和异常路径三类。6. 实战踩坑记录几个让我印象深刻的教训文章最后分享几个我在构建技能层过程中亲身踩过的坑。这些都属于“当时觉得合理后来才发现问题”的典型列出来供你参考。6.1 技能描述里的“废话”比“缺失”更可怕一开始我写技能描述总想写全背景、原理、注意事项、历史原因恨不得写八百字。结果是模型拿到长篇描述后反而抓不住重点经常忽略最关键的操作约束。后来我强制自己遵循“两句话原则”第一句话讲技能是做什么的第二句话讲调用它的前置条件或禁忌。如果还有必要补充用条目列在最下方。实测下来模型在长描述里的关键信息召回率远低于短描述。描述不是论文是给模型的“产品说明书”越简短越有效。6.2 返回值字段命名不统一模型自己都搞混了早期技能返回值的字段名没有统一规范有的接口用created_at有的用createTime有的用c_time。模型在多个技能间切换时会经常把字段名张冠李戴产生极其隐蔽的错误。后来我定了一条规矩所有技能返回值的字段名统一走一套命名规范——全小写下划线式snake_case、时间字段统一叫created_at、状态字段统一叫status、业务主体统一叫data。这套规范看起来很死板但它大幅降低了模型在多技能间进行信息搬移时的错误率。6.3 中文语义场景下技能描述用英文还是中文这是个很多中文团队都会遇到的问题。模型底层训练语料以英文居多但业务场景是中文描述到底该用哪种语言我的实测结论是技能名称用英文技能描述用中文。名称的作用是让模型在推理时快速定位英文短名词在这个环节有优势描述则要承载大量业务约束中文的表达精度更高尤其对“禁用场景”“使用前提”这类约束语义中文的歧义远小于英文。这个方案在我们多个项目里都表现稳定你可以直接抄作业。6.4 别高估Agent的记忆力把状态显式传给技能Agent在长期对话里容易丢失早期信息比如用户十分钟前提过的日期范围到后面Agent执行查询时可能已经忘记。别指望模型“记得”设计技能时尽量设计成无状态调用技能所需的全部上下文由调度层从会话历史里抽取并作为参数显式传入。我把这称为“技能的无状态原则”。它虽然让调度层的代码更复杂但换来的是技能的可测试性和可复用性的大幅提升。一个不依赖隐式状态的技能既方便单测也方便在多个Agent间共享。从整体来看构建一个高质量技能层真正困难的地方从来不在写代码而在于你能否把“模型怎么做决策”这件事想清楚。技能描述写得好不好、参数设计得巧不巧、依赖关系理得顺不顺每一项都比单纯的模型选型更影响最终效果。希望这篇内容能帮你在Agent技能设计这条路上少走几段弯路。