作为一个长期泡在AI Agent项目里的人我越来越意识到一个问题大家讨论Agent的时候注意力几乎全放在大模型选哪个Prompt怎么写上却很少有人认真对待agent-skills这个东西。实际上Agent能不能真正落地干活往往不取决于模型多聪明而是取决于你给它装配了多少靠谱的技能。我最近把一个内部项目彻底重构了一遍核心改动就是把原来散落在各个业务逻辑里的能力抽离成独立的skills模块跑通了之后效果提升非常明显。这篇东西我就把这个过程和思路完整拆开讲讲包括什么是Agent技能、怎么设计、怎么实现、怎么评估以及我踩过的几个典型坑。1. 先弄清楚Agent的技能到底指什么在动手之前我建议大家把技能和另外几个容易混淆的概念先掰扯清楚不然后面做出来的东西大概率是个四不像。1.1 技能不等于工具也不等于Prompt很多人觉得给Agent配几个工具函数tool再写个系统提示词就叫有技能了。这个理解不算全错但很粗。我的定义是工具Tool是Agent可以调用的原子能力比如搜索网页读取文件调用某个API。它本身不含决策逻辑。技能Skill是工具、Prompt模板、执行流程、校验规则和错误处理的一套组合。它表示Agent知道在什么场景下按什么步骤调用什么工具把一类任务做完。举个例子。单纯给Agent一个get_weather(city)接口这是工具。但如果你给它配了用户提到天气 → 解析城市 → 调接口 → 判断温度数值是否异常 → 生成穿衣建议这一整套流程这才叫技能。1.2 为什么技能层是Agent架构里最值得投入的一层我重构之后最大的感受是**模型是大脑技能是肌肉记忆。**大脑负责理解意图和做模糊决策但如果每一步具体操作都要靠大脑现想那Agent的反应又慢又不可控。把常见操作固化成技能之后有几个直接的好处稳定同样的输入技能执行路径基本一致不容易出现随机发挥。可测技能是独立的可以单独写测试用例不用每次都在完整对话里验证。可复用一个技能可以服务多个场景。比如信息提取技能既能用在客服工单上也能用在数据分析任务里。可优化某个环节出错直接改那个技能就行不用动整个Agent。我见过很多团队花大力气调Prompt结果效果时好时坏本质就是没有把该固化的能力固化下来。1.3 技能的分类方式在做架构设计的时候我习惯把技能分成三类方便后续管理和规划分类说明示例感知型技能负责获取和理解信息网页抓取、文档解析、数据库查询、日志检索操作型技能负责执行具体动作发送邮件、创建工单、修改配置、执行脚本决策型技能负责分析、判断和生成方案代码审查、SQL生成、风险评分、方案对比这个分类不是绝对的但有个好处当你发现Agent在某个环节卡住时可以快速定位是信息不够还是做不了还是判断不了。2. 一个Agent技能从0到1的实现路径下面我以实际的agent-skills项目重构为例讲一下我怎么设计一个技能的完整生命周期。这里用代码审查技能做例子因为它是我们团队用得最多的一个技能逻辑上也比较有代表性。2.1 第一步定义技能的输入输出契约技能跟函数一样先定义接口再谈实现。我的做法是给每个技能写一个独立的描述文件包含name技能名称比如code_reviewdescription一句话说清楚这个技能解决什么问题、在什么条件下触发input_schema结构化输入明确字段类型和必填项output_schema结构化输出方便上层解析和渲染这里最关键的是description。因为在大模型驱动的Agent里模型是通过描述来决定要不要调用这个技能的。描述写得含糊模型要么不敢用要么乱用。我自己常用的描述模板是当用户请求对代码变更进行评估、检查缺陷、提出改进建议时使用此技能。 输入为代码片段或PRPull Request的变更列表输出包含问题列表、严重程度、修改建议。要比用于代码审查这种描述好得多因为前者明确了触发条件和返回值形态。2.2 第二步把执行流程拆成可编程的步骤技能不是一个单一的模型调用它是一串流程。我会把流程画成步骤列表每个步骤要么是工具调用要么是模型推理要么是规则判断。代码审查技能的流程我拆成了四步提取变更内容从PR对象或代码片段中提取diff信息。静态规则扫描用正则和内置规则库扫描明显的低级问题比如硬编码密钥、空指针风险、明显的不安全函数。模型深度分析把diff和扫描结果一起交给大模型让它关注逻辑缺陷、边界条件、并发安全等静态工具不容易发现的问题。结果聚合与格式化把规则扫描和模型分析结果合并按文件、行号、严重级别输出。为什么要做这种规则模型的混合设计原因很现实纯靠模型做代码审查又慢又贵而且模型对小问题的召回率不稳定纯靠规则则只能抓到模式匹配的问题根本谈不上智能。把两者组合起来既控成本又提覆盖。2.3 第三步实现技能执行器流程定了接下来就是代码实现。我这里用Python写了一个简单的技能执行器骨架核心逻辑是注册表 执行器 上下文传递class SkillExecutor: def __init__(self): self.registry {} self.context {} def register(self, skill): self.registry[skill.name] skill return self def run(self, skill_name, **kwargs): skill self.registry.get(skill_name) if not skill: raise SkillNotFoundError(funknown skill: {skill_name}) # 每个技能执行前把当前上下文传入 skill.set_context(self.context) result skill.execute(**kwargs) # 执行后回写上下文供后续技能使用 self.context.update(skill.get_outputs()) return result每个技能都是一个类需要实现execute方法。这里我把上下文单独管理是为了让多个技能可以链式调用。比如提取工单信息技能执行完会把customer_id写进上下文下一个查询历史订单技能直接就能读到。这个设计思路可以帮你保证技能之间低耦合不会出现一个技能直接改另一个技能内部状态的情况。2.4 第四步用编排层把技能串联起来单个技能能做的事情终究有限Agent真正厉害的是技能的组合。我在项目里定义了一个编排层它的职责是接收用户请求 → 理解意图 → 决定调用哪个技能、按什么顺序调用、参数怎么传递。一个最简单但实用的编排策略是Plan-Execute-Reflect三步循环Plan让模型根据用户请求生成一个技能调用计划。Execute按计划依次执行技能。Reflect把执行结果反馈给模型让它判断任务是否完成或者是否需要调整计划再执行一轮。我在实现的时候发现这个循环里最需要控制的是轮数上限。模型有时候会陷入执行→发现不完美→再执行的死循环不仅烧钱还拖时间。我直接设了最多3轮超出就返回当前最优结果让用户决定下一步。3. 技能调优与效果评估别只盯着准确率技能写出来不难难的是让它稳定好用。我在这部分花的时间最多跟大家分享一下我的评估思路和调优方法。3.1 建立技能专属测试集我维护了一个测试用例库每个技能至少配20条用例覆盖正常输入、边界输入、异常输入、误导性输入四类。以代码审查技能为例正常输入一段有明确逻辑缺陷的Python代码边界输入空文件、只有注释的文件、超大文件异常输入不是代码的文本、二进制内容误导性输入看起来像代码但其实是日志输出这里我的一个经验是误导性输入的用例必须要有。因为Agent在真实场景里接到的输入五花八门如果技能没有防御能力很容易把垃圾数据当正经输入处理然后输出一堆没意义的结果。3.2 分层评估指标对技能效果我不用单一指标而是按召回质量、执行稳定性、资源消耗三个维度打分维度指标我关注的原因召回质量问题检出率、误报率这个技能值不值得用就看这俩执行稳定性成功率、超时率、异常率线上频繁挂掉的技能等于没有资源消耗单次调用的token数、耗时、成本决定这个技能能不能规模化比如代码审查技能我要求严重级别问题检出率不低于90%误报率不高于15%。如果误报太高用户就会失去信任宁可不用这个技能。3.3 迭代优化的常用手段评估完发现短板之后我的优化手段按优先级排列补规则如果是规则扫描环节漏掉的问题直接往规则库里加规则。这个手段成本最低。调Prompt模板如果是模型分析环节的理解偏差就调整技能内部使用的Prompt把重点问题和约束写清楚。改流程如果是步骤顺序不合理比如先扫描后分析导致信息传递遗漏就调整流程。换模型如果技能的核心判断任务超过当前模型的能力上限就考虑给技能单独配一个更强的模型。这里我把模型的选用也做成可配置的。提示给技能单独配模型是个很实用的设计。不是所有技能都需要旗舰级模型也不是一个模型就能干所有活。按技能的实际需求来配能在效果和成本之间找到平衡点。3.4 灰度上线与回归技能改完不能直接全量上。我一般分三步走第一阶段在测试集上跑全部用例确认通过率不低于之前的版本。 第二阶段在真实流量的10%上灰度跑48小时对比新旧版本的指标。 第三阶段全量切换同时保留旧版本的日志方便出问题时快速回滚。这套流程看起来繁琐但真的能避免很多线上事故。我之前有一次改完技能直接全量上线结果有一个正则写错了把所有包含时间戳的文本都当成敏感信息提取了导致下游任务大面积报错。从那以后我再也不敢跳过灰度。4. 技能编排实战把模型调用的成本降下来很多入门者做Agent习惯性把所有逻辑都丢给大模型认为模型能力够了就行。但到了真实业务场景你会发现这条路既贵又慢。技能化的核心价值之一就是把能用确定性逻辑解决的问题从模型调用里剥离出来。4.1 不需要模型的步骤就别用模型我举一个真实的优化案例。我们的客服Agent接了一个查询订单物流的技能。最初的实现是用户提问 → 大模型调用查单工具 → 工具返回物流轨迹 → 大模型再生成一段回复文本。这里第二次大模型调用其实是不必要的。快递轨迹本身就是结构化数据直接套一个模板拼装成您的包裹已从XX发出预计X号送达就行。去掉这次模型调用之后平均响应时间从3秒降到了0.8秒单次成本下降了大概六成。我建议大家在写技能时每次都问自己一句这一步真的需要模型来做吗读取字段、格式转换、字段映射、简单判断这些都用不上模型。模型只应该用在模糊语义理解和复杂推理上。4.2 技能链的上下文传递设计多个技能串联的时候上下文传递是很容易出bug的地方。我要求所有技能的输入输出都是JSON可序列化的且不允许在技能之间传递Python对象引用。这样做的原因有两个一是方便日志记录和问题回溯。每个技能执行完我把输入输出快照存一份线上出问题可以直接查链路。二是方便做缓存。如果技能B的输入依赖技能A的输出而A的输出是确定的那A的结果就可以缓存不必每次重新执行。我目前实现的缓存策略很简单在SkillExecutor.run()里把技能的输入参数做一个哈希命中缓存就直接返回上次结果并打上from_cache标记。代码审查这种耗时操作缓存命中率能达到三成以上因为很多变更请求是重复的。4.3 故障转移与降级策略技能也会挂尤其是那些依赖外部API的技能。我从实际教训里总结了三条策略超时必设每个外部调用都要配超时时间我一般设5秒。宁可返回超时错误也不能让整个Agent卡住。降级链路比如网页抓取技能挂了可以降级到搜索引擎摘要先保证用户拿到部分信息而不是彻底失败。人工兜底对于高价值任务技能连续失败两次后直接把任务标记为需要人工处理不再重试。注意重试不是越多越好。我之前设过3次重试结果外部服务已经大面积故障3次重试把本地线程池全部占满其他技能也一起饿死了。现在所有重试都加了指数退避和最大并发限制。5. 技能治理让Agent技能库保持干净可控技能会越攒越多如果一开始没有治理意识半年之后就是一座屎山。我分享一下我的管理方案。5.1 命名与文档规范每个技能必须有四个东西命名、描述、负责人、依赖清单。命名用下划线分隔的动词加名词比如parse_invoice、send_alert不用拼音纯英文也不用大小写混合。描述必须写清楚什么时候该用什么时候不该用这直接决定模型调用技能的正确率。负责人很重要。技能是有生命的业务一变化它就可能失效。没有负责人出了问题连找谁问都不知道。5.2 版本管理与废弃机制技能的Prompt和逻辑也要做版本管理。我目前的做法是每次修改技能都在注册表里生成一个新版本号但保留旧版本可以回退。当某个技能连续30天没有被任何Agent调用我会标记为deprecated再等30天如果还是没有调用直接下线。这个机制帮我清理掉了不少历史遗留技能。曾经有个汇率换算技能在业务调整之后早就没用了但一直躺在注册表里模型有时候还会误调用它输出过时的汇率造成过几次用户投诉。5.3 技能的可观测性最后一项是日志和监控。我在技能执行器里埋了三个关键点技能耗时分布技能错误率技能被触发的频率和上下文有了这些数据你就能回答几个关键问题哪个技能最常用哪个技能经常失败哪个技能一调用成本就飙高这些都是后续优化方向的来源。在SkillExecutor.run()里执行前后打点特别简单start time.time() try: result skill.execute(**kwargs) metrics.record(skill.name, latencytime.time() - start, statussuccess) except Exception as e: metrics.record(skill.name, latencytime.time() - start, statuserror) raise这些指标汇总到日志平台之后我每周扫一眼基本就能知道整个Agent体系的健康状况。6. 我踩过的几个坑以及现在的应对方式最后分享几个真实踩过的坑每个都是拿线上事故换来的经验。6.1 技能描述写得太泛模型乱调用最早我把code_review技能描述写成审查代码质量。结果有用户问这段代码的风格符合规范吗模型也调用了这个技能而技能内部根本没做风格检查输出了一堆无关的缺陷用户体验很差。现在我的描述里都明确写了本技能只关注逻辑缺陷、安全风险和性能问题不评估代码风格相当于主动给模型划了边界。6.2 技能内嵌Prompt与主Prompt冲突我之前在技能内部写了一套系统Prompt又在Agent主Prompt里写了一套行为规则。两套规则对同一个行为的约束不一致模型的输出就一会儿按这个来一会儿按那个来非常不稳定。现在的约束是**技能的Prompt只和如何执行这个任务有关不涉及Agent应该是什么角色。**角色的定义只放在主Prompt里避免职责交叉。6.3 技能执行顺序固定导致场景扩展性差最初我在编排层写死了先查信息→再分析→最后执行的顺序结果新接了一个投诉处理场景发现它需要先分析严重性→再查信息→再执行只能硬写分支逻辑。后来我改用用户意图到技能序列的映射表来做编排新场景只需要往映射表加一条记录不用改代码。这个改动很小但对扩展性的提升非常大。6.4 只测Happy Path没测异常路径这是最典型的坑。我最早给技能写测试全写的正常输入上线之后遇到空值输入直接崩溃。现在我把异常输入测试用例当成和正常用例同等重要每个技能的测试集里异常和边界用例占比不低于四成。最后说点实在的对整个agent-skills这套体系折腾了大半年我最深的体会是Agent开发的瓶颈从来不在模型能力不够而在于我们有没有把确定性的事情固化好把不确定性的事情用最小的成本交给模型。技能层就是做这件事的。如果你的项目也遇到Agent表现不稳定、调用成本下不来、新场景接入麻烦这些问题我建议别急着换模型、别反复调Prompt先花点时间把技能层梳理清楚。从最简单的一两个技能开始做跑通了再逐步扩充。每个技能都做到契约清晰、流程明确、可测试、可观测整个Agent系统会扎实很多。以后每次给Agent加新能力我都会先问自己一个问题这个是该做成技能还是该让模型自由发挥绝大部分情况答案都是前者。