agent-skills：把智能体能力拆成可复用的“技能包”，这次我把整套设计思路撸清楚了
做智能体开发的朋友应该都有这种感觉：项目一过某个规模，原本顺手的 agent 代码就开始失控。要么是 system prompt 越堆越长，要么是工具函数散落在各个文件里，明明很多任务用的都是同一套能力，却被反复复制粘贴。我最近在做一个偏自动化的 agent 项目，核心需求是让模型不仅能聊天，还能按需调用外部工具、操作数据、跑完整的多步流程，于是认真把“agent-skills”这套思路重新整理了一遍——简单说，就是把智能体单次任务中的能力拆成独立、可描述、可复用、可组合的技能模块，再像搭积木一样按需注册和编排。
这篇文章不聊花哨的概念，直接从项目里摸出来的设计思路和踩坑记录讲起。适合正在开发 agent 功能、或者想把自己手里那堆“只会一问一答”的机器人升级成能干实事的读者。我会把技能的定义、结构、注册机制、组合编排和排查过程都完整拆开，尽量让你看完就能在自己的项目里动手落地。
1. 项目整体思路：为什么要把技能从智能体里拆出来
1.1 技能不等于“提示词模板”
很多人第一次听到“agent skills”，第一反应是：这不就是给 prompt 里加一段描述吗？确实，早期智能体能力扩展主要靠往 system prompt 里堆文字，比如“当用户要查天气时，请调用天气接口”。但在真实任务里，这种方式很快就撑不住了。
我试过在一个偏客服场景的 agent 里用纯 prompt 描述十几个工具。效果是：模型经常漏调用、参数传错、甚至编造工具返回值。因为 prompt 本质上是在“期望模型自觉遵守协议”，而不是在工程上“约束模型必须走某条路径”。技能的思路完全不同——它把能力封装成带元信息、带参数约束、带回调逻辑的代码模块，模型通过明确的触发机制调用技能，就像调用函数一样，而不是靠“读说明书然后自由发挥”。
所以我在这个项目里对技能的定义是：一个最小的、可被智能体主动触发的任务执行单元。它包含三样东西：技能说明（让模型知道什么时候该用）、入参出参（让模型知道怎么用）、执行逻辑（真正去做事的那段代码）。三者缺一不可。
技能和普通函数的最大区别在于“主动性”。普通函数是程序流程里写死的，模型决定不了调用时机；技能则是把调用权交给了模型——模型根据自己的推理判断当前任务需要哪个技能，然后以结构化参数发起调用，拿到结果后继续推理。这层交互方式的转变，才是“skill”和“function”的本质差异。
1.2 一个技能模块应该长什么样
我在项目里给技能设计了一套统一结构，每个技能对外暴露四段信息：
- 技能名称：短横线风格的唯一标识，比如
search_web、calendar_create_event。 - 功能描述：用一段不超过三句话的话说明“这个技能解决什么问题、在什么场景下触发、有什么注意事项”。这直接决定模型能不能在关键时刻想起它。
- 参数列表：每个参数的名称、类型、是否必填、取值范围、示例值，尽量给全，减少模型的猜测成本。
- 执行函数：接收参数、执行任务、返回结构化结果的实际代码。
我自己的体会是：这个结构里最容易偷懒的是“功能描述”，但恰恰它是后续 everything 的地基。同一个技能，描述写成“搜索互联网信息”和写成“当用户询问实时新闻、特定事实或需要最新资料时，使用此技能执行网络搜索。请将查询词尽量拆短”效果天差地别。后者给了模型明确的触发条件和参数构造建议，调用准确率能提升一个量级。
2. 技能库的核心结构设计与拆解
2.1 技能的元信息与命名规范
技能数量一多，混乱就从命名开始。我第一版技能库里出现过web_search、searchOnline、search_web_v2这种惨不忍睹的命名并存情况，模型经常找不到正确的那个。后来我定了一套硬性规范：
- 一律小写，单词间用下划线连接，动词开头，比如
create_todo、fetch_stock_quote。 - 一个技能只做一件事，名称和职责严格一致。如果发现技能描述里出现“以及”“同时”这类词，说明职责太杂，要拆。
- 命名时考虑“模型视角”。模型不是看你代码里的人名，而是看技能名+描述的语义关联。
summarize_doc和doc_summarizer_tool让模型选，前者触发准确率明显更高，因为动词结构更符合自然语言习惯。
关于元信息，我还给每个技能加了三个字段：version（版本号）、author（维护人）、tags（标签分类，比如“数据获取”“日程管理”“文本处理”）。tags 在技能数量超过二十个以后非常有用，可以配合路由逻辑做初筛——先按标签缩小候选范围，再把候选技能的描述交给模型做精确选择，既省 token 又提升准确率。
2.2 技能内的变量、引用与结果返回
技能内部要能保存状态、引用外部资源、把处理结果传给下一步动作，所以我在实现时给每个技能定义了三个内部槽位：
- 输入槽：接收模型传来的结构化参数。这里有个容易被忽略的地方——模型输出的参数可能是字符串形式的数字或 JSON 字符串，技能执行前要有严格的 parse 和类型强转逻辑，最好对必填参数做显式校验，缺失时返回清晰错误信息而不是直接崩溃。
- 上下文槽：存放技能依赖的全局信息。比如一个
send_email技能，没有必要让模型每次传一遍 SMTP 地址、发件人身份，这些应该从上下文槽里自动带入。 - 输出槽：统一返回一个 JSON 对象，至少包含
success布尔值、data数据区和error错误信息区。这个输出会重新喂给模型，作为下一轮推理的上下文之一。
输出格式的统一非常重要。如果有的技能返回纯字符串、有的返回列表、有的返回 Java 风格的 map，模型的解析成本就上去了，后续编排也会被各种格式兼容问题拖死。项目跑起来之后我就后悔没在一开始统一规范——后期重构时改了几十处调用关系，那叫一个酸爽。
2.3 技能的粒度怎么定才算合适
这是设计技能库时最大的哲学问题：一个技能应该多“大”？
按我自己的经验，有两条判断标准。第一条：一个技能应该承载一个“有明确完成标志”的任务。比如“查询明天天气”算一个，“写一篇 800 字文章”也算一个——但“处理用户输入的所有可能情况”就不算，因为它没有明确终点。第二条：技能的粒度跟随复用频率。如果一个能力被三个以上业务流程用到，它就该独立成技能；如果只在一个流程里出现，可以先做成流程内部步骤，不要急着抽出来。
另外补充一个反常识的观察：粒度太小也不是好事。我把某个函数拆成get_order_info、get_order_status、get_order_items三个技能之后，模型的调用次数暴增，而且经常同时调用三个技能来拼凑信息，token 消耗翻倍，准确率反而下降。后来合并成一个get_order_details技能，加上一个detail_types参数，问题才解决。所以不要把“技能”当成“函数级”抽象，它更接近“任务级”抽象。
3. 技能注册与调用的完整实现
3.1 注册中心与加载流程
技能不能散落在代码里“随用随调”，那样编排逻辑会乱成一团麻。我在项目里维护了一个技能注册中心，本质就是一个全局字典：技能名称到技能对象的映射。每个技能对象包含前面说的四段信息，并提供统一的execute(params, context)入口。
加载流程是这样的：
- 项目启动时，扫描指定目录下所有技能定义文件。
- 每个技能模块声明自己的元信息，注册中心读取后写入索引。
- 注册中心维护两份结构：一份是“名称到对象”的字典，供程序内确定性调用；一份是“描述列表”，供模型推理时的候选技能检索。
- 调用时走统一的 execute 入口，内部再分发到具体实现。
之所以不直接把技能函数列表扔给模型，是因为“调用技能”是一个有状态的过程——模型先决定调用哪个技能，然后传参数，然后等待结果，然后决定要不要继续调用。注册中心天然支持这种多轮交互，而直接传函数引用往往会把“技能调用”降级成“一次性函数调用”，失去 agent 的决策能力。
提示：注册中心的数据结构务必加上技能状态标记。比如
enabled开关、deprecated弃用标记。我遇到过模型偏爱调用一个已废弃的技能，因为它描述写得最诱人——后来给废弃技能加了“此技能已停止服务，请使用 xxx 替代”的说明，错误才收敛。
3.2 一个真实的搜索辅助技能示例
这里给一个我实际用过的例子，做一个简化版的网络搜索技能：
# skills/web_search.py from dataclasses import dataclass, field from typing import Optional @dataclass class WebSearchSkill: name: str = "web_search" description: str = ( "当用户需要实时信息、最新新闻、特定事实查询或网络资料时，" "使用此技能执行搜索。把查询词拆成简短关键词，不要长句。" "若首次结果不佳，可调整 query 后再次调用。" ) version: str = "1.2.0" tags: list = field(default_factory=lambda: ["data_fetch", "search"]) parameters: dict = field(default_factory=lambda: { "query": { "type": "string", "required": True, "description": "搜索关键词，尽量简短", "example": "2025 年新款手机评测" }, "limit": { "type": "integer", "required": False, "description": "返回结果条数，默认5", "default": 5 } }) def execute(self, params: dict, context: dict) -> dict: query = params.get("query", "").strip() if not query: return {"success": False, "error": "query参数不能为空", "data": None} limit = int(params.get("limit", 5)) if limit < 1 or limit > 20: limit = 5 # 这里替换成实际的搜索API调用 raw_results = self._call_search_api(query, limit) return { "success": True, "data": { "query": query, "count": len(raw_results), "results": raw_results }, "error": None } def _call_search_api(self, query: str, limit: int): # 模拟API调用，真实项目中替换为外部服务 return [ {"title": f"示例结果{i}", "url": f"https://example.com/{i}", "snippet": f"关于{query}的第{i}条摘要"} for i in range(limit) ]这个例子看起来简单，但有三个细节值得留意。第一是description里写了“拆成短词”“可再次调用”这些执行建议，这不是废话，是在主动影响模型的行为模式。第二个是参数里的example字段，很多技能库都不提供示例值，但模型在构造参数时有一个明显的“示例锚定”效应——给一个高质量示例，参数构造的准确率显著提升。第三是返回值里success和error字段齐全，方便后续编排逻辑做条件判断，而不是依赖异常机制来传递业务错误。
3.3 技能注册的代码接入
技能模块写好之后，注册只需要一行声明：
# registry.py skills_registry = {} def register(cls): instance = cls() skills_registry[instance.name] = instance return cls @register class WebSearchSkill: # ... 同上启动时扫描目录：
import pkgutil, importlib def load_skills(package_name: str): for mod_info in pkgutil.iter_modules(importlib.import_module(package_name).__path__): importlib.import_module(f"{package_name}.{mod_info.name}")这段代码的核心思路是：技能模块通过 import 副作用完成自我注册。只要模块被加载，技能就自动进注册中心。新增技能不需要改造主程序逻辑，只加一个文件。实测下来，这种插件式架构在技能规模膨胀到几十个的时候依然能保持主程序稳定，值得推荐。
4. 技能组合与多步任务编排
4.1 顺序组合：把技能当成积木块
单个技能只能处理单原子操作，真实任务往往是“搜索→提取→整理→输出”这种多步链路。我在项目里处理组合问题时，没有引入过于复杂的工作流引擎，而是用了两种轻量手段。
第一种是模型自主编排。把可用技能列表描述喂给模型，让它自己决定调用顺序和次数。这是最灵活的方式，但也是最不可控的。实际经验是：模型在分支超过三个之后会出现“决策抖动”，时而漏步骤时而重复执行。所以这种方法只适用于分支少、容错高的场景。
第二种是流程模板编排。为高频任务预设步骤序列，每个步骤绑定一个技能和参数映射规则，模型只负责填充参数，不负责决定顺序。比如“周报生成”流程，固定为fetch_events→collect_metrics→summarize_text→render_markdown四步，每一步的输入输出通过上下文槽周转。这种方式稳定性高、容易调试，代价是灵活性下降，遇到模板覆盖不了的场景需要人工介入。
我目前的策略是两者结合：主干流程用模板，分支细节上放权给模型。比如周报流程是模板，但“本周重点”这种开放性问题允许模型临时调用search_web补充背景资料。这种混合模式在真实项目里平衡了可控性和灵活性，也避免了两边的短板。
4.2 多技能之间的数据传递
技能组合的核心难点不是调用顺序，而是数据怎么在技能之间流转。我踩过的最大一个坑是：技能 A 的返回值直接作为技能 B 的输入参数，一旦格式不完全匹配，整条链路就断。
解决方案是引入字段映射层。每个技能在定义参数时，不是只写参数名，而是一并声明“这个参数可以从上游哪个输出字段取值”。比如流程模板里：
flow = [ {"skill": "web_search", "args": {"query": "{user_query}"}, "output_as": "search_results"}, {"skill": "summarize_text", "args": {"text": "{search_results.data.results[0].snippet}"}, "output_as": "summary"} ]这里的{user_query}、{search_results.data...}是占位符，运行时从全局上下文槽里按路径取值。这样数据传递变成了显式声明，而不是靠技能实现里的隐式逻辑。排查问题的时候，看流程模板就能知道哪个数据从哪来、到哪里去，能少掉不少头发。
4.3 条件分支和回退处理
真实业务里经常出现“根据上游结果决定下一步”的情况。我用了极简的分支语法：每个流程步骤允许定义on_success和on_failure两种后续动作。on_success指向下一步骤；on_failure指向一个兜底技能，比如“返回错误信息给用户”或者“换个查询词重试”。
需要注意：回退不能无脑重试。我给重试技能设了次数上限，超过三次就人工介入。曾经出现过一次线上事故：某个搜索技能因为外部服务故障持续返回异常，模型触发重试逻辑，同一个错误查询被连续执行了十几次，不仅浪费 token，还差点打爆外部接口配额。后来加了“重试次数隔离”和“单技能熔断”——某个技能失败超过阈值后直接从候选列表摘除，模型在当轮对话中就无法再选择它。
5. 实际开发中的常见问题与排查技巧实录
5.1 高频踩坑清单：模型不调用、参数乱传、结果乱用
问题一：技能明明存在，模型就是不用
这个问题的根源几乎都是描述不够清晰或者触发场景描述缺失。我见过自己的一个get_current_time技能，描述只写了“获取当前时间”——结果用户问“现在几点”的时候，模型宁可盲猜也不调用它。后来把描述改成“当用户询问当前日期、时间、星期几或需要基于时间做判断时，调用此技能获取权威时间数据”，触发准确率从不到 40% 飙升到 90% 以上。关键是：描述里必须写清楚“什么时候该用它”，而不是“它有什么用”。
问题二：参数永远传不对
排查这个问题的顺序我建议是：先查参数描述里有没有给示例，再查参数名是不是和模型习惯的用语差距太大，最后查有没有做类型转换兜底。前两项属于“提示工程”范畴，第三项属于“工程健壮性”范畴。我遇到比较典型的是：技能参数定义要求limit是 integer，模型却传了字符串"5"。我在 execute 里做了int(params.get("limit", 5))这种强转，问题就消失了。核心原则是：不要相信模型会完全按 JSON Schema 传参，要在技能内部做宽容处理。
问题三：模型拿到结果后不会用
这类问题通常表现为：结果都返回了，明明里面有需要的数据，模型的最终回答还是泛泛而谈。我试过把输出槽的数据做得更结构化，比如把关键信息提取成字段而不是塞进长文本，模型的使用率会高很多。另一个实用技巧：在技能的 description 里末尾加一句“返回结果中，data.results 数组的第一项通常是最相关的”。模型读到这个提示后，会优先引用列表第一项，回答质量提升明显。
5.2 调试技能调用的三个实用手段
手段一：日志打点
技能执行要留痕。我在每个技能的execute入口和出口打日志，记录：调用时间、传入参数、返回结果摘要、耗时。日志格式统一用[SKILL]name=xxx params=xxx result_summary=xxx。技能多的时候，没有一个可检索的日志流，线上排查就是大海捞针。
手段二：调用轨迹回放
模型调用技能的轨迹应该做成可回放的数据结构，每一步记录“模型思考依据（如果能拿到）→调用了哪个技能→传了什么参数→拿到了什么结果→下一步决策”。我在项目里把这个轨迹存成了 JSON 数组，出问题时直接翻轨迹，比看一堆零散日志高效得多。
手段三：单技能沙盒测试
写技能的时候，不要每次都在完整 agent 里测试。我给每个技能做了独立的沙盒入口，可以直接传参数、跑执行、看返回 JSON。这样调参数校验逻辑和 result 格式的时候，不用走完整个 agent 链路，效率高很多。沙盒成本很低，一个命令行脚本的事，强烈建议早做。
5.3 技能库膨胀后的维护策略
技能超过三十个之后，维护压力就会变成主要矛盾。我的应对方案有三条：一是上面提过的tags标签体系，定期归档不常用技能；二是加version字段做灰度发布，新版本技能先只在一部分会话里启用，观察调用准确率和失败率之后再全量发布；三是建立技能的“调用统计报表”，每周看一次哪些技能高频触发、哪些技能长期无人问津。长期无人调用的技能不急着删，但要从模型的候选列表里降权，避免干扰选择。
注意：给技能加“调用统计”还有个隐藏好处——它能反向验证技能描述的质量。如果某个技能从来不被调用，但业务上明明需要它，那大概率是描述写得有问题，需要重新措辞而不是加更多功能。
6. 写在项目之外：我对技能体系下一步的想法
项目推进到现在，我最大的感受是：agent 的开发重心已经从“怎么让模型听懂人话”转移到“怎么让模型可靠地做事”，而技能体系正好是后者的核心抓手。把能力模块化、描述规范化、调用过程可观测化之后，智能体的行为能被显著约束在可控范围内。
我个人接下来的方向，一是做技能间的依赖声明——让某些技能可以显式声明它依赖哪些基础技能，避免重复代码；二是尝试让模型参与新技能生成——当现有技能无法完成任务时，模型能输出新技能的描述和逻辑，经人工审核后自动接入注册中心。这个方向还不成熟，但一旦跑通，agent 的自扩展能力会提升一个台阶。
最后分享一个很朴素的结论：给 agent 加技能，最难的部分从来不是写那个执行函数，而是把“模型会怎么理解和使用这个技能”想清楚。每次新增技能前，先站在模型的角度读一遍自己的描述——大概率会发现，你在心里想的和纸上写出来的，根本不是一回事。把这一步做好，整个技能库的质量就有了最基本的保障。
