这两年做智能体项目踩过最大的坑不是模型能力不够而是把 Agent 当成一个能聊天的黑盒来用。agent-skills这个词我是在一次内部技术复盘时认真想明白的——真正让智能体从演示级走向可用级的是它到底掌握了一套什么样的技能体系以及这套体系是怎么被设计、注册、调用和评估的。这篇文章我想把这些经验完整地梳理一遍。如果你正在做 AI Agent 相关的项目或者准备把大模型接入到实际业务里这篇内容会给你一套可以直接参考的技能设计框架包括分层思路、接口规范、评估闭环以及我在多个项目里反复踩过又填平的坑。不聊虚的理论全是能落地的实操记录。1. 项目概述agent-skills 到底在解决什么问题1.1 从一个尴尬的调试现场说起先讲一个我经历过的真实场景。某次和一个团队联调一个文档处理智能体需求很简单用户上传一份合同Agent 帮忙提取关键条款、生成摘要、并按照指定模板输出。Demo 阶段一切正常演示的时候模型也确实能答上来。但一进入真实数据测试就全乱了有的合同是扫描件有的表格嵌套了三层有的条款写了详见附件三但附件根本没上传。Agent 要么答非所问要么直接编造条款内容更麻烦的是它分不清提取信息和判断合同风险这两个动作经常做着做着就跑到另一个任务上去了。调试了三天问题根源慢慢浮出水面我们根本没有给这个 Agent 定义清晰的技能边界。它就像一个什么都会一点但什么都不精的实习生你给它一个模糊指令它就靠临场发挥来凑答案。这个项目之后我彻底意识到Agent 的能力天花板不取决于模型本身有多强而取决于你给它配备了哪些技能以及这些技能被定义得有多清楚。这就是agent-skills这个标题背后真正的价值所在。1.2 agent-skills 的核心定位agent-skills不是一个具体的开源库也不是某个平台的专有名词它代表的是一套面向智能体任务执行的能力封装与组织方式。它的核心思想是把 Agent 需要完成的各类操作拆解成一个个可注册、可调用、可评估的原子技能单元再通过编排层将它们组合成完整的工作流。我习惯把它理解为给 Agent 编写岗位说明书。一份好的岗位说明书会写清楚这个岗位负责什么、不负责什么、遇到什么情况该做什么判断、产出标准是什么。agent-skills要做的正是这件事——把模糊的智能转化为明确的能力清单。这套思路之所以越来越重要是因为现在的 Agent 应用已经从单轮问答进化到了多步骤任务执行。用户不再满足于让模型说一段话而是希望它做成一件事。做成一件事就需要工具调用、需要状态管理、需要异常处理、需要结果校验这些都不是靠提示词堆砌能解决的必须有结构化的技能体系来支撑。1.3 这套技能体系适合谁结合我接触过的项目来看以下几类人会从agent-skills的思维方式里获益最多第一类是做智能体应用开发的工程师。无论你用哪种框架市面上主流的 agent 框架都支持 skill 注册机制掌握技能拆解与设计的底层逻辑能让你的代码结构更清晰、调试成本更低。第二类是业务方或产品经理。理解技能体系的边界和限制能帮助你更准确地定义需求——不是笼统地说做个智能助手而是说清楚这个助手需要具备哪几项可验收的能力。第三类是对 Agent 技术感兴趣的爱好者。即使不写代码了解技能体系的组织逻辑也能帮助你在使用各种 Agent 产品时更清楚地判断它擅长什么、不擅长什么避免产生不切实际的预期。这里有一个我反复强调的观点agent-skills不是某个具体工具的说明书而是一种思考 Agent 的方式。掌握了这种思考方式无论底层模型怎么换、框架怎么变你都能快速搭建出可靠的应用。2. 技能体系设计核心能力拆解与选型逻辑2.1 为什么技能要分层而不是堆功能很多人设计 Agent 技能时容易犯一个错误恨不得把所有功能塞进一个技能里。比如做一个全能办公助手就把文档读取、表格处理、邮件发送、日历管理全部写在一个技能描述里结果模型根本不知道该在什么时候调用哪个功能。我在实践中确定的思路是技能必须分层而且每一层只解决一类问题。我通常把技能体系分为三层。感知层负责获取和解析信息是整个技能体系的地基。举个例子一个文档处理 Agent 的感知层技能包括文本提取、图片 OCR、表格结构识别。如果感知层做不好后面的所有分析和生成都是空中楼阁。认知层负责理解和推理是 Agent 的大脑。它包含信息抽取、意图判断、风险识别、方案生成等技能。认知层通常需要调用大模型的能力但要注意的是不是所有任务都需要最强模型有些结构化抽取任务用轻量模型反而更快更省。行动层负责执行和输出是 Agent 的手。它包含格式化输出、接口调用、文件写入、消息通知等技能。行动层的设计要尽量标准化让执行结果可以被上一层校验和反馈。这三层之间的关系是单向依赖的感知层为认知层提供输入认知层为行动层提供决策。这个单向依赖非常重要它避免了技能之间的循环混乱让问题定位变得容易。我见过太多失败的 agent 项目本质问题就是技能层级混乱感知和认知互相穿插出了问题都不知道该查哪一层。2.2 技能粒度越细越好还是越粗越好技能粒度是我在多个项目中反复调整过的一个参数。粒度太大技能变成一个又笨又重的工具灵活性差、复用率低粒度太小Agent 要在一堆细碎技能之间频繁切换不仅浪费 token还容易让模型决策混乱。分享一下我现在采用的划分标准一个技能职责单一且产出可评估就是合适的粒度。比如提取合同编号是一个技能判断合同风险等级是另一个技能这两个不会混淆。但如果把处理合同整体作为一个技能里面包含了提取、判断、摘要、归档一堆动作这个技能就不合格。实操中的一个判断技巧是如果某个技能的描述需要超过 100 个字才能说明白那它大概率要被拆分成多个子技能。技能描述应当像 API 文档一样精确输入是什么、输出是什么、什么情况下不该调用它。另外我建议每个技能都要声明明确的适用范围。一个技能只对PDF 格式的采购合同有效那么当输入是一张图片时Agent 就应该走其他技能而不是硬着头皮处理这样可以显著减少幻觉输出。2.3 技能注册表一切调用行为的数据底座要说过去半年我做的最有价值的一件事就是在某个项目里引入了**技能注册表Skill Registry**机制。这个注册表不是什么高深的东西它就是一个集中的技能元数据仓库每次新增或修改技能都必须在这里登记。一个完整的技能注册条目包含以下要素技能 ID 是全局唯一标识符习惯上用领域-动作-对象的格式命名比如contract-extract-number、email-send-by-template。这种命名方式好处是看名字就能知道用途日志排查时一眼定位。技能描述是给模型看的要用简洁明确的自然语言描述技能功能、输入输出格式、使用前提。这里的描述质量直接影响模型调用的准确率值得花时间打磨。输入输出 Schema 使用 JSON Schema 定义既能用于校验又能作为提示词的一部分传给模型让模型知道该怎么构造调用参数。权限级别是定义该技能需要哪些权限只读、读写、管理这是一道安全防线避免 Agent 在执行过程中做超出范围的操作。失败处理策略定义了调用失败后的行为比如重试、跳过、上报防止一个技能报错导致整个任务链崩溃。注册表的核心价值在于让技能管理从陈年代码里的注释变成了可查询的数据。我之前在一个项目里遇到过技能版本混乱的问题——代码里明明有新版域名检查逻辑但 Agent 还在用旧版工具接口怎么查都查不出原因。后来把所有技能纳入注册表并绑定版本号这类问题彻底杜绝了。3. 实操落地一个可复现的最小技能框架3.1 技能注册与调用的核心数据结构下面给出一个我在实际项目中使用的技能描述结构。这不算标准规范而是经过多个项目检验的、比较稳定的一种写法你可以直接拿来改。{ skill_id: contract-extract-number, name: 合同编号提取, description: 从合同文本中提取唯一的合同编号。适用于采购合同、销售合同、框架协议。如果输入文本中不存在合同编号返回空字符串并标记not_found。, input_schema: { type: object, properties: { text: { type: string, description: 合同全文文本最大长度 50000 字符 } }, required: [text] }, output_schema: { type: object, properties: { contract_number: { type: string, description: 提取到的合同编号 }, status: { type: string, enum: [found, not_found, ambiguous] } }, required: [contract_number, status] }, permission_level: read, max_retries: 2, failure_policy: return_error }这里有几个细节值得说一下。description字段里我特意写了如果输入文本中不存在合同编号返回空字符串并标记not_found。这种对边界情况的明示非常重要因为模型在不确定时倾向于编造一个看起来合理的回答你要主动帮它定义没有结果也是一种合法结果。max_retries和failure_policy是我后来才加的字段。之前没有这两个字段时技能调用失败后 Agent 的行为不可控有的重试三次有的直接把这步跳过但继续往下走生成了完全不靠谱的最终答案。加了显式的失败策略之后异常行为变得可预期了。3.2 调度循环模型如何选取和执行技能有了技能注册表之后Agent 的主循环其实就变得很清晰了。我用一个简单的伪代码来描述这个调度过程def agent_loop(user_request, skill_registry): # 第一步规划 plan planner.plan(user_request, available_skillsskill_registry.list()) # 第二步按计划逐步执行 for step in plan.steps: skill skill_registry.get(step.skill_id) if not skill.check_permission(step.intent): return step.skill_id, permission_denied # 第三步带校验地调用技能 result executor.run(skill, step.args) is_valid, feedback evaluator.validate( resultresult, schemaskill.output_schema ) if not is_valid: return step.skill_id, fvalidation_failed: {feedback} # 第四步汇总并输出 final_answer response_builder.compose(plan, all_results) return final_answer这个循环的核心思想是每一步都有校验。evaluator.validate这一步尤其关键它用技能注册表里的输出 Schema 对模型返回的结果做结构校验字段缺失、类型错误、枚举值越界都能被抓住。我在一个表格处理项目里加上这层校验之后技能调用的整体准确率从 78% 提到了 92%效果非常明显。还有一个细节容易被忽略planner.plan的输入不仅要包含用户请求还要包含可用技能的清单。这样模型在做任务规划时就知道自己有哪些工具可用不会规划出技能库里根本不存在的操作。这也侧面验证了技能描述的重要性——描述写得够清楚规划才能做得准。3.3 从需求到技能的拆解流程我总结了一个四步拆解法让技能设计从拍脑袋变成可执行。这里用一个实际需求作为例子我们要做一个报销单审核助手能识别发票信息、核对报销标准、输出审核意见。第一步叫穷举场景。把需求涉及到的所有操作场景全部列出来先不考虑技术可行性。比如识别发票类型、提取发票金额、识别发票日期、核对发票与报销单一致性、判断金额是否超标准、查询历史报销记录、生成审核意见、输出审批建议。第二步叫合并同类。把处理同一类对象的操作合并成技能单元比如识别发票类型提取发票金额识别发票日期可以合并成发票信息提取因为它们都是对发票这个对象的感知层处理。第三步叫定义边界。给每个技能明确输入输出和适用范围同时写清楚不负责什么。比如核对发票与报销单一致性这个技能不负责判断审批流程是否合规那是另一个技能的事。第四步叫评审验证。把技能清单交给不熟悉项目的人来审看他们能不能根据描述判断该调用哪个技能。如果对方犹豫了说明描述还不够清晰。这一步虽然土但特别有效。这个方法论听起来简单但真正执行到位的人很少。大部分项目停在第一步或第二步就急着写代码了后面必然要返工。3.4 技能评估用数据说话而不是靠感觉有技能体系就一定要有评估机制否则你永远不知道改动是变好了还是变坏了。我在项目中建立了一套三层的评估管道。第一层是单技能评估。对每个技能单独构建测试集比如合同编号提取这个技能准备了 50 个正样本和 20 个负样本正样本要求正确提取负样本要求返回not_found而不是强行编造。这层评估跑得最快改一行代码就能看到效果。第二层是任务链路评估。把一条完整业务链路的多个技能串起来跑看端到端的成功率和耗时。这层评估能发现单技能之间衔接的问题比如上一个技能的输出格式变了下一个技能的解析器没跟上。第三层是随机场景评估。让评估集尽可能接近真实世界的分布包含各种边界情况图片模糊的发票、中英文混合的合同、格式混乱的表格。这层评估最能反映生产环境的真实表现。评估结果要用数据看板展示每次技能调整都记录前后对比值。我在某个项目里建过一个简单的量化表格核心维度包括调用成功率、平均响应时间、结果格式合规率、异常处理覆盖率。这样每次迭代都有据可依团队讨论不再靠我觉得这里有问题这种主观感受。4. 常见问题与排查技巧实录4.1 问题一技能边界模糊导致乱调用这是所有 agent 项目里最经典的问题。现象是用户提出一个请求Agent 调用了一个完全不相关的技能或者在一个任务执行到一半时跳去执行另一个任务。我曾经在一个客服 Agent 项目里遇到过用户问退款什么时候到账Agent 居然调用了产品推荐技能给用户推了一堆商品。排查了很长一段才发现是因为技能描述里写了处理用户咨询这个描述太宽泛了模型把退款咨询和产品推荐都归为了咨询。解决方案很简单但也容易被忽略收紧技能描述中的触发条件。在产品推荐的技能描述里明确写仅当用户表达出购买意向或询问商品信息时调用同时在退款查询的描述里写清楚用户提及退款、到账、金额异常等关键词时应调用本技能。改完之后乱调用率直接下降了一半以上。4.2 问题二上下文爆炸与记忆管理Agent 执行长任务时上下文会不断增加尤其是调用了多个技能后前面技能的原始输出、中间推理过程、工具返回的完整数据都会留在上下文里。上下文一长不仅费用上升模型注意力还会被稀释早先的关键信息可能被忽略。我的处理方法是引入技能级摘要机制。每个技能执行完后不回传完整结果而只回传这个技能的摘要和关键参数。比如合同编号提取技能跑完后上下文里只加入一条合同编号已提取: ABC-2024-001而不是把整个合同文本再塞一遍。这个改动对长链路任务的效果是立竿见影的上下文体积下降了约 40%任务成功率反而提升了。4.3 问题三技能执行结果不稳定同一个技能在同一条输入上跑两次结果不一致这是模型类技能最让人头疼的问题之一。尤其涉及内容生成、方案建议这类认知层技能时即使温度参数设得很低结果还是会飘。我的应对策略是双保险。第一保险是在输出 Schema 里强制加入置信度字段让模型自己评估这次输出的置信水平低置信度的结果自动触发重试。第二保险是引入规则校验针对某些可验证的字段用程序化方法二次确认。比如生成的正则表达式我会用测试用例跑一遍确认能匹配再交付而不是直接信任模型的输出。这种方式会让每次技能调用多花一点时间但换来的是最终结果的可信度大幅提升。在面向企业客户交付时这个可信度比速度重要得多。4.4 问题四技能组合的优先级冲突当 Agent 拥有多个技能且它们之间存在隐含的优先级关系时就会出问题。我曾经在一个人事问答 Agent 里同时配置了查看员工手册和查询请假政策两个技能用户问请假要提前几天申请Agent 调用了员工手册技能返回了一段通用的考勤说明但其实请假政策里才有精确的天数规定。优先级冲突的解法是在技能元数据里增加 priority 字段。两个技能描述相关时让模型框架优先选择优先级高的技能。同时还要在相关技能描述里互相添加提示比如请假政策查询的描述里写若涉及具体请假天数优先调用本技能而非员工手册查询。交叉提示这个技巧很实用代价几乎为零效果却好得出奇。4.5 常见问题速查表我把这些排查记录整理成了一张速查表研发过程中遇到类似问题可以直接定位方向。现象可能原因排查方向常用解法Agent 调用无关技能技能描述边界模糊检查触发条件是否明确在描述中限定触发关键词和排除场景长任务做一半丢失上下文上下文过长导致注意力分散观察任务中途的回复质量变化技能级摘要机制精简单步回传内容相同输入不同结果模型类技能随机性对比多次输出的差异字段增加置信度字段必要时规则校验两个技能响应冲突优先级未定义检查技能注册表的优先级配置显式添加 priority 和交叉提示调用成功但结果格式不对输出 Schema 约束不足检查校验器的执行日志强化输出字段的枚举和类型约束技能执行超时输入数据量过大查看技能耗时的分位数分布增加输入截断或分块处理权限相关报错技能权限级别配置过严检查与执行意图的匹配度调整 permission_level 与实际的匹配策略结果校验不通过返回结构不符合预期对比注册表与实际返回结构更新注册表或修正解析逻辑这八类问题几乎覆盖了我在各个 Agent 项目里遇到过的绝大多数故障场景。形成这张表的过程中最有价值的不是最后的结果而是每次排查时沉淀下来的判断路径它会让你在下一次遇到相似问题时少走很多弯路。5. 从技能到能力Agent 如何持续进化5.1 单技能打磨的三阶段技能不是写出来就能用的它需要经过三个阶段的打磨才算真正成熟。我这几年做过的所有技能几乎都走完了这三步。第一阶段叫跑通主流程。先不管边界情况把最常见的输入跑通确认输出符合预期。这个阶段往往会发现技能描述里的 bug 或者 Schema 设计不合理的地方。第二阶段叫加固边界。开始处理各种异常输入和边缘情况比如空输入、超长输入、格式错误的输入。这个阶段的核心是写异常处理逻辑并确保技能在这些场景下不会崩溃或产生幻觉输出。第三阶段叫压测优化。把技能放到高并发或复杂链路中测试观察性能瓶颈和稳定性。这个阶段我会特别关注技能的耗时构成看看时间主要花在模型调用、工具执行还是数据转换上针对性优化。不要指望一个技能写完就能直接上线至少预留三分之一的时间来做后两个阶段。我见过太多项目在第一步就跑上线结果线上环境各种翻车其实不是模型的问题是技能的边界没有打磨好。5.2 多技能协作的编排模式技能多了之后编排就成了新的核心问题。我的经验是编排逻辑不要散落在提示词里而要显式地用代码定义。常见的一种编排模式叫顺序执行适合流程固定的任务。比如日报生成 Agent先取数据、再生成摘要、最后按模板输出三步依次执行中间没有分支。这种模式最简单也最稳定。第二种模式叫条件路由核心是根据某一步的结果选择不同的后续技能。比如合同审核 Agent如果第一步合同类型识别返回采购合同就走采购合同审核流程返回销售合同就走销售合同流程。这种模式需要给模型一个结构化的决策输出而不能让它自由发挥。第三种模式叫并行聚合适合子任务之间没有依赖的场景。比如市场分析 Agent 需要同时分析竞品价格、用户评价、行业趋势三个分析技能可以并行执行最后汇总输出。并行模式能把整体耗时降低一半以上但要注意各子任务的输出格式必须严格统一否则汇总时会混乱。编排代码化有一个额外的好处方便监控和追踪。每一步执行了什么技能、消耗了多少 token、耗时多久全部可以打进日志。反过来如果你的编排逻辑全写在提示词里出了问题连查都没法查。5.3 技能回放与持续进化最后要讲的这个话题我认为是agent-skills项目最有价值的部分——如何让技能体系在真实使用中持续进化。我的做法是建立一套技能回放机制。每次 Agent 在真实环境中执行的完整轨迹都会记录下来包括用户输入、技能调用序列、每个技能的返回结果、最终输出。然后定期对这些轨迹做分析寻找两类信号。第一类是失败信号。某一步技能调用失败或者最终结果被用户/审核员打回这些都是技能需要优化的直接证据。我会汇总失败模式找到最频繁的哪几种针对性修改技能描述或补充训练数据。第二类是模式信号。某些技能总是一起被调用可能说明它们应该被合并为一个更高层级的技能某些技能自上线以来从未被调用过可能说明它没有存在价值或者它的功能被其他技能覆盖了。定期清理这类技能能让体系保持精炼。这个机制听起来简单但坚持做三个月之后效果非常明显。我在某项目里就是靠回放分析把一次客服咨询的平均技能调用次数从 6.8 次降到了 4.1 次响应速度快了接近一半用户满意度反而上升了。因为多余的调用减少了出错的概率也跟着降低。技能回放的分析不需要多复杂的系统早期的做法简单到用日志查询语句就能实现。关键在于坚持记录和定期复盘把它变成团队的习惯而不仅仅是一个技术系统。现在每完成一个版本迭代我都会安排一次专门的技能复盘对着真实调用记录逐条过把该优化的优化、该合并的合并、该下线的下线。做 Agent 这几年我最大的感受是模型能力在快速迭代但真正决定应用上限的依然是工程化的基本功。agent-skills给我的启发在于它把智能这件事拆解成了一个个可以设计、可以测试、可以优化的工程单元。每打磨好一个技能单元Agent 就多一分可靠每建立起一套评估机制团队就少一分盲目。如果你正在做类似的 Agent 项目我的建议很简单不要急着堆功能先把你手头最核心的三五个技能定义清楚跑通评估闭环再一步步向外扩展。这个基础打得越扎实后面走得就越稳。 
长河君 · 2026/10/13 5:20:10 · 阅读 1.2k 智能体技能体系设计实战：从注册、调度到评估的全流程指南
这两年做智能体项目踩过最大的坑不是模型能力不够而是把 Agent 当成一个能聊天的黑盒来用。agent-skills这个词我是在一次内部技术复盘时认真想明白的——真正让智能体从演示级走向可用级的是它到底掌握了一套什么样的技能体系以及这套体系是怎么被设计、注册、调用和评估的。这篇文章我想把这些经验完整地梳理一遍。如果你正在做 AI Agent 相关的项目或者准备把大模型接入到实际业务里这篇内容会给你一套可以直接参考的技能设计框架包括分层思路、接口规范、评估闭环以及我在多个项目里反复踩过又填平的坑。不聊虚的理论全是能落地的实操记录。1. 项目概述agent-skills 到底在解决什么问题1.1 从一个尴尬的调试现场说起先讲一个我经历过的真实场景。某次和一个团队联调一个文档处理智能体需求很简单用户上传一份合同Agent 帮忙提取关键条款、生成摘要、并按照指定模板输出。Demo 阶段一切正常演示的时候模型也确实能答上来。但一进入真实数据测试就全乱了有的合同是扫描件有的表格嵌套了三层有的条款写了详见附件三但附件根本没上传。Agent 要么答非所问要么直接编造条款内容更麻烦的是它分不清提取信息和判断合同风险这两个动作经常做着做着就跑到另一个任务上去了。调试了三天问题根源慢慢浮出水面我们根本没有给这个 Agent 定义清晰的技能边界。它就像一个什么都会一点但什么都不精的实习生你给它一个模糊指令它就靠临场发挥来凑答案。这个项目之后我彻底意识到Agent 的能力天花板不取决于模型本身有多强而取决于你给它配备了哪些技能以及这些技能被定义得有多清楚。这就是agent-skills这个标题背后真正的价值所在。1.2 agent-skills 的核心定位agent-skills不是一个具体的开源库也不是某个平台的专有名词它代表的是一套面向智能体任务执行的能力封装与组织方式。它的核心思想是把 Agent 需要完成的各类操作拆解成一个个可注册、可调用、可评估的原子技能单元再通过编排层将它们组合成完整的工作流。我习惯把它理解为给 Agent 编写岗位说明书。一份好的岗位说明书会写清楚这个岗位负责什么、不负责什么、遇到什么情况该做什么判断、产出标准是什么。agent-skills要做的正是这件事——把模糊的智能转化为明确的能力清单。这套思路之所以越来越重要是因为现在的 Agent 应用已经从单轮问答进化到了多步骤任务执行。用户不再满足于让模型说一段话而是希望它做成一件事。做成一件事就需要工具调用、需要状态管理、需要异常处理、需要结果校验这些都不是靠提示词堆砌能解决的必须有结构化的技能体系来支撑。1.3 这套技能体系适合谁结合我接触过的项目来看以下几类人会从agent-skills的思维方式里获益最多第一类是做智能体应用开发的工程师。无论你用哪种框架市面上主流的 agent 框架都支持 skill 注册机制掌握技能拆解与设计的底层逻辑能让你的代码结构更清晰、调试成本更低。第二类是业务方或产品经理。理解技能体系的边界和限制能帮助你更准确地定义需求——不是笼统地说做个智能助手而是说清楚这个助手需要具备哪几项可验收的能力。第三类是对 Agent 技术感兴趣的爱好者。即使不写代码了解技能体系的组织逻辑也能帮助你在使用各种 Agent 产品时更清楚地判断它擅长什么、不擅长什么避免产生不切实际的预期。这里有一个我反复强调的观点agent-skills不是某个具体工具的说明书而是一种思考 Agent 的方式。掌握了这种思考方式无论底层模型怎么换、框架怎么变你都能快速搭建出可靠的应用。2. 技能体系设计核心能力拆解与选型逻辑2.1 为什么技能要分层而不是堆功能很多人设计 Agent 技能时容易犯一个错误恨不得把所有功能塞进一个技能里。比如做一个全能办公助手就把文档读取、表格处理、邮件发送、日历管理全部写在一个技能描述里结果模型根本不知道该在什么时候调用哪个功能。我在实践中确定的思路是技能必须分层而且每一层只解决一类问题。我通常把技能体系分为三层。感知层负责获取和解析信息是整个技能体系的地基。举个例子一个文档处理 Agent 的感知层技能包括文本提取、图片 OCR、表格结构识别。如果感知层做不好后面的所有分析和生成都是空中楼阁。认知层负责理解和推理是 Agent 的大脑。它包含信息抽取、意图判断、风险识别、方案生成等技能。认知层通常需要调用大模型的能力但要注意的是不是所有任务都需要最强模型有些结构化抽取任务用轻量模型反而更快更省。行动层负责执行和输出是 Agent 的手。它包含格式化输出、接口调用、文件写入、消息通知等技能。行动层的设计要尽量标准化让执行结果可以被上一层校验和反馈。这三层之间的关系是单向依赖的感知层为认知层提供输入认知层为行动层提供决策。这个单向依赖非常重要它避免了技能之间的循环混乱让问题定位变得容易。我见过太多失败的 agent 项目本质问题就是技能层级混乱感知和认知互相穿插出了问题都不知道该查哪一层。2.2 技能粒度越细越好还是越粗越好技能粒度是我在多个项目中反复调整过的一个参数。粒度太大技能变成一个又笨又重的工具灵活性差、复用率低粒度太小Agent 要在一堆细碎技能之间频繁切换不仅浪费 token还容易让模型决策混乱。分享一下我现在采用的划分标准一个技能职责单一且产出可评估就是合适的粒度。比如提取合同编号是一个技能判断合同风险等级是另一个技能这两个不会混淆。但如果把处理合同整体作为一个技能里面包含了提取、判断、摘要、归档一堆动作这个技能就不合格。实操中的一个判断技巧是如果某个技能的描述需要超过 100 个字才能说明白那它大概率要被拆分成多个子技能。技能描述应当像 API 文档一样精确输入是什么、输出是什么、什么情况下不该调用它。另外我建议每个技能都要声明明确的适用范围。一个技能只对PDF 格式的采购合同有效那么当输入是一张图片时Agent 就应该走其他技能而不是硬着头皮处理这样可以显著减少幻觉输出。2.3 技能注册表一切调用行为的数据底座要说过去半年我做的最有价值的一件事就是在某个项目里引入了**技能注册表Skill Registry**机制。这个注册表不是什么高深的东西它就是一个集中的技能元数据仓库每次新增或修改技能都必须在这里登记。一个完整的技能注册条目包含以下要素技能 ID 是全局唯一标识符习惯上用领域-动作-对象的格式命名比如contract-extract-number、email-send-by-template。这种命名方式好处是看名字就能知道用途日志排查时一眼定位。技能描述是给模型看的要用简洁明确的自然语言描述技能功能、输入输出格式、使用前提。这里的描述质量直接影响模型调用的准确率值得花时间打磨。输入输出 Schema 使用 JSON Schema 定义既能用于校验又能作为提示词的一部分传给模型让模型知道该怎么构造调用参数。权限级别是定义该技能需要哪些权限只读、读写、管理这是一道安全防线避免 Agent 在执行过程中做超出范围的操作。失败处理策略定义了调用失败后的行为比如重试、跳过、上报防止一个技能报错导致整个任务链崩溃。注册表的核心价值在于让技能管理从陈年代码里的注释变成了可查询的数据。我之前在一个项目里遇到过技能版本混乱的问题——代码里明明有新版域名检查逻辑但 Agent 还在用旧版工具接口怎么查都查不出原因。后来把所有技能纳入注册表并绑定版本号这类问题彻底杜绝了。3. 实操落地一个可复现的最小技能框架3.1 技能注册与调用的核心数据结构下面给出一个我在实际项目中使用的技能描述结构。这不算标准规范而是经过多个项目检验的、比较稳定的一种写法你可以直接拿来改。{ skill_id: contract-extract-number, name: 合同编号提取, description: 从合同文本中提取唯一的合同编号。适用于采购合同、销售合同、框架协议。如果输入文本中不存在合同编号返回空字符串并标记not_found。, input_schema: { type: object, properties: { text: { type: string, description: 合同全文文本最大长度 50000 字符 } }, required: [text] }, output_schema: { type: object, properties: { contract_number: { type: string, description: 提取到的合同编号 }, status: { type: string, enum: [found, not_found, ambiguous] } }, required: [contract_number, status] }, permission_level: read, max_retries: 2, failure_policy: return_error }这里有几个细节值得说一下。description字段里我特意写了如果输入文本中不存在合同编号返回空字符串并标记not_found。这种对边界情况的明示非常重要因为模型在不确定时倾向于编造一个看起来合理的回答你要主动帮它定义没有结果也是一种合法结果。max_retries和failure_policy是我后来才加的字段。之前没有这两个字段时技能调用失败后 Agent 的行为不可控有的重试三次有的直接把这步跳过但继续往下走生成了完全不靠谱的最终答案。加了显式的失败策略之后异常行为变得可预期了。3.2 调度循环模型如何选取和执行技能有了技能注册表之后Agent 的主循环其实就变得很清晰了。我用一个简单的伪代码来描述这个调度过程def agent_loop(user_request, skill_registry): # 第一步规划 plan planner.plan(user_request, available_skillsskill_registry.list()) # 第二步按计划逐步执行 for step in plan.steps: skill skill_registry.get(step.skill_id) if not skill.check_permission(step.intent): return step.skill_id, permission_denied # 第三步带校验地调用技能 result executor.run(skill, step.args) is_valid, feedback evaluator.validate( resultresult, schemaskill.output_schema ) if not is_valid: return step.skill_id, fvalidation_failed: {feedback} # 第四步汇总并输出 final_answer response_builder.compose(plan, all_results) return final_answer这个循环的核心思想是每一步都有校验。evaluator.validate这一步尤其关键它用技能注册表里的输出 Schema 对模型返回的结果做结构校验字段缺失、类型错误、枚举值越界都能被抓住。我在一个表格处理项目里加上这层校验之后技能调用的整体准确率从 78% 提到了 92%效果非常明显。还有一个细节容易被忽略planner.plan的输入不仅要包含用户请求还要包含可用技能的清单。这样模型在做任务规划时就知道自己有哪些工具可用不会规划出技能库里根本不存在的操作。这也侧面验证了技能描述的重要性——描述写得够清楚规划才能做得准。3.3 从需求到技能的拆解流程我总结了一个四步拆解法让技能设计从拍脑袋变成可执行。这里用一个实际需求作为例子我们要做一个报销单审核助手能识别发票信息、核对报销标准、输出审核意见。第一步叫穷举场景。把需求涉及到的所有操作场景全部列出来先不考虑技术可行性。比如识别发票类型、提取发票金额、识别发票日期、核对发票与报销单一致性、判断金额是否超标准、查询历史报销记录、生成审核意见、输出审批建议。第二步叫合并同类。把处理同一类对象的操作合并成技能单元比如识别发票类型提取发票金额识别发票日期可以合并成发票信息提取因为它们都是对发票这个对象的感知层处理。第三步叫定义边界。给每个技能明确输入输出和适用范围同时写清楚不负责什么。比如核对发票与报销单一致性这个技能不负责判断审批流程是否合规那是另一个技能的事。第四步叫评审验证。把技能清单交给不熟悉项目的人来审看他们能不能根据描述判断该调用哪个技能。如果对方犹豫了说明描述还不够清晰。这一步虽然土但特别有效。这个方法论听起来简单但真正执行到位的人很少。大部分项目停在第一步或第二步就急着写代码了后面必然要返工。3.4 技能评估用数据说话而不是靠感觉有技能体系就一定要有评估机制否则你永远不知道改动是变好了还是变坏了。我在项目中建立了一套三层的评估管道。第一层是单技能评估。对每个技能单独构建测试集比如合同编号提取这个技能准备了 50 个正样本和 20 个负样本正样本要求正确提取负样本要求返回not_found而不是强行编造。这层评估跑得最快改一行代码就能看到效果。第二层是任务链路评估。把一条完整业务链路的多个技能串起来跑看端到端的成功率和耗时。这层评估能发现单技能之间衔接的问题比如上一个技能的输出格式变了下一个技能的解析器没跟上。第三层是随机场景评估。让评估集尽可能接近真实世界的分布包含各种边界情况图片模糊的发票、中英文混合的合同、格式混乱的表格。这层评估最能反映生产环境的真实表现。评估结果要用数据看板展示每次技能调整都记录前后对比值。我在某个项目里建过一个简单的量化表格核心维度包括调用成功率、平均响应时间、结果格式合规率、异常处理覆盖率。这样每次迭代都有据可依团队讨论不再靠我觉得这里有问题这种主观感受。4. 常见问题与排查技巧实录4.1 问题一技能边界模糊导致乱调用这是所有 agent 项目里最经典的问题。现象是用户提出一个请求Agent 调用了一个完全不相关的技能或者在一个任务执行到一半时跳去执行另一个任务。我曾经在一个客服 Agent 项目里遇到过用户问退款什么时候到账Agent 居然调用了产品推荐技能给用户推了一堆商品。排查了很长一段才发现是因为技能描述里写了处理用户咨询这个描述太宽泛了模型把退款咨询和产品推荐都归为了咨询。解决方案很简单但也容易被忽略收紧技能描述中的触发条件。在产品推荐的技能描述里明确写仅当用户表达出购买意向或询问商品信息时调用同时在退款查询的描述里写清楚用户提及退款、到账、金额异常等关键词时应调用本技能。改完之后乱调用率直接下降了一半以上。4.2 问题二上下文爆炸与记忆管理Agent 执行长任务时上下文会不断增加尤其是调用了多个技能后前面技能的原始输出、中间推理过程、工具返回的完整数据都会留在上下文里。上下文一长不仅费用上升模型注意力还会被稀释早先的关键信息可能被忽略。我的处理方法是引入技能级摘要机制。每个技能执行完后不回传完整结果而只回传这个技能的摘要和关键参数。比如合同编号提取技能跑完后上下文里只加入一条合同编号已提取: ABC-2024-001而不是把整个合同文本再塞一遍。这个改动对长链路任务的效果是立竿见影的上下文体积下降了约 40%任务成功率反而提升了。4.3 问题三技能执行结果不稳定同一个技能在同一条输入上跑两次结果不一致这是模型类技能最让人头疼的问题之一。尤其涉及内容生成、方案建议这类认知层技能时即使温度参数设得很低结果还是会飘。我的应对策略是双保险。第一保险是在输出 Schema 里强制加入置信度字段让模型自己评估这次输出的置信水平低置信度的结果自动触发重试。第二保险是引入规则校验针对某些可验证的字段用程序化方法二次确认。比如生成的正则表达式我会用测试用例跑一遍确认能匹配再交付而不是直接信任模型的输出。这种方式会让每次技能调用多花一点时间但换来的是最终结果的可信度大幅提升。在面向企业客户交付时这个可信度比速度重要得多。4.4 问题四技能组合的优先级冲突当 Agent 拥有多个技能且它们之间存在隐含的优先级关系时就会出问题。我曾经在一个人事问答 Agent 里同时配置了查看员工手册和查询请假政策两个技能用户问请假要提前几天申请Agent 调用了员工手册技能返回了一段通用的考勤说明但其实请假政策里才有精确的天数规定。优先级冲突的解法是在技能元数据里增加 priority 字段。两个技能描述相关时让模型框架优先选择优先级高的技能。同时还要在相关技能描述里互相添加提示比如请假政策查询的描述里写若涉及具体请假天数优先调用本技能而非员工手册查询。交叉提示这个技巧很实用代价几乎为零效果却好得出奇。4.5 常见问题速查表我把这些排查记录整理成了一张速查表研发过程中遇到类似问题可以直接定位方向。现象可能原因排查方向常用解法Agent 调用无关技能技能描述边界模糊检查触发条件是否明确在描述中限定触发关键词和排除场景长任务做一半丢失上下文上下文过长导致注意力分散观察任务中途的回复质量变化技能级摘要机制精简单步回传内容相同输入不同结果模型类技能随机性对比多次输出的差异字段增加置信度字段必要时规则校验两个技能响应冲突优先级未定义检查技能注册表的优先级配置显式添加 priority 和交叉提示调用成功但结果格式不对输出 Schema 约束不足检查校验器的执行日志强化输出字段的枚举和类型约束技能执行超时输入数据量过大查看技能耗时的分位数分布增加输入截断或分块处理权限相关报错技能权限级别配置过严检查与执行意图的匹配度调整 permission_level 与实际的匹配策略结果校验不通过返回结构不符合预期对比注册表与实际返回结构更新注册表或修正解析逻辑这八类问题几乎覆盖了我在各个 Agent 项目里遇到过的绝大多数故障场景。形成这张表的过程中最有价值的不是最后的结果而是每次排查时沉淀下来的判断路径它会让你在下一次遇到相似问题时少走很多弯路。5. 从技能到能力Agent 如何持续进化5.1 单技能打磨的三阶段技能不是写出来就能用的它需要经过三个阶段的打磨才算真正成熟。我这几年做过的所有技能几乎都走完了这三步。第一阶段叫跑通主流程。先不管边界情况把最常见的输入跑通确认输出符合预期。这个阶段往往会发现技能描述里的 bug 或者 Schema 设计不合理的地方。第二阶段叫加固边界。开始处理各种异常输入和边缘情况比如空输入、超长输入、格式错误的输入。这个阶段的核心是写异常处理逻辑并确保技能在这些场景下不会崩溃或产生幻觉输出。第三阶段叫压测优化。把技能放到高并发或复杂链路中测试观察性能瓶颈和稳定性。这个阶段我会特别关注技能的耗时构成看看时间主要花在模型调用、工具执行还是数据转换上针对性优化。不要指望一个技能写完就能直接上线至少预留三分之一的时间来做后两个阶段。我见过太多项目在第一步就跑上线结果线上环境各种翻车其实不是模型的问题是技能的边界没有打磨好。5.2 多技能协作的编排模式技能多了之后编排就成了新的核心问题。我的经验是编排逻辑不要散落在提示词里而要显式地用代码定义。常见的一种编排模式叫顺序执行适合流程固定的任务。比如日报生成 Agent先取数据、再生成摘要、最后按模板输出三步依次执行中间没有分支。这种模式最简单也最稳定。第二种模式叫条件路由核心是根据某一步的结果选择不同的后续技能。比如合同审核 Agent如果第一步合同类型识别返回采购合同就走采购合同审核流程返回销售合同就走销售合同流程。这种模式需要给模型一个结构化的决策输出而不能让它自由发挥。第三种模式叫并行聚合适合子任务之间没有依赖的场景。比如市场分析 Agent 需要同时分析竞品价格、用户评价、行业趋势三个分析技能可以并行执行最后汇总输出。并行模式能把整体耗时降低一半以上但要注意各子任务的输出格式必须严格统一否则汇总时会混乱。编排代码化有一个额外的好处方便监控和追踪。每一步执行了什么技能、消耗了多少 token、耗时多久全部可以打进日志。反过来如果你的编排逻辑全写在提示词里出了问题连查都没法查。5.3 技能回放与持续进化最后要讲的这个话题我认为是agent-skills项目最有价值的部分——如何让技能体系在真实使用中持续进化。我的做法是建立一套技能回放机制。每次 Agent 在真实环境中执行的完整轨迹都会记录下来包括用户输入、技能调用序列、每个技能的返回结果、最终输出。然后定期对这些轨迹做分析寻找两类信号。第一类是失败信号。某一步技能调用失败或者最终结果被用户/审核员打回这些都是技能需要优化的直接证据。我会汇总失败模式找到最频繁的哪几种针对性修改技能描述或补充训练数据。第二类是模式信号。某些技能总是一起被调用可能说明它们应该被合并为一个更高层级的技能某些技能自上线以来从未被调用过可能说明它没有存在价值或者它的功能被其他技能覆盖了。定期清理这类技能能让体系保持精炼。这个机制听起来简单但坚持做三个月之后效果非常明显。我在某项目里就是靠回放分析把一次客服咨询的平均技能调用次数从 6.8 次降到了 4.1 次响应速度快了接近一半用户满意度反而上升了。因为多余的调用减少了出错的概率也跟着降低。技能回放的分析不需要多复杂的系统早期的做法简单到用日志查询语句就能实现。关键在于坚持记录和定期复盘把它变成团队的习惯而不仅仅是一个技术系统。现在每完成一个版本迭代我都会安排一次专门的技能复盘对着真实调用记录逐条过把该优化的优化、该合并的合并、该下线的下线。做 Agent 这几年我最大的感受是模型能力在快速迭代但真正决定应用上限的依然是工程化的基本功。agent-skills给我的启发在于它把智能这件事拆解成了一个个可以设计、可以测试、可以优化的工程单元。每打磨好一个技能单元Agent 就多一分可靠每建立起一套评估机制团队就少一分盲目。如果你正在做类似的 Agent 项目我的建议很简单不要急着堆功能先把你手头最核心的三五个技能定义清楚跑通评估闭环再一步步向外扩展。这个基础打得越扎实后面走得就越稳。