智能体能力层设计指南：agent-skills 技能封装与编排实践

1. 从“agent-skills”这个标题说起：它到底在解决什么问题

第一次看到“agent-skills”这个标题，我脑子里蹦出来的第一个念头是：这大概率不是一个单纯的代码库，而是一套关于“能力封装”的方法论。为什么这么说？因为“agent”这个词在当下的技术语境里，早就从科幻电影里的拟人化角色，变成了一个非常具体的工程概念——它指的是一个能感知环境、做出决策、调用工具、完成任务的软件实体。而“skills”这个词，则直接指向了“能力”这个核心。

把这两个词拼在一起，意思就很明确了：如何给一个智能体（agent）赋予、管理、复用、组合它的各项技能。这听起来像是一个技术框架的名字，但我觉得它更像是一个工程问题的抽象。任何一个做过智能体开发的人都知道，最头疼的从来不是“让模型跑起来”，而是“让模型在正确的时候做正确的事”。模型本身是个黑盒，你给它输入，它给你输出，但中间那个“决定调用哪个工具、传什么参数、失败了怎么办”的过程，才是真正考验工程能力的地方。

所以，agent-skills 这个标题背后，我看到的是一套关于能力抽象层的设计思路。它要解决的问题很具体：当你的智能体需要处理的任务越来越复杂，从简单的问答变成多步骤的流程编排，从单一工具调用变成多工具协同，你不可能把所有的逻辑都写在一个巨大的提示词里。你需要把能力拆开，像搭积木一样，每个技能独立定义、独立测试、独立复用。这就是 agent-skills 最核心的价值主张。

这篇文章适合谁来读？我觉得有三类人。第一类是正在做智能体应用开发的工程师，你可能已经用过大模型 API，也写过一些工具调用的代码，但总觉得代码越写越乱，想找一个更结构化的方式来组织能力。第二类是对智能体架构感兴趣的产品经理或技术负责人，你想理解一个成熟的智能体系统内部是怎么分层的，为什么有些系统能稳定运行而有些一碰就碎。第三类是刚入门的技术爱好者，你可能还没写过智能体，但想从“能力设计”这个角度切入，理解这个领域的核心思维方式。

接下来的内容，我会从设计思路、核心细节、实操过程、常见问题四个维度，把 agent-skills 这个主题拆开揉碎。我不会只讲概念，而是会结合我自己的实践经验，告诉你哪些地方容易踩坑，哪些参数需要反复调试，哪些设计决策会直接影响系统的可维护性。你可以把这篇文章当成一份“智能体能力层设计指南”，读完之后，你应该能自己动手设计一套适合自己业务场景的 skills 体系。

2. 智能体能力层的整体设计与思路拆解

2.1 为什么要把“技能”从智能体里拆出来

先讲一个我自己的教训。早期做智能体的时候，我习惯把所有逻辑都塞进一个系统提示词里。比如“你是一个助手，你可以查天气、可以算数学、可以查数据库，当用户问天气的时候你要调用天气接口，当用户问数学的时候你要调用计算器……”一开始还挺好用，因为任务简单，模型能记住。但很快问题就来了：每加一个功能，提示词就长一截，模型开始混淆，有时候该调天气的时候它去调计算器，有时候两个都不调，直接编一个答案给你。更麻烦的是，你没法单独测试某个功能，因为所有逻辑都耦合在一起。

后来我意识到，问题的根源在于能力没有边界。在人类组织里，我们不会让一个人同时负责所有事情，而是会划分岗位、定义职责、明确接口。智能体也一样，它需要一个“能力层”来管理所有的技能。agent-skills 这个思路，本质上就是给智能体建立一套“岗位说明书”：每个技能有明确的输入输出、有独立的实现逻辑、有清晰的触发条件。智能体本身只负责一件事——根据当前上下文，决定调用哪个技能，然后把技能返回的结果整合成最终回答。

这样做的好处非常明显。第一是可测试性：每个技能可以单独写单元测试，输入什么、输出什么、边界条件是什么，一目了然。第二是可复用性：一个“查询订单状态”的技能，可以在客服场景用，也可以在售后场景用，不需要重复实现。第三是可维护性：当业务逻辑变化时，你只需要修改对应的技能，而不是去动那个巨大的提示词。第四是可观测性：你可以记录每个技能的调用次数、成功率、耗时，从而定位系统的瓶颈。

2.2 技能的定义：从“函数”到“能力单元”

在 agent-skills 的语境里，一个“技能”到底是什么？我的理解是：它是一个带有语义描述的可调用单元。这句话有点抽象，我拆开解释。

首先，它必须是“可调用的”。这意味着它有一个明确的入口，通常是一个函数或者一个 API 端点。你给它输入参数，它给你返回结果。这一点和普通的函数没有区别。

其次，它必须是“带有语义描述的”。这是和普通函数最大的区别。普通函数的文档是给人看的，而技能的描述是给模型看的。模型需要根据这个描述来判断：当前用户的问题，是否应该调用这个技能？如果调用，应该传什么参数？所以技能的描述必须包含几个关键要素：技能名称、功能说明、适用场景、参数列表（每个参数的类型、含义、是否必填）、返回值格式、可能的错误情况。这些信息会被嵌入到模型的提示词里，成为模型决策的依据。

最后，它必须是一个“单元”。这意味着它应该有清晰的边界，不应该依赖外部的隐式状态。一个技能应该尽可能做到“给定输入，就能确定输出”，这样才能保证可测试和可复用。当然，现实中有些技能确实需要访问数据库或外部服务，但至少它的接口应该是干净的，不应该把内部的实现细节暴露给调用方。

我习惯把技能分成三类。第一类是原子技能，比如“查询天气”“计算两个数的和”“发送邮件”，它们是最小的功能单元，通常只做一件事。第二类是组合技能，比如“处理退款申请”，它内部可能会调用“查询订单”“验证用户身份”“发起退款”等多个原子技能，对外只暴露一个简单的接口。第三类是元技能，比如“规划任务步骤”“反思上一步的结果”，它们不直接处理业务数据，而是用来控制智能体的行为。这三类技能在设计和管理上会有不同的侧重点，后面我会详细讲。

2.3 技能注册与发现：让智能体知道“自己能做什么”

有了技能的定义，下一个问题就是：智能体怎么知道有哪些技能可用？这就涉及到技能注册与发现的机制。

最简单的方式是静态注册：在系统启动的时候，把所有技能的描述加载到一个列表里，然后把这个列表拼接到系统提示词中。这种方式实现简单，适合技能数量不多（比如少于 20 个）的场景。但它的缺点也很明显：当技能数量增加时，提示词会变得非常长，不仅消耗 token，还会让模型难以聚焦。我试过在一个项目里注册了 50 多个技能，结果模型的选择准确率明显下降，因为它要在太多的选项里做判断。

更成熟的方式是动态发现：智能体先根据用户的问题，生成一个“技能检索”的查询，然后从一个技能库中检索出最相关的几个技能，再把它们注入到提示词中。这种方式可以支持大量的技能，而且能根据上下文动态调整。实现动态发现通常需要给每个技能建立一个向量索引，把技能的描述转换成嵌入向量，然后通过相似度检索来匹配。我在一个项目中用过这种方式，技能数量超过 100 个，检索的准确率依然能保持在可接受的水平。

还有一种折中的方式叫分层注册：把技能按照领域分组，比如“订单相关”“用户相关”“支付相关”，智能体先选择领域，再在领域内选择具体技能。这种方式适合技能数量中等、且领域划分清晰的场景。它的好处是减少了单次决策的复杂度，但需要额外维护领域分类的逻辑。

选择哪种方式，取决于你的技能数量和业务复杂度。我的经验是：技能少于 20 个，静态注册就够了；20 到 100 个，考虑分层注册；超过 100 个，动态发现是必须的。当然，这不是绝对的，还要看技能之间的相似度。如果技能之间差异很大，静态注册也能撑到 50 个左右；如果技能之间很相似，可能 10 个就需要动态发现了。

2.4 技能编排：从“单步调用”到“多步流程”

单个技能的调用相对简单，但真实场景往往需要多个技能协同完成。比如用户说“帮我查一下上个月的订单，然后把金额超过 500 的退款”，这就涉及“查询订单”“筛选金额”“发起退款”三个步骤。智能体需要决定：先调用哪个，再调用哪个，中间的结果怎么传递。

这就是技能编排要解决的问题。我见过几种不同的编排方式。

第一种是模型自主编排：把所有的技能描述给模型，让模型自己决定调用顺序。这种方式最灵活，但稳定性最差。模型可能会漏掉步骤，可能会重复调用，可能会在中间步骤失败后不知道怎么办。我在早期项目中用过这种方式，结果就是“演示很惊艳，上线很崩溃”。

第二种是预定义流程编排：把常见的多步流程写成一个组合技能，内部用代码固定调用顺序。这种方式稳定性最好，但灵活性差，只能处理预定义的场景。适合业务流程非常固定的场景，比如“退款申请”这种有明确步骤的操作。

第三种是混合编排：模型负责选择“用哪个流程”，流程内部用代码固定步骤。比如模型判断用户是要“退款”还是“查订单”，然后调用对应的组合技能。这种方式兼顾了灵活性和稳定性，是我目前最推荐的方式。

还有一种更高级的方式叫规划-执行分离：先用一个规划技能把用户的问题拆解成步骤列表，然后逐步执行，每执行一步可以重新规划。这种方式适合非常复杂的任务，但实现难度也最高。我在一个数据分析的项目中用过这种方式，效果不错，但需要仔细设计规划器的提示词和错误处理逻辑。

3. 核心细节解析与实操要点

3.1 技能描述怎么写才能让模型“看懂”

技能描述是模型决策的唯一依据，写得好不好直接决定系统的准确率。我踩过的坑是：一开始把技能描述写成了技术文档，比如“函数名：query_order，参数：user_id (string)，order_date (string)，返回：JSON 数组”。结果模型经常传错参数，或者在不该调用的时候调用。

后来我总结了一个原则：技能描述要写给模型看，而不是写给人看。具体来说，要包含以下几个部分。

第一是技能名称。名称要简洁、语义明确，最好用“动词+名词”的格式，比如“查询订单”“发送邮件”“计算折扣”。避免用缩写或内部代号，模型不认识。

第二是功能说明。用一两句话说明这个技能是做什么的，什么情况下应该使用它。这里的关键是“什么情况下使用”，因为模型需要根据场景来判断。比如“当用户询问订单状态、物流信息、预计送达时间时，使用此技能”。这样模型就知道触发条件了。

第三是参数说明。每个参数要说明类型、含义、是否必填、取值范围。如果参数有默认值，也要写清楚。我习惯用表格来组织参数说明，因为模型对表格的理解能力比纯文本好。

第四是返回值说明。说明返回的数据结构，包括字段名和含义。如果返回的是 JSON，最好给一个示例。这样模型知道怎么解析结果。

第五是错误处理。说明可能出现的错误情况，以及模型应该怎么应对。比如“如果查询不到订单，返回空数组，此时应该告知用户未找到相关订单”。

下面是一个我实际用过的技能描述模板，你可以参考：

技能名称：查询订单 功能说明：根据用户ID和日期范围查询订单列表。当用户询问订单状态、历史订单、订单金额时使用。 参数： - user_id (string, 必填)：用户唯一标识 - start_date (string, 可选)：开始日期，格式 YYYY-MM-DD，默认为 30 天前 - end_date (string, 可选)：结束日期，格式 YYYY-MM-DD，默认为今天 返回值：订单对象数组，每个对象包含 order_id, amount, status, created_at 字段 错误处理：如果 user_id 无效，返回错误码 400；如果查询超时，返回错误码 504，此时应提示用户稍后重试

这个模板看起来简单，但每一条都是经过反复调试才确定下来的。比如“默认为 30 天前”这个细节，是因为模型经常不传日期参数，如果不给默认值，技能就会报错。再比如“错误处理”那一段，是因为模型在遇到错误时，如果没有明确的指引，就会自己编一个答案，而不是如实告知用户。

3.2 参数校验：别让模型传“脏数据”

模型传参数这件事，永远不要假设它会传对。我见过模型把日期格式写成“2024年1月1日”，把数字写成字符串“500”，把布尔值写成“是”。所以参数校验是必须的，而且要在技能内部做，不能依赖模型自己纠正。

我的做法是在每个技能入口处加一层校验逻辑。对于字符串参数，检查长度和格式；对于数字参数，检查类型和范围；对于日期参数，尝试解析并统一格式。如果校验失败，返回一个明确的错误信息，告诉模型“参数格式错误，日期应该是 YYYY-MM-DD 格式”。这样模型在下一轮对话中就有机会纠正。

还有一个技巧是参数归一化。比如用户说“上个月”，模型可能会传“last_month”，也可能会传“2024-03”。我在技能内部写了一个归一化函数，把常见的自然语言日期表达转换成标准格式。这样即使模型传得不那么精确，技能也能正确处理。

注意：参数校验的错误信息要写得足够具体，让模型知道怎么改。不要只写“参数错误”，而要写“start_date 格式错误，应为 YYYY-MM-DD，例如 2024-01-01”。

3.3 技能粒度怎么把握：太粗还是太细

技能粒度是一个很容易走极端的问题。太粗了，一个技能做太多事，内部逻辑复杂，难以复用；太细了，技能数量爆炸，模型选择困难，调用链太长。

我的经验法则是：一个技能只做一件事，但这件事要有业务意义。什么意思？比如“查询订单”是一个合理的粒度，因为它对应一个完整的业务动作。但“连接数据库”就不是一个合理的技能，因为它太底层了，没有业务语义。反过来，“处理退款”可能太粗了，因为它内部包含了查询、验证、退款多个步骤，应该拆成组合技能。

具体怎么判断？我通常问自己三个问题。第一，这个技能能否用一句话描述清楚？如果不能，说明太粗了。第二，这个技能是否会被多个场景复用？如果只会被一个场景用到，可能不需要单独拆出来。第三，这个技能的输入输出是否清晰？如果输入参数超过 5 个，或者返回值结构很复杂，可能需要拆分。

还有一个实用的技巧：先粗后细。一开始不要把粒度定得太细，先按业务动作划分，等系统跑起来之后，观察哪些技能经常被一起调用，哪些技能内部逻辑越来越复杂，然后再考虑拆分。我在一个项目中一开始把“用户认证”和“权限检查”放在一个技能里，后来发现权限检查的逻辑越来越复杂，就拆成了两个独立的技能。

3.4 错误处理与重试：让智能体“优雅地失败”

技能调用失败是常态，不是异常。网络超时、接口限流、数据不存在，这些都会发生。关键是怎么处理。

我的原则是：技能内部处理可恢复的错误，技能外部处理不可恢复的错误。什么意思？比如网络超时，技能内部可以自动重试 2 到 3 次，如果还是失败，再返回错误给智能体。而像“用户不存在”这种错误，重试没有意义，直接返回错误，让智能体决定怎么回复用户。

重试策略也有讲究。我通常用指数退避：第一次失败后等 1 秒，第二次等 2 秒，第三次等 4 秒。这样可以避免在服务端压力大的时候雪上加霜。重试次数不要太多，3 次足够了，再多会拖长响应时间。

还有一个细节是错误信息的结构化。技能返回的错误不应该是一个简单的字符串，而应该是一个包含错误码、错误描述、是否可重试的对象。这样智能体可以根据错误码来决定下一步动作。比如错误码 429 表示限流，智能体可以告诉用户“当前请求过多，请稍后再试”；错误码 404 表示资源不存在，智能体可以告诉用户“未找到相关信息”。

提示：在技能描述里明确写出错误码的含义和应对方式，这样模型在遇到错误时不会慌，而是按照预设的逻辑处理。

4. 实操过程与核心环节实现

4.1 环境准备与基础框架搭建

假设你现在要从零开始搭建一套 agent-skills 体系，我会建议你按下面的步骤来。首先明确技术栈：我习惯用 Python 作为开发语言，因为生态成熟，调试方便。核心依赖包括一个大模型 API（用于决策）、一个 Web 框架（用于暴露技能接口，比如 FastAPI）、一个向量数据库（如果要做动态发现，比如 Chroma 或 FAISS）。如果你只是做原型验证，可以先用静态注册，不需要向量数据库。

第一步是定义技能的基础数据结构。我通常会定义一个 Skill 类，包含以下字段：name（技能名称）、description（功能说明）、parameters（参数列表）、handler（实际执行的函数）、error_handling（错误处理逻辑）。这个类是所有技能的基类，每个具体技能继承它并实现 handler 方法。

第二步是搭建技能注册中心。这是一个简单的字典或者列表，用来存储所有已注册的技能。我习惯用一个 SkillRegistry 类来管理，提供 register、get、list_all 等方法。注册的时候可以加一些元数据，比如技能分类、版本号、作者，方便后续管理。

第三步是写一个技能调用的统一入口。这个入口接收技能名称和参数，负责参数校验、调用 handler、捕获异常、记录日志。所有技能调用都走这个入口，这样可以统一处理日志、监控、限流等横切关注点。

第四步是集成大模型。把技能注册中心里的技能描述转换成提示词的一部分，然后调用大模型 API，解析模型的输出，判断它要调用哪个技能、传什么参数。这一步是整个系统的核心，也是最容易出问题的地方。我建议先用一个简单的场景测试，比如只注册两个技能，看模型能不能正确选择。

4.2 一个完整技能的实现示例

下面我用“查询天气”这个技能来演示完整的实现过程。虽然这个例子很简单，但麻雀虽小五脏俱全，你可以把它当成模板来套用。

首先是技能定义：

class WeatherSkill(Skill): name = "查询天气" description = "根据城市名称查询当前天气。当用户询问天气、气温、是否下雨时使用。" parameters = [ {"name": "city", "type": "string", "required": True, "description": "城市名称，如北京、上海"}, {"name": "date", "type": "string", "required": False, "description": "日期，格式 YYYY-MM-DD，默认为今天"} ] def handler(self, city, date=None): # 参数校验 if not city or not isinstance(city, str): return {"error": "INVALID_CITY", "message": "城市名称不能为空"} if date: try: datetime.strptime(date, "%Y-%m-%d") except ValueError: return {"error": "INVALID_DATE", "message": "日期格式应为 YYYY-MM-DD"} # 调用外部天气 API try: result = weather_api.query(city, date) return {"success": True, "data": result} except TimeoutError: return {"error": "TIMEOUT", "message": "天气服务超时，请稍后重试", "retryable": True} except Exception as e: return {"error": "UNKNOWN", "message": str(e), "retryable": False}

然后是注册：

registry = SkillRegistry() registry.register(WeatherSkill())

接着是调用入口：

def invoke_skill(skill_name, params): skill = registry.get(skill_name) if not skill: return {"error": "SKILL_NOT_FOUND", "message": f"技能 {skill_name} 不存在"} # 参数校验 validated_params = validate_params(skill.parameters, params) if validated_params.get("error"): return validated_params # 调用 handler try: result = skill.handler(**validated_params) log_skill_call(skill_name, params, result) return result except Exception as e: log_skill_error(skill_name, params, e) return {"error": "EXECUTION_ERROR", "message": str(e)}

最后是集成到智能体循环中：

def agent_loop(user_input): # 构建提示词 prompt = build_prompt(user_input, registry.list_all()) # 调用大模型 response = llm.generate(prompt) # 解析模型输出 if response.has_skill_call(): skill_name = response.skill_name params = response.params result = invoke_skill(skill_name, params) # 把结果返回给模型，生成最终回答 final_response = llm.generate(build_final_prompt(user_input, result)) return final_response else: return response.text

这个流程看起来简单，但每个环节都有细节。比如build_prompt函数要把技能描述格式化成模型能理解的格式，validate_params要处理类型转换和默认值，log_skill_call要记录足够的上下文用于排查问题。这些细节决定了系统的稳定性。

4.3 技能编排的代码实现

单个技能跑通之后，下一步就是多技能编排。我以“查询订单并退款”这个场景为例，演示组合技能的实现。

首先定义一个组合技能：

class RefundOrderSkill(Skill): name = "订单退款" description = "查询用户订单并针对指定订单发起退款。当用户要求退款、退货时使用。" parameters = [ {"name": "user_id", "type": "string", "required": True}, {"name": "order_id", "type": "string", "required": False, "description": "订单号，如果不传则查询最近订单"}, {"name": "reason", "type": "string", "required": False, "description": "退款原因"} ] def handler(self, user_id, order_id=None, reason=None): # 第一步：查询订单 if not order_id: orders = invoke_skill("查询订单", {"user_id": user_id}) if orders.get("error"): return orders if not orders["data"]: return {"error": "NO_ORDER", "message": "未找到可退款的订单"} order_id = orders["data"][0]["order_id"] # 第二步：验证订单状态 order = invoke_skill("查询订单详情", {"order_id": order_id}) if order.get("error"): return order if order["data"]["status"] != "已支付": return {"error": "INVALID_STATUS", "message": "该订单当前状态不支持退款"} # 第三步：发起退款 refund_result = invoke_skill("发起退款", { "order_id": order_id, "amount": order["data"]["amount"], "reason": reason or "用户申请" }) return refund_result

这个组合技能内部调用了三个原子技能，对外只暴露一个简单的接口。智能体只需要决定“是否调用订单退款技能”，不需要关心内部的步骤。这样做的好处是：如果退款流程变化了，只需要修改这个组合技能，不需要改智能体的提示词。

注意：组合技能内部的调用也要走统一的 invoke_skill 入口，这样才能保证日志、监控、错误处理的一致性。不要直接调用 handler，否则会绕过校验和日志。

4.4 技能监控与迭代优化

系统上线之后，监控是必不可少的。我通常会记录以下几个指标：每个技能的调用次数、成功率、平均耗时、错误分布。这些数据可以帮助你发现很多问题。

比如，如果某个技能的调用次数异常高，可能是模型过度调用了它，需要检查技能描述是否写得太宽泛。如果某个技能的成功率很低，可能是外部依赖不稳定，需要加重试或降级策略。如果某个技能的耗时很长，可能是内部逻辑需要优化，或者需要加缓存。

我还会定期分析“技能调用序列”，看看模型是否经常走一些奇怪的路径。比如用户问“天气”，模型先调了“查询订单”，再调了“查询天气”，这就是明显的误调用，需要调整技能描述或提示词。

迭代优化的另一个重要手段是收集失败案例。每次技能调用失败，我都会把上下文记录下来，包括用户输入、模型输出、技能参数、错误信息。然后定期 review 这些案例，找出共性问题。我统计过，80% 的失败集中在 20% 的技能上，把这些技能优化好，整体成功率就能大幅提升。

5. 常见问题与排查技巧实录

5.1 模型不调用技能，直接编答案

这是最常见的问题。用户问“今天天气怎么样”，模型不调用天气技能，而是直接编一个“今天晴天，25度”。原因通常是技能描述不够明确，模型觉得“这个问题我能直接回答”。

排查思路：先检查技能描述里有没有明确写出触发条件。比如“当用户询问天气时使用”这句话，模型可能理解成“当用户明确说‘查询天气’时才使用”。改成“当用户询问任何与天气、气温、降水、风力相关的问题时使用”，覆盖范围就广了。

另一个原因是提示词里没有强调“必须调用技能”。我习惯在系统提示词里加一句：“对于需要实时数据或外部信息的问题，必须调用相应技能，不得自行编造答案。”这句话能显著降低编答案的概率。

还有一个技巧是少样本示例。在提示词里给一两个“用户问天气 -> 调用天气技能”的示例，模型会更容易模仿。示例不用多，一两个就够了，太多会占用 token。

5.2 模型调用了错误的技能

用户问“订单什么时候到”，模型调用了“查询天气”技能。这种错误通常是因为技能之间的描述有重叠，或者模型对用户意图的理解有偏差。

排查思路：先看两个技能的描述是否有相似的触发词。比如“查询订单”的描述里如果写了“查询订单状态、物流信息”，而“查询天气”的描述里写了“查询信息”，模型就可能混淆。解决方法是让每个技能的描述尽可能独特，避免使用过于宽泛的词汇。

另一个原因是技能数量太多，模型的选择空间太大。这时候可以考虑分层注册或动态发现，减少单次决策的选项数量。

还有一个容易被忽略的点是参数名称。如果两个技能都有date参数，模型可能会把日期传给错误的技能。我习惯给参数加前缀，比如order_date、weather_date，这样即使模型选错了技能，参数校验也能拦住。

5.3 技能调用参数错误

模型传的参数格式不对，比如日期写成“明天”，数字写成“五百”。这种问题很难完全避免，但可以通过几个手段降低概率。

第一是在技能描述里给出参数示例。比如“date: 日期，格式 YYYY-MM-DD，例如 2024-01-01”。模型看到示例，传错的概率会降低。

第二是在参数校验里做归一化。比如把“明天”转换成具体日期，把“五百”转换成 500。我写过一个normalize_params函数，处理常见的自然语言表达。

第三是在错误信息里给出纠正指引。比如“日期格式错误，应为 YYYY-MM-DD，您传入的是‘明天’，请转换为具体日期”。模型看到这个错误，下一轮通常会纠正。

5.4 技能调用超时或失败

外部服务不稳定是常态。我的处理策略是：能重试的重试，不能重试的降级，降级不了的如实告知。

重试策略前面讲过，指数退避，最多 3 次。降级策略是指：如果天气服务挂了，可以返回一个缓存的历史数据，或者返回一个“暂时无法获取天气信息”的提示。如实告知是指：如果既不能重试也不能降级，就明确告诉用户“当前服务不可用，请稍后重试”，而不是编一个答案。

还有一个技巧是设置超时时间。每个技能调用都应该有超时限制，比如 5 秒。超过 5 秒就放弃，返回超时错误。这样可以避免一个慢技能拖垮整个系统。

5.5 常见问题速查表

5.6 几个我踩过的坑和独家技巧

第一个坑是技能描述里的“等”字。我写过“查询订单、物流等信息”，结果模型把“等信息”理解成“所有信息”，经常在不该调用的时候调用。后来我把“等”字去掉了，改成穷举式的描述，准确率明显提升。

第二个坑是参数默认值。我一开始没给参数设默认值，结果模型经常不传可选参数，技能就报错。后来我给所有可选参数都设了默认值，并且在描述里写明“默认为 XXX”，问题就解决了。

第三个技巧是用技能名称做前缀。我在日志里给每个技能调用加了一个唯一 ID，格式是“技能名-时间戳-随机数”。这样排查问题时，可以快速定位到某一次具体的调用，查看完整的输入输出。

第四个技巧是定期清理无用技能。系统跑久了，会积累一些从来不被调用的技能。这些技能不仅占用提示词空间，还会干扰模型的选择。我每隔一段时间就会分析技能调用日志，把调用次数为 0 的技能下线。

第五个技巧是给技能打标签。我在技能注册的时候会加一些标签，比如“高频”“低频”“外部依赖”“内部计算”。这样在监控和优化的时候，可以按标签筛选，快速定位问题。

6. 技能体系的扩展与演进方向

6.1 从静态技能到动态生成

目前大部分 agent-skills 体系都是静态的：技能在开发时定义好，运行时只能选择，不能创建。但我在一些实验性项目中尝试过动态生成技能：让模型根据用户的需求，现场生成一个技能的代码，然后注册到系统中。这种方式非常强大，但也非常危险，因为模型生成的代码可能有 bug，甚至可能有安全风险。

我的做法是加一层沙箱执行：模型生成的技能代码在一个隔离的环境中运行，只能访问有限的资源，不能执行危险操作。同时加一层人工审核：生成的技能需要经过审核才能正式注册。这种方式适合内部工具场景，不适合直接面向用户的场景。

6.2 技能之间的依赖管理

当技能数量增多时，技能之间会出现依赖关系。比如“订单退款”依赖“查询订单”和“发起退款”。如果“查询订单”挂了，“订单退款”也会失败。这就需要一套依赖管理机制。

我通常会在技能注册的时候声明依赖关系，然后在调用时检查依赖是否可用。如果依赖不可用，可以选择降级（比如用缓存数据）或者直接返回错误。更高级的做法是依赖注入：组合技能不直接调用原子技能，而是通过一个依赖容器来获取，这样可以方便地替换实现或加 mock。

6.3 技能版本管理与灰度发布

技能也会迭代，新版本可能不兼容旧版本。我习惯给每个技能加版本号，比如“查询订单 v1”“查询订单 v2”。智能体可以选择调用哪个版本，或者根据用户群体灰度发布。

灰度发布的实现方式是：在技能注册中心里，同一个技能名称可以注册多个版本，每个版本有一个流量比例。调用的时候根据比例随机选择版本。这样可以先让小部分用户试用新版本，观察稳定性后再全量。

6.4 技能市场的可能性

如果技能定义足够标准化，理论上可以建立一个“技能市场”：不同的开发者贡献技能，智能体按需订阅。这在一些开源社区已经有一些雏形。但我觉得最大的挑战不是技术，而是信任和质量控制：你怎么知道一个第三方技能是安全的、可靠的、符合预期的？

我的设想是加一层技能认证：技能需要经过测试、审核、评级，才能进入市场。智能体可以选择只使用高评级的技能。同时加一层运行时监控：如果某个技能的错误率超过阈值，自动下线。这些机制需要一套完整的基础设施来支撑，目前还在探索阶段。

7. 我个人的一些实践体会

做智能体能力层设计这几年，我最大的体会是：技能设计本质上是一个“翻译”工作。你要把人类的业务逻辑，翻译成模型能理解的技能描述；你要把模型的自然语言输出，翻译成结构化的技能调用；你要把技能的执行结果，翻译成用户能理解的回答。这个翻译过程做得好不好，直接决定系统的体验。

另一个体会是：不要追求一步到位。我见过很多团队一开始就想设计一个完美的技能体系，结果花了几个月还没上线。我的建议是先用最粗糙的方式跑起来，哪怕只有两三个技能，哪怕描述写得很烂。跑起来之后，你才能看到真实的问题，才能有针对性地优化。技能体系是迭代出来的，不是设计出来的。

还有一个体会是：监控比功能更重要。一个功能再强大，如果不知道它什么时候会失败、为什么失败，那就是一个定时炸弹。我宁愿少做一个功能，也要把监控和日志做扎实。每次技能调用都要有记录，每个错误都要有上下文，这样才能快速定位和修复问题。

最后分享一个小技巧：定期做“技能审计”。每隔一个月，把所有的技能调用日志拉出来，看看哪些技能从来没被调用过，哪些技能的错误率异常高，哪些技能的描述和实际行为不一致。这个审计过程往往能发现很多隐藏的问题，也能帮你决定下一步优化什么。

这个方向后续还可以这样扩展：把技能体系和评估体系结合起来，每次技能调用都自动打分，用评分来驱动技能的迭代。或者把技能体系和用户反馈结合起来，让用户对技能的执行结果进行评价，用反馈来优化技能描述。这些方向我都还在探索中，有机会再单独写一篇来聊。