Agent技能化实战：从参数Schema设计到可插拔技能编排

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 常见参数错误及对策

下面这几个问题，是我在实战中反复遇到的，几乎每一个都坑过我的项目，整理成表格供大家对照参考。

这里特别说一下"枚举限定"。有些技能的状态字段，比如订单状态、工单进度，本身是可枚举的。如果你不列出来，模型就会自由发挥。我在内部项目里曾经因为订单状态枚举没写全，导致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.py

5.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_ascii=False) except ValueError as e: return json.dumps({"status": "error", "message": str(e)}, ensure_ascii=False) except Exception as e: # 兜底异常处理，避免把未处理异常抛给Agent return json.dumps({"status": "error", "message": f"系统异常：{str(e)}"}, ensure_ascii=False)

执行模块的设计有几个细节值得注意。第一，参数校验必须独立在前，不能让脏数据进到核心查询逻辑；第二，所有返回值统一是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可靠地干活"这套方法，会持续很长一段时间都不过时。你可以从一个小场景开始，试着把一个高频功能拆成一个标准技能，然后逐渐扩展。假以时日，你会拥有一支由技能装配起来的、既可靠又灵活的智能体团队。