最近在整理一套基于多智能体的自动化处理方案时，我发现自己反复接触到一个关键词：agent-skills。这并不是某个特定框架里的专有名词，而是指代理本身所能执行的一组可复用技能集合。从早期的简单提示词调用，到后来成体系的技能定义、注册、校验和编排，这套思路几乎贯穿了当今所有主流智能代理项目的底层设计。今天围绕这个标题，把我自己从零搭建技能库的完整过程和踩坑记录分享出来，希望能给正在研究代理能力边界的你一点参考。
先说清楚这是个什么东西。agent-skills 本质上解决的是“让代理在动态环境里稳定调用工具”的问题。你可以把它理解成一种标准化的技能包：每个技能包绑定一个明确的任务目标、输入参数、校验规则，以及对应的执行逻辑。比起把全部执行步骤塞进一轮模型对话里，这种拆分成独立技能模块的做法，能显著提升代理的稳定性、可复用性和可维护性。适合正在做智能助手、自动化工序拆解、企业流程智能化改造的人，也适合对多智能体协作模型感兴趣的开发者。
我当时接手的是一个模拟项目X，目标是把原本靠多人维护的一套业务运营清单，改成由代理自主识别任务、自动调度执行、并汇总反馈。刚开始我以为只要在系统提示词里写得足够详细，模型自然就能“看懂”业务规则，结果实际跑起来完全不是那么回事：任务稍长一点，上下文就开始相互污染；某些固定的判断逻辑模型会自己发挥；换一个业务版本，之前调通的流程又变得不可靠。走到这一步我才意识到，光靠自然语言约束的代理是不可控的，必须把每一项动作变成一项明确、独立的技能，然后围绕技能去构建整个执行链路。
1. 整体设计与思路拆解
1.1 从“提示词驱动”转向“技能驱动”
最早那版方案里，所有业务规则都写在系统提示词里，大概两千多字，外加几份参考样例。小范围测试时效果还算可以，一旦任务涉及的环节超过五个，模型就会开始“选择性遗忘”之前的约束。比如要求第一步先校验数据格式，第二步再调用计算模块，模型有时候会跳过校验直接进入计算，甚至把校验环节的结果当成下一步的输入参数。
后来我意识到，模型本质上是概率推理，不适合承载强约束的业务规则。把这些规则从提示词中剥离出来，变成独立的可执行代码模块，再由代理按需调用，这才是稳定路线。每个技能模块承担一个原子任务，输入输出都有严格定义，模型只负责决定“何时调用哪个技能”，不再负责具体怎么做。这两者一分离，整套逻辑立刻清晰了。
这个设计的核心原则是：让模型只做决策，让代码做执行。决策部分需要发挥模型的语义理解能力，执行部分则需要完全确定性。技能模块内部不依赖模型推理，所有逻辑都是预先写好的，这样无论模型怎么“发挥”，落地的动作永远是可控的。
1.2 技能库的组织方式：原子技能与复合技能
技能库不能一上来就平铺一堆功能函数，否则代理会面临选择困难。我的做法是把技能分成两层：原子技能和复合技能。
原子技能是不能再拆分的最小操作单元，比如“读取配置文件”“校验邮箱格式”“发送一条通知”“查询一条记录”。这类技能没有业务含义，只有单一且明确的功能。复合技能则由多个原子技能按固定顺序组合而成，相当于一条标准作业流程，比如“处理新用户注册”这个复合技能，内部可能包含校验参数、写入数据库、发送欢迎通知三个原子技能。
代理在实际运行时默认只感知复合技能层，只有在复合技能内部需要动态分支时，才会进一步调用底层原子技能。这样的好处是：日常使用中代理面对的选择数量被大幅压缩，避免了“几十个技能摆在一起不知道选哪个”的尴尬；同时底层技能的通用性又保证了灵活性，换个业务场景，重新组合一遍就能复用。
1.3 技能描述的质量直接影响调度准确率
技能库里每个技能都有配套的描述文本，代理就是靠这串描述来做调度的。第一次构建时我低估了描述的重要性，技能名写得很简短，描述也只有一句话，例如“处理用户注册”，结果代理经常在相似技能之间选错。
后来总结下来，技能描述至少要回答三件事：这个技能解决什么问题、输入参数是什么类型、典型使用场景是什么。描述应该像给一个完全不懂代码的同事写操作说明，而不是给自己看的便签。比如“读取用户注册信息”这个技能，描述里需要写明“从指定数据源读取并解析用户提交的注册字段，返回结构化字典，仅在用户点击注册按钮后调用”，这样代理在判断时就不会和“查询用户资料”搞混。
1.4 为什么需要独立的技能注册中心
当技能数量超过二十个之后，每个技能的版本管理、参数校验逻辑、启用状态就变得很庞杂。临时在代码里硬编码一套技能数组的做法开始变得吃力，于是我又加了一层技能注册中心。其实就是一张结构化的技能配置表，集中记录技能名称、描述、参数schema、入口函数、关联权限和状态信息。代理启动时会自动加载这张表，生成可调度的技能列表。
注册中心带来的额外好处是权限控制有了落地载体。在技能配置里增加了必需的权限标记，比如有的技能只能在内网调用，有的技能需要管理员身份，代理在决策时如果发现当前会话权限不足，可以直接跳过而不是花费上下文空间去“思考该不该执行”。这种前置过滤极大减少了无效推理。
2. 核心细节解析与实操要点
2.1 技能输入参数的严格schema化
这是整套方案中最重要的一个细节。技能模块的入参如果只是一堆松散字段，代理解析时就会出现各种奇怪的类型错配。一个典型的教训是：某个技能原本定义了一个名为“time”的参数，代理调用时传进来“2025-03-15 14:30:00”这种字符串，而技能内部却需要时间戳数值，结果每次运行都报错，而报错信息又不直观，排错花了不少时间。
后来所有技能的参数全部改成严格的 JSON Schema 约束，每个参数都声明类型、必填性、默认值和取值范围。代理在调用技能前，注册中心会对传入参数做一次自动校验，不符合 schema 就直接拒绝调用，并生成结构化的错误反馈。这一步看起来很简单，实际上能过滤掉一大半低级错误，让代理把有限的推理资源集中在真正的决策上。
参数命名也需要讲究。尽量使用语义明确的名称，减少缩写歧义。比如“usr_id”不如“user_id”直观，而“user_id”又不如“user_account_id”在面对多个业务模块时更清晰。图形上即使代理理解能力强，但是在大量相似参数名之间做区分时，命名差异仍然是决定准确率的重要变量。
2.2 技能执行结果的结构化返回
技能的返回值同样需要规范化。早期一些技能返回的是纯文本描述，比如“读取成功，共5条数据”，代理需要再次解析这段文本才能提取出“5”这个数值，既浪费上下文又容易出错。后来说到底还是改成结构化返回，统一用 JSON 格式输出数据字段，外加一个独立的状态码字段。
状态码设计参考了常规接口规范：0表示成功，非0表示各类异常。每一项异常都带有明确的错误标识和人类可读的信息。代理拿到返回值之后，优先看状态码，只有状态码为0时才去读取数据体。这个约定让后续的错误处理逻辑变得非常统一，不管哪个技能出了问题，推进流程的框架代码都执行同一套处理流程。
2.3 技能调用权限与密钥隔离
代理执行某些技能时，往往需要访问外部依赖或内部系统，这就涉及到密钥管理的问题。绝对不能把密钥明文写在技能配置表里，无论项目体量多小都不能这么干。我在模拟项目X中是专门建立了一个环境变量索引，技能注册中心只记录密钥的索引名称，实际值从运行环境中读取。
另外，即使是同一个技能，在不同调用场景下可能需要不同的权限。比如“读取订单信息”这个技能，普通会话只能读取脱敏数据，管理员会话才能读取完整数据。我在技能配置里增加了访问分级字段，代理在决策阶段就会结合当前会话权限筛选可用技能列表，权限不足的技能直接隐形，避免代理“越权尝试”之后被拒绝的尴尬循环。
2.4 技能回归测试的重要性
技能库会随业务迭代不断更新，每一次修改都有可能会影响到依赖它的复合技能。为每个技能写几组典型的单元测试，是我见过性价比最高的投资。测试用例要覆盖三类场景：正常输入、边界输入、典型异常输入。我每次修改技能内部逻辑后，都会跑一遍全量测试，确认原有行为没有被破坏。
这里有个心得：测试用例的预期输出不要太宽松，避免只断言“返回结果不为空”。一定要明确断言具体的数据内容。比如某个解析技能，应该断言“返回值中字段device_type 等于 mobile”，而不是“返回值中有 device_type 字段”。松散的断言会让回归测试失去筛选价值，等于没写。
3. 实操过程与核心环节实现
3.1 搭建技能模块的基本文件结构
我采用了一套固定的文件组织方式，每个技能一个独立目录，包含配置文件、主逻辑文件和测试文件。目录结构大致如下：
skills/ user_register/ skill.yaml main.py test_cases.py data_check/ skill.yaml main.py test_cases.pyskill.yaml记录技能元信息和参数schema，main.py是技能的实际执行入口，test_cases.py存放针对该技能的回归测试。技能注册中心通过扫描skills/目录，自动加载所有子目录下的skill.yaml，形成一个统一的调度清单。
3.2 编写技能配置示例
以“用户注册信息解析”这个原子技能为例，skill.yaml的核心字段如下：
name: parse_user_registration description: 解析用户提交的注册请求体，将原始请求字符串转换为结构化的注册信息字典。仅在用户点击注册按钮后调用。 version: 1.0.0 enabled: true permission_level: normal parameters: type: object properties: raw_body: type: string description: 注册请求体的原始JSON字符串 source_channel: type: string enum: [web, mobile, api] default: web required: - raw_body returns: type: object properties: user_account_id: type: string register_time: type: string channel: type: string这里特别注意parameters字段的required列表，只把真正必须的字段列入，可选项通过default补全。代理如果发现可以不传某个参数，决策压力会小很多。
3.3 技能执行入口的骨架实现
main.py里的入口函数保持统一的签名，便于注册中心统一调用。一个典型骨架如下：
def execute(payload: dict) -> dict: # 参数校验已在注册中心完成，此处只需取参数 raw_body = payload["raw_body"] source_channel = payload.get("source_channel", "web") try: # 核心逻辑区域 data = parse_register_body(raw_body) if not data: return {"code": 1001, "message": "解析结果为空", "data": {}} # 业务处理 formatted = format_register_data(data, source_channel) return {"code": 0, "message": "ok", "data": formatted} except Exception as e: return {"code": 5000, "message": f"internal error: {e}", "data": {}}统一返回{"code", "message", "data"}这个结构，最大好处是上层逻辑极其简单。代理只需要判断code == 0，不管成功还是失败都能直接进行后续处理，而不需要层层嵌套的去 try 各种解析逻辑。
3.4 技能注册中心的加载逻辑
注册中心的实现不复杂，核心是从所有技能目录中读取skill.yaml,动态生成一个字典。一个简化版本的加载代码：
import os import yaml def load_skills(): skills = {} base_dir = "skills" for entry in os.listdir(base_dir): skill_dir = os.path.join(base_dir, entry) if not os.path.isdir(skill_dir): continue config_path = os.path.join(skill_dir, "skill.yaml") if not os.path.exists(config_path): continue with open(config_path, "r", encoding="utf-8") as f: config = yaml.safe_load(f) # 额外检查启用状态 if config.get("enabled", True): skills[config["name"]] = config return skills这里有一个细节：加载后最好对技能配置做一次全量校验，而不是等到调用时才报错。例如parameters.properties里声明的字段与main.py中实际读取的字段不一致，这种错位在静态阶段发现成本最低。我写了一个简单的配置检查脚本，跑在注册中心加载之后、对外服务之前。
3.5 复合技能的编排方式
复合技能我通常直接写成普通函数，内部按顺序调用原子技能。因为不涉及模型推理，这块代码非常好写。一个“处理用户注册并发送欢迎通知”的复合技能大致是：
def execute(payload: dict) -> dict: step1 = parse_user_registration.execute(payload) if step1["code"] != 0: return step1 step2 = check_user_eligibility.execute({"account_id": step1["data"]["user_account_id"]}) if step2["code"] != 0: return step2 step3 = send_welcome_notice.execute({"account_id": step1["data"]["user_account_id"]}) return step3每个子步骤失败就立即中断，并返回对应错误信息。这里需要注意不要把所有步骤的错误都合并成一个通用提示，否则运维排障时需要逐个步骤去猜。每一步的错误保持独立，最终反馈给用户的信息再统一包装一次。
3.6 代理调度技能时的提示词设计
虽然执行逻辑全部下沉到了技能模块，但代理本身还需要一套简洁的调度说明。我的做法是在系统提示词中加一段固定格式的“技能使用指南”，把技能列表直接贴给代理，同时写明使用原则。例如：
你是一个技能调度引擎。以下是你可调用的技能列表，每个技能包含名称、描述和参数格式。你需要根据用户当前意图，从列表中选择最合适的技能进行调用。如果需要多个技能协同完成，请按顺序逐步调用，并在上一步返回成功后进行下一步。禁止使用列表之外的任何工具，禁止修改技能内部逻辑。这段话的核心作用是划清边界：代理只能从给定列表中选择，不能自行发挥。加上“按顺序逐步调用”这句约束之后，代理在复合任务中的表现明显变得更稳健，不会试图跳步或并行执行有依赖关系的技能。
4. 常见问题与排查技巧实录
4.1 代理选择了错误技能
最常见的现象是用户意图明明对应技能A，代理却调用了技能B，而且经常是因为技能描述里出现了相似词。排查方法是打开附近的决策日志，看看当时给代理的技能列表顺序。有些情况下描述准确仍然选错，是因为两个技能描述里的关键词重合度过高。解决策略是主动在描述里加上“边界词”，比如“仅为...”、“不要用于...”，把容易混淆的场景提前排除。
我做过一次对比试验：同一批技能，A版本描述只写功能，B版本描述增加排除场景，结果调度准确率从82%提升到94%。这个数字虽然不是严格的学术实验，但对实际项目来说已经是非常可观的改进。
4.2 参数校验通过但执行仍然报错
这种情况一般出现在非必填参数上。注册中心只校验了参数是否存在，没校验参数内容是否在可接受范围内。比如某个技能允许传入“limit”参数，默认是10，最大是100，代理传入一个字符串“abc”，schema校验发现类型不匹配会拦截；但如果代理传入字符串“50”，类型校验过了，执行时才转整数报错。后来我在 schema 中给这类参数增加明确的pattern或enum限制，类型转化错误几乎清零。
这里建议一条原则：技能内部永远不要默认入参一定安全。即使注册中心已经做了校验，入口函数再补一次转换和兜底，成本很低，但能避免大多数线上异常。
4.3 上下文过长导致代理丢失技能信息
当技能数量很大，配置描述全部拼进提示词后，上下文可能超过模型可接受范围。早期测试时技能列表只占几千字符还好，后来技能增加到五十个以上，提示词本身就开始挤占任务推理空间，代理反而会遗忘后面的技能描述。
我采用的策略是分组调度，也就是把技能分成若干个职能域，代理先根据用户请求判断属于哪个域，再调用该域的子技能列表。这个分域过程本身也可以做成一个“路由技能”，这样代理每一轮看到的技能数量都不会太多。实际效果是精度和响应速度都得到了提升。
4.4 技能内部异常被吞掉的情况
有些技能模块为了追求“简洁”，在 except 区域直接写一句return {"code": -1}，导致上层完全不知道发生了什么。这其实是个很坑的习惯。排查这类问题时，最有价值的信息是异常栈和具体的参数上下文。我现在的做法是除非异常，否则返回消息里一定带上异常类型和发生异常所在的技能名称，方便日志检索。
4.5 技能更新后旧会话还在用旧逻辑
虽然技能代码更新后注册中心会重新加载，但与已建立的代理会话上下文还是会残留旧技能描述。理想情况是每次技能变更后，强制建新会话或在提示词里标记一次技能版本变更。实际操作中我是在技能列表中增加一个version标记字段，代理决策时如果发现版本与自己掌握的版本不一致，会主动要求刷新技能列表。虽然这种机制并不完美，但能减少不少“明明部署了新代码，代理却还在按照旧规则处理”的困惑。
5. 一个典型任务链的完整走查
为了把整个技能库跑通，我以“用户上传文件并触发合规检查”这个场景做了一次完整走查。整个任务链涉及三个复合技能和七个原子技能。代理收到用户请求后，首先调用“解析上传任务”复合技能，把用户上传的原始文件内容解析成标准化任务描述。这一步内部调用了文件格式识别、内容解析、字段映射三个原子技能。解析成功后，代理进入“检查合规项目”复合技能，依次调用敏感信息扫描、权限范围核对、数据保留策略匹配三个原子技能。如果检查结果全部通过，代理最后调用“登记归档”复合技能，写入任务记录并向用户发送完成反馈。
这个链路的每个环节返回值都是统一格式，所以调试的时候完全不用去猜测状态。整个过程跑下来，最直观的感受是：代理真正变成了一个调度者，而不是一个什么都要亲自动手的执行者。这种模式对资源消耗的控制效果也很明显，同样是处理十个任务，之前的实现上下文消耗严重，经常跑到第三四个任务时就开始出现“遗忘”，换成技能库之后十轮任务几乎没有上下文质量衰减。
如果你现在正在做的项目也涉及让代理“学会调用工具”，我的建议是不要急着写复杂提示词，先把需要代理做的事情拆成独立的技能清单，哪怕最初只拆出三五个，也要把描述、参数、返回结构定义清楚。这个前期动作看起来繁琐，但它决定了后续所有可维护性的上限。
我自己的体会是：技能库这种架构，本质上是在模型能力和业务确定性之间搭一座桥。桥搭得越稳，上层应用就越敢把更复杂的任务交给代理去执行。反过来，如果没有这座桥，代理的能力再强，也很难让你放心地在真实流程里放手让它干活。
