1. 项目背景为什么我要折腾技能化这件事做AI Agent开发的朋友应该都有同感真正让一个智能体从能聊天变成能干活的不是模型本身有多聪明而是你给它装配了多少可靠的能力。这个能力在行业里越来越倾向于用一个词来概括——agent-skills也就是智能体技能。我今年大半年的精力几乎都扑在这套技能化体系上。起因很简单手头一个内部项目需要Agent完成一系列复杂任务包括检索文档、调用内部API、操作数据库、生成报表甚至还要自动写邮件发出去。最初我把这些能力全部写死在Agent的主流程里结果两个月后代码变成一团乱麻加一个新功能要动十几个文件改一个接口的报错要翻遍整个项目。后来我彻底重构把技能作为独立的一等公民抽象出来形成了一套可注册、可编排、可复用的技能体系也就是这个agent-skills项目的核心思路。这篇文章不聊天花乱坠的架构理论就讲我在落地这套体系时踩过的坑、验证过的方案、总结出的设计原则。适合正在做Agent开发的工程师、准备给大模型应用加手和脚的产品经理以及所有对智能体工程化感兴趣的读者。如果你还没接触过Agent开发也不用担心我会从最基础的设计思路讲起保证你能跟上节奏。2. 技能究竟是什么给Agent装上可插拔的手脚2.1 从写死功能到声明式技能传统开发模式下你要让Agent调用一个工具通常是在代码里写一个函数然后把这个函数塞给Agent的调用逻辑。刚开始一两个工具还好一旦超过十个问题就来了函数参数不一致、返回值格式混乱、Agent经常把参数填错更别提不同工具之间的调用顺序和组合逻辑完全靠代码硬编码。技能化的核心思路是把每一个能力封装成一个标准化的技能包。这个技能包有自己的名字、功能描述、输入参数定义、执行逻辑和返回值规范。Agent不需要理解这个技能在代码层面怎么实现它只需要根据用户的需求从技能列表中挑出合适的技能填好参数触发执行。我在做这个设计的时候参考了插件系统的思路。就像你给浏览器装扩展每个扩展独立开发、独立更新、互不干扰。Agent的技能也应该是这样——新增一个技能不需要改动Agent主逻辑删除一个技能也不会影响其他能力运转。这个可插拔特性是技能化体系最核心的价值。2.2 技能包的标准结构拆解一个标准的agent-skill我通常是这么组织的它包含一个元信息文件描述这个技能是干什么的、参数怎么填、一个执行模块真正干活的代码、以及一个可选的自检模块在技能执行前后验证状态。# 一个标准技能包的结构示例 my_skill/ ├── SKILL.md # 技能描述文件写给模型看的说明书 ├── run.py # 技能执行入口真正的业务逻辑 ├── schema.json # 参数定义输入输出的JSON Schema ├── test.py # 自检脚本验证技能是否正常工作 └── requirements.txt # 依赖声明这个结构不是拍脑袋定的而是踩过无数坑之后总结出来的。以前我把参数定义写在代码注释里模型根本读不到后来把描述写得很随意结果Agent经常误解技能用途再后来加入了自检模块每次技能升级后先跑一遍测试确保不会把Agent带沟里去。2.3 为什么技能描述比实现更重要这里要说一个很多新手容易忽略的关键点对于Agent系统来说技能的描述远比实现更重要。因为模型决定调用哪个技能、怎么填参数完全依赖它对技能描述的理解。实现哪怕写得再漂亮如果描述让模型产生了误解一切白搭。我之前有个技能是获取用户订单信息实现逻辑很简单查数据库然后返回。但当时描述写得太笼统结果Agent经常在用户问我上个月买了什么的时候错误地调用获取当前订单状态这个技能导致答非所问。后来我按照以下模板重写了所有技能描述准确率提升非常明显技能一句话概述这个技能在什么场景下使用最多两句话。适用条件明确列出什么时候该用、什么时候绝不能用。参数详解每个参数的含义、格式、取值边界最好附一个示例。返回说明返回数据的结构、可能出现的异常情况。这个模板看起来简单但执行起来需要很多细节打磨。后面我专门用一节讲参数设计那是技能化体系最容易被低估的难点。3. 参数设计的艺术Agent不是你的同事它不会猜3.1 参数Schema决定Agent的上限如果把Agent技能比作一把工具参数Schema就是工具上的手柄——握持是否顺手直接决定了你能不能把活干漂亮。我见过太多技能设计者把参数定义当成普通API接口来写给个类型和必填标志就算完事。但在Agent场景下这远远不够。关键原因在于普通API是程序员之间打交道双方有共同的上下文一个orderId字段大家都能猜到含义。但Agent模型是一个聪明但不熟业务的新同事它不会主动猜测你的字段到底该填什么格式。举个例子一个查询天气的技能如果参数只写city: string模型可能会填北京、beijing、北京市等多种格式而你的后端逻辑可能只认其中一种。所以我在定义技能参数时会执行一套严格的规范。核心原则是让模型在没有任何外部提示的情况下也能填出完全正确的参数。这不是靠运气而是靠把规则讲清楚。{ parameters: { city: { type: string, description: 城市名称使用标准中文全称不包含省份后缀例如北京、上海、广州, examples: [北京, 上海], required: true }, date: { type: string, description: 查询日期格式为YYYY-MM-DD时区为中国标准时间取值范围为今天及未来7天, examples: [2025-01-15], required: false } } }3.2 常见参数错误及对策下面这几个问题是我在实战中反复遇到的几乎每一个都坑过我的项目整理成表格供大家对照参考。常见错误表现对策参数描述模糊模型填了完整名词而非代码需要的短码每个参数都要说明取值范围和格式缺少示例值模型不知道日期该填今天还是明天提供1-2个示例尤其是受时间影响的参数没有枚举限定模型填了不在支持范围内的值在描述中显式列出所有可选项参数间依赖关系不清传了A但不传B导致接口报错在描述中明确当XX参数存在时必须同时传YY时间格式不一致有的接口要时间戳有的要字符串全项目统一使用格式并在描述中一次说清这里特别说一下枚举限定。有些技能的状态字段比如订单状态、工单进度本身是可枚举的。如果你不列出来模型就会自由发挥。我在内部项目里曾经因为订单状态枚举没写全导致Agent反复用已派单这种状态值去查数据而系统里根本没有这个值。后来我在参数描述里明确画了范围状态枚举值仅为待支付、已支付、已发货、已完成、已取消此后再没出过这类问题。3.3 为Agent设计包容性输入还有一类问题更隐蔽同一个参数不同用户、不同场景下表达方式完全不同。比如日期用户可能说今天明天下周一元旦,这些自然语言需要被转换成标准格式才能填入参数。我的做法是对于这类用户输入技能内部单独设计一层语义解析格式转换逻辑。也就是说参数定义给Agent看的是一个宽泛的、符合人类直觉的格式比如自然语言日期技能内部把它转换成系统需要的精确格式比如时间戳。这个思路也符合Agent开发的整体趋势——让模型做语义理解让代码做精确执行。我建议大家在设计参数时不要为了迁就后端逻辑而强迫模型填机器语言如果发现一个参数让模型经常填错不妨想一想是不是可以让技能自己处理这个转换这属于典型的花小钱办大事。4. 技能注册与调度Agent怎么知道该用什么4.1 技能清单与路由策略技能化的下一步是把技能注册到一个统一的清单里让Agent在执行任务时能看到所有可用的技能然后根据任务需求做选择。这一步在技术实现上很简单但在策略设计上很有讲究。最简单的做法是把所有技能全部塞给模型让模型自己选。但当技能数量超过一定阈值模型就晕了经常选错。我实测下来当一次性提供给模型的技能描述超过20个准确率会显著下降。所以我后来引入了分级路由机制先用一个轻量级分类器或者让模型先粗选技能类别再在小范围内细选具体技能。举个例子我的Agent系统里有大约40个技能整体分成五类数据查询类、内容生成类、流程操作类、系统管理类、外部集成类。模型拿到用户请求后第一步先判断这个请求属于哪个类别第二步再在该类别下挑选具体技能。这种方式让每次决策的候选集缩小到8个以内准确率提升不少而且调试起来也清晰。4.2 技能优先级与互斥处理技能多了之后另一个必然遇到的问题是多个技能可能都能处理同一个请求但效果天差地别。比如用户问帮我看看昨晚的销售数据既可以用销售数据查询技能也可以用生成销售报表技能——前者可能只是简单的查数字后者则会生成完整分析。这就需要定义技能的优先级和互斥规则。我的做法是在技能元信息中增加两个字段priority整数数值越大优先级越高。当模型不确定选哪个时优先选高优先级技能。conflicts与其他技能的冲突列表。某些技能不能同时启用或者需要在特定条件下才允许调用。实现这些规则其实不复杂关键是想清楚业务场景。我在设计规则时通常会和业务方开一次评审会把所有可能产生歧义的场景列出来一条条确认优先级。宁可前期多花点时间也不要在线上让Agent自作主张。5. 完整实操从零构建一个可用技能5.1 选型与初始化纸上谈兵这么久接下来我完整演示一遍如何从零开发一个agent-skill让它能在真实项目中工作。为了便于理解我用一个最常见的场景——查询员工信息来做示例。首先我需要确认技能包目录结构。这里我没有用任何重型框架就是一个纯Python项目加上一份标准化的元信息文件。之所以不用框架是因为技能本身应该是轻量的过度依赖框架反而失去了可插拔的优势。# 创建技能包目录 mkdir employee_query cd employee_query touch SKILL.md schema.json run.py test.py5.2 编写技能描述文件第一步是写SKILL.md这是整个技能最关键的文件。模型会反复阅读这个文件来判断何时调用该技能所以必须写得极其清晰。我结合前面的经验用结构化写法来组织内容。# 技能查询员工信息 ## 功能概述 根据姓名、工号或部门查询公司内部员工的基本信息包括姓名、工号、部门、职位、联系方式等。适用于HR系统管理、内部通讯录查询等场景。 ## 适用场景 - 用户询问某某的联系方式是什么 - 用户询问技术部有哪些员工 - 用户需要确认某人的职位或所属部门 ## 不适用场景 - 用户询问员工的考勤记录或工资明细请使用查询薪酬考勤技能 - 用户询问外部客户或非本公司人员信息 ## 参数说明 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | name | string | 否 | 员工姓名支持模糊匹配例如张会匹配所有姓张的员工 | | employee_id | string | 否 | 员工工号精确匹配例如E1001 | | department | string | 否 | 部门名称使用公司标准部门名例如技术部 | 注意name、employee_id、department三个参数必须至少传入一个。 ## 返回结果 返回匹配员工的列表每个员工包含以下字段 - name: 员工姓名 - employee_id: 工号 - department: 部门 - position: 职位 - phone: 联系电话 - email: 企业邮箱这里我把不适用场景单独列出来目的是给模型明确的负向信号。经验表明仅告诉模型什么时候用是不够的必须同时告诉它什么时候不用否则模型会拿这个技能硬套所有相关问题。5.3 实现技能执行逻辑接下来是run.py真正干活的代码。这里我不写具体的数据库操作只演示技能执行的骨架逻辑重点看它的健壮性设计。员工查询技能执行模块 import json import re from datetime import datetime def validate_params(params: dict) - dict: 参数校验与标准化 errors [] # 至少需要一个查询条件 if not any(params.get(k) for k in (name, employee_id, department)): errors.append(参数错误name、employee_id、department 至少需要传入一个) # 工号格式校验 emp_id params.get(employee_id) if emp_id and not re.match(r^E\d{4}$, emp_id): errors.append(f参数错误employee_id 格式不正确期望格式如 E1001实际为 {emp_id}) if errors: raise ValueError(; .join(errors)) # 姓名去空格 if params.get(name): params[name] params[name].strip() return params def execute(params: dict) - str: 技能执行入口返回JSON字符串 try: params validate_params(params) # 这里省略真正的数据库查询逻辑 results query_employee_db(params) response { status: success, data: results, query_time: datetime.now().isoformat(), total: len(results) } return json.dumps(response, ensure_asciiFalse) except ValueError as e: return json.dumps({status: error, message: str(e)}, ensure_asciiFalse) except Exception as e: # 兜底异常处理避免把未处理异常抛给Agent return json.dumps({status: error, message: f系统异常{str(e)}}, ensure_asciiFalse)执行模块的设计有几个细节值得注意。第一参数校验必须独立在前不能让脏数据进到核心查询逻辑第二所有返回值统一是JSON字符串方便Agent解析第三异常处理要考虑什么错误信息该给模型看——技术栈细节不要暴露但要给出足够的排查线索。5.4 注册技能并验证schema.json和SKILL.md的内容类似只不过是从代码层面描述技能接口。它通常在技能注册阶段被系统读取用于生成调用Agent函数时需要的function schema。{ name: query_employee_info, description: 查询员工基本信息支持按姓名、工号或部门查询, parameters: { type: object, properties: { name: {type: string, description: 员工姓名}, employee_id: {type: string, description: 员工工号}, department: {type: string, description: 部门名称} } } }技能注册的方式和项目技术栈有关。我这里采用扫目录读配置的方式Agent启动时扫描指定的技能目录逐个读取schema.json把技能注册到函数列表里。这种方式的好处是新增技能零成本——把技能包丢进目录重启系统就能生效。验证环节我一般用两种手段一是跑test.py对技能的核心路径做断言二是直接用一个模拟Agent环境给一条真实用户请求看技能能否被正确调用。后者更重要因为有时候代码逻辑没问题但技能描述写得不清楚模型压根不会调用它。6. 技能编排从单技能到多技能协作6.1 技能的串联与组合单个技能能解决的问题有限真实业务场景往往需要多个技能协作。比如用户说帮我查一下张三的联系方式然后给他发一封问候邮件这就需要两个技能查询员工信息和发送邮件串起来执行。我实现技能组合的方式是参数传递依赖让技能A的返回值直接成为技能B的输入参数。这个逻辑可以在Agent层面实现也可以单独编排出一个个工作流技能。拿上面这个场景举例。如果只是让模型自由发挥它能完成但每次执行过程可能不稳定——有时先发邮件再查信息逻辑就乱了。我更推荐的做法是把这个组合逻辑固化成一个高层技能。也就是说在普通技能之上再加一层编排技能它内部定义了子技能的执行顺序和数据传递规则。这样做能让执行过程从概率正确变成稳定正确。6.2 一个编排技能的示例编排技能的本质是一个脚本它定义了在特定场景下应该按什么顺序调用哪些技能、如何处理中间结果。我通常用JSON配置来表达让非开发人员也能理解和调整。{ skill_name: send_greeting_by_employee, description: 根据员工姓名或工号查询联系方式并发送问候邮件, steps: [ { step: 1, skill: query_employee_info, input_mapping: {name: {user_input.name}, employee_id: {user_input.employee_id}}, output_key: employee_info }, { step: 2, skill: send_email, input_mapping: { to: {employee_info.data[0].email}, subject: 问候邮件, content: {user_input.message_template} } } ], error_policy: { step_1_not_found: 如果查询结果为空直接返回未找到该员工信息不再执行后续步骤 } }这里的关键点在于output_key和input_mapping的设计。每个步骤产出的数据会暂存到上下文中后续步骤可以通过路径表达式引用。路径表达式的语法需要小心设计否则嵌套多了非常容易出错。我在测试阶段发现写编排配置的最大挑战不是逻辑本身而是数据格式的兼容性——一个技能返回的是data数组另一个技能的入参却是单个对象。所以后来我统一规范了所有技能的返回结构状态码、提示信息、业务数据全部标准化编排引擎才能顺畅衔接。6.3 编排中的容错与回退多技能协作还意味着错误可能的多样性。我在实践中总结了三种最常遇到的场景及应对方式上一技能返回空结果比如查不到员工信息就不能继续发邮件。此时编排应中止并返回清晰的提示。上一技能抛异常比如邮件接口超时。此时应重试或者换成备用渠道而不是直接把错误抛给用户。参数映射缺失比如输入中缺了员工工号但姓名有两个员工匹配。此时需要设计歧义消解逻辑比如先向用户确认到底指哪一个。容错设计是一项细致活不能一概而论。我给的建议是先梳理业务上如果这次失败会怎样按影响程度决定该中止、重试还是降级。别想着一个通用方案打天下。7. 常见问题与排查技巧实录7.1 模型为什么不调用我的技能这是最让人抓狂的问题之一。明明技能都注册好了但模型就是视而不见绕开技能自己瞎编答案或者一直用另一个技能。排查这个问题的思路我基本按照下面几步走第一步确认技能真的被加载了。打印Agent系统启动时的技能注册日志看有没有报错。第二步检查技能描述是否与其他技能冲突。两个技能描述太相似时模型可能随机挑一个。第三步检查SKILL.md和schema.json是否一致。如果不一致模型读到的信息是混乱的。第四步检查技能的参数是否过于复杂。如果必要的参数超过4个模型很容易填不齐而放弃调用。有个很典型的案例我加了一个生成周报技能但在技能描述里写了一句适用于任何内容生成场景结果模型不管用户问什么都会尝试调用它还经常把参数填错。把适用范围改小之后这个问题立刻消失了。7.2 技能执行结果偶尔对、偶尔错这种间歇性错误通常比完全不可用更让人头疼。我在排查这类问题时的经验是记录一切。技能执行模块的入参、出参、异常信息全部写入日志方便事后复盘。最常见的间歇性错误原因有二。第一个是参数格式不稳定模型有时按描述填了标准格式有时自由发挥填了其他格式而技能内部没有做兼容处理。第二个是外部依赖不稳定比如数据库连接偶尔超时或者第三方接口限流。前者需要加强技能内部的参数标准化后者则需要加缓存、重试等基础设施。另外注意一点如果技能内部有随机性比如调用了大模型生成内容那输出本身就不稳定这不算是bug而是需要技能的调用方比如编排流程设计好容错。7.3 技能升级后老场景失效技能迭代后出现回归这个问题在工程上很常见在Agent技能体系里也同样存在。我经历过一次优化了某个技能的返回格式没仔细核对下游依赖结果所有引用这个技能的编排流程全部异常。后来我强制要求技能升级必须过三关。第一关单技能自测确保核心路径正常第二关下游编排流程回归测试最好自动化第三关准备一个模拟真实用户请求的验收用例集把所有历史典型场景跑一遍。这三关过了才允许上线。虽然麻烦一点但比起线上翻车再修成本低多了。8. 我的体会技能化不只是技术更是产品思维整个agent-skills项目做下来我最大的感受是技能化体系的难点不在技术而在拆解业务的能力。技术方案有章可循——定义Schema、编写描述、实现逻辑、注册调度、编排容错每一步都有清晰的做法。真正考验人的是你有没有能力把复杂的业务需求拆成边界清晰、语义明确、可独立验证的技能单元。而这个拆解能力无法一次到位。我最初设计的技能粒度很粗一个处理订单技能包含了查单、改单、退款、物流查询等多种功能结果参数又长又多模型总是填不对。后来狠下心来拆成四五个独立技能每个技能的参数精简到了三四个整体准确率和稳定性都明显上来了。所以在技能设计上我给自己定了一条规矩一个技能只干一件事如果它需要超过4个参数才能工作请考虑拆分。这不是硬性标准但作为设计准入门槛能逼你去思考业务的最小有效单元是什么。另外还想强调一点技能体系要轻装上阵别一开始就追求大而全。我见过不少团队雄心勃勃要建几百个技能结果过了一个月维护不动全部废弃。技能应该跟着业务痛点长出来不要为了技能化而技能化。这个项目的经验和能力沉淀下来就是一套真正属于自己团队的数字生产力底座。工具会快速迭代模型会持续升级但用标准化技能让Agent可靠地干活这套方法会持续很长一段时间都不过时。你可以从一个小场景开始试着把一个高频功能拆成一个标准技能然后逐渐扩展。假以时日你会拥有一支由技能装配起来的、既可靠又灵活的智能体团队。
