最近我在折腾智能体开发时，被一个高频问题反复卡住：模型本身挺聪明，一让它干具体活儿就各种掉链子。要么不知道该调用哪个工具，要么把参数传得乱七八糟，要么只回复“我可以帮你处理”然后就没有然后了。后来我意识到，问题不在模型，而在我没有给模型一套结构化的技能体系。所以就有了 agent-skills 这套方案：把能力拆成可复用的技能模块，让模型像人一样按卡操作、按章执行。

这篇东西不会讲虚的。我会从 agent-skills 的定位讲起，一路拆到技能定义、注册机制、执行器实现、多技能编排，再把我在实际调试中踩过的坑一并列出来。适合正在做 AI Agent、机器人流程、或任何需要让大模型操作真实工具的开发者参考。项目本身不复杂，但很多细节不亲手磨一遍，很难体会到“技能”和“普通函数”之间的本质区别。

1. agent-skills 的整体设计与思路拆解

1.1 它到底是什么

agent-skills 不是某个单一模型，也不是一个开箱即用的成品应用。它更像一套“智能体技能管理机制”，解决的是：当大模型需要完成真实任务时，如何把任务拆解成可执行的动作，并在动作执行中保证正确性、可复用性和可观测性。

我在最初设计时，给 agent-skills 定下三个核心能力：技能注册、技能调用、技能编排。所谓技能注册，就是把一个个可复用能力（比如“查天气”“读PDF”“发邮件”）以统一格式登记到技能库中。技能调用，则是指大模型根据用户意图自动从技能库中选择合适的技能，并生成正确的调用参数。技能编排更进一步，允许把多个技能按逻辑顺序组织成一个流程，去完成一个复杂目标。

这三个能力对应的价值也很好理解：没有注册机制，技能就是一堆散落各处的函数；没有调用机制，模型永远不知道“该用哪个工具”；没有编排机制，稍微复杂一点的任务就只能在单次调用里打转，无法形成真正的工作流。

我在实际使用中感受到的最大变化是，agent-skills 把“模型会说什么”和“系统能干什么”彻底解耦了。模型只负责意图理解与规划，真正的动作执行全部由技能层完成。这样即使底层模型换掉，技能库依然可以复用，业务逻辑也不会被模型风格绑架。

1.2 为什么非要把“技能”单独拎出来

很多人第一反应可能是：我在代码里写几个函数，让模型通过函数调用不就行了？区别就在这里。

函数是一对一的固定接口，你给它写死参数，它就执行固定动作。但技能是带语义的、可被模型动态选择的模块。一个函数只能被显式调用，而一个技能却可以被模型在任意场景中主动发现。举个例子，你写了一个read_pdf(file_path)函数，模型必须先知道存在这个函数，而且要知道该在什么时候用。如果你把技能库做得足够清晰，模型可以通过技能描述推断出它适合解决哪类问题，甚至在用户没有直接提及“PDF”时，也能根据“帮我看看这份合同里违约金那条怎么写的”这类意图，联想到读取文件技能。

这种“可发现性”是技能系统区别于普通函数的关键。它要求每个技能都自带一份高质量的描述，包括功能摘要、适用场景、参数说明、返回值结构、使用限制。描述写得好不好，直接决定了模型选择的准确率。我在实践里试过用一句话描述技能，结果模型经常选错；改成详细说明后，选对率明显提升。

另外，单独拎出技能还有个好处：可替换性。同一个“发送通知”技能，底层可以用短信接口，也可以换邮件接口，对模型来说看到的都是统一技能接口，底层怎么实现完全不影响上层规划。我后来做多场景部署时，只需替换技能内部实现，模型侧代码一行不用动。

1.3 整体架构：技能注册表、执行器与规划器

agent-skills 在结构上分为三个层次：规划层、调度层、执行层。

规划层负责把用户输入转换成任务清单。这通常由大模型完成，它会读取技能注册表中的全部技能，结合用户请求，推测需要哪几步操作。这一层的输出不是自然语言，而是一份结构化的“技能调用计划”，例如先调用技能A，再根据技能A的结果调用技能B。

调度层是系统的核心。它负责解析计划，按顺序触发对应技能，并把每一步执行结果反馈给规划层。调度层同时处理超时、重试、异常分支、上下文累积。我在最初实现时把调度逻辑写得非常简单，只是按顺序执行列表，后来发现真实任务里会出现大量“根据上一步结果决定下一步”的情况，于是又把调度层改成支持条件跳转和循环。

执行层则是技能的具体实现。每个技能内部可以是任意代码逻辑，也可以是对外部系统API的封装。执行层只关心两件事：收到合法参数、返回结构化结果。它不关心模型是怎么想的，也不关心上层流程怎么走。

这三层各司其职，组合起来的完整链路是：用户输入 → 模型规划 → 调度解析 → 技能注册表匹配 → 执行器运行 → 结果回传。即使是最简单的单技能调用，也走这条链路。好处是——每当任务出错，我们能精确看到是哪一步出了问题，而不是在一个巨大的函数调用的黑盒里抓瞎。

2. 核心细节：技能定义与注册机制

2.1 技能描述的结构设计

技能定义是 agent-skills 的灵魂。我给每个技能设计了一套标准Schema，包含几个固定字段：

name: 技能唯一名称，小写蛇形 description: 技能功能描述，说明它能做什么、解决什么问题 version: 技能版本号，便于后续升级兼容 parameters: 调用参数定义，包含名称、类型、必填性、描述 returns: 返回结果结构说明 examples: 1-3个典型调用示例

这里面最容易被忽视的是 examples 字段。我起初觉得有 description 就够了，但实测发现，在长尾场景下，模型对纯文字描述的理解方差很大。给出一两个典型例子后，模型对“什么时候该用这个技能”的判断会稳定很多。尤其是当多个技能职责相近时，example 能直接当着“使用场景提示”来用。

举个例子，一个“获取天气”技能和一个“获取空气质量”技能，单看描述都差不多，模型容易混淆。如果“获取天气”的 examples 里有“用户问今天适合洗车”，模型就会把洗车这种依赖天气的问题关联过来，而不是误调空气质量接口。

参数定义方面，我强烈建议不要使用过度宽松的类型。比如“参数: content，类型: string”，模型很可能会传入乱七八糟内容。应该把每个参数都写成带业务语义的对象：{"name": "city", "type": "string", "required": true, "description": "城市中文名，如：上海、北京", "enum": ["北京", "上海", "广州"]}。枚举值能收就收，这样能挡掉大量无效调用。

2.2 技能注册表与动态加载

技能注册表在 agent-skills 里承担“技能目录”的职责。一个最简单的实现可以是一个字典，key 是技能名，value 是技能对象。但真实项目中，我建议把技能注册表做成独立的服务，或者至少用独立模块管理，避免把技能定义散落在业务代码各处。

我的习惯是：每个技能独立一个文件，通过装饰器或注册函数挂载到全局注册表。这样新增一个技能只需要新增一个文件，不需要改动调度层。

# 示例：技能注册装饰器 skill_registry = {} def register_skill(skill_cls): instance = skill_cls() skill_registry[instance.name] = instance return instance

这种动态注册方式还有个额外好处：可以按需加载。Agent 启动时，可以只加载当前任务域所需的技能子集，减少模型需要读取的技能描述数量。我实测过，当技能注册表里挂载超过40个技能时，模型在每次请求中读取全部描述的开销会明显增大，且选择准确率下降。按业务域拆分成多张注册表后，准确率回升，响应速度也快了。

注册表内部还应该保存每个技能的调用统计，例如调用次数、失败次数、平均耗时。这些数据虽然短期看没什么用，但当我需要决定哪些技能要优化时，就是直接看统计数据，而不是凭感觉。

2.3 技能描述与模型上下文的关系

大模型能看到技能，只是因为我们在系统提示词中拼入了技能描述。这带来一个直接问题：描述写太长会占用上下文窗口，写太短又影响选择准确率。

agent-skills 的做法是这样：把描述控制在100到300字之间，重点是“适用于什么场景”和“怎么用”。与任务无关的实现细节全都不写。比如一个发送邮件的技能，描述里只写“根据收件人地址发送邮件，支持正文和附件”，不用写“使用SMTP协议，超时设置30秒”。

另外，注意把技能描述的阅读顺序调整成“场景优先”。模型在扫描技能时，第一眼看到的应该是“我什么时候会用到这个技能”，而不是“我是谁”。我曾经因为把一个技能的功能定义写得太过详细，导致模型被具体操作步骤吸引，反而忽略了它适用的前置条件。后来重写描述，开头直接写“当用户需要向指定邮箱发送电子邮件时使用”，选中率立刻变好。

3. 实操：实现一个简易的 agent-skills 执行器

3.1 基础环境与项目结构

这里我以 Python 为例，搭建一个最小可运行的 agent-skills 执行器。不需要任何框架，只需要标准库加一个请求库就行。项目结构可以是这样：

agent-skills/ ├── registry.py # 技能注册表 ├── skill_base.py # 技能基类 ├── skills/ │ ├── weather.py # 天气技能 │ └── calculator.py # 计算器技能 ├── planner.py # 模拟模型规划（可替换成LLM） └── executor.py # 调度执行器

先把技能基类定义好。所有技能都继承这个基类，好处是执行器只依赖基类接口，不关心具体技能内部实现。

# skill_base.py class BaseSkill: name: str = "" description: str = "" parameters: list = [] def run(self, **kwargs): raise NotImplementedError def validate(self, kwargs): # 简单校验参数是否齐全 required = [p["name"] for p in self.parameters if p.get("required")] for k in required: if k not in kwargs: return False, f"缺少参数: {k}" return True, ""

3.2 具体技能示例：计算器与天气查询

计算器技能是最容易上手的例子。它的入参是两个数字和一个运算符，返回值是计算结果。

# skills/calculator.py from skill_base import BaseSkill class CalculatorSkill(BaseSkill): name = "calculator" description = "执行四则运算，支持加减乘除。当用户需要计算表达式时使用。" parameters = [ {"name": "expression", "type": "string", "required": True, "description": "数学表达式，如 1 + 2 * 3"} ] def run(self, **kwargs): expression = kwargs["expression"] # 注意：这里做简单处理，生产环境请使用安全计算库 return {"result": eval(expression)}

天气查询技能需要接入外部API。为了让示例脱离具体服务商，我用一个模拟函数代替。核心是展示一个技能如何封装外部依赖。

# skills/weather.py import random from skill_base import BaseSkill class WeatherSkill(BaseSkill): name = "get_weather" description = "获取指定城市当前的天气情况。当用户询问天气、温度、穿衣建议时使用。" parameters = [ {"name": "city", "type": "string", "required": True, "description": "城市中文名，如：北京"} ] def run(self, **kwargs): city = kwargs["city"] weather = random.choice(["晴", "阴", "小雨", "多云"]) temp = random.randint(10, 32) return {"city": city, "weather": weather, "temperature": temp}

我在写真实技能时，会额外增加一层缓存。比如天气查询技能，如果同一城市在10分钟内被重复查询，直接返回缓存结果。这个细节能显著减少外部API调用成本，尤其是在Agent做多轮对话时，模型经常会对同一城市反复查询。

3.3 注册与执行链路

注册表只需要把技能类实例化并保存。执行器则需要接收一个“技能名+参数”的指令，然后调用注册表中的技能执行。

# registry.py from skills.calculator import CalculatorSkill from skills.weather import WeatherSkill skill_registry = {} def register_all(): for cls in [CalculatorSkill, WeatherSkill]: instance = cls() skill_registry[instance.name] = instance def get_skill(name): return skill_registry.get(name)

# executor.py from registry import get_skill def execute_skill(skill_name, params): skill = get_skill(skill_name) if not skill: return {"success": False, "error": f"技能 {skill_name} 不存在"} valid, msg = skill.validate(params) if not valid: return {"success": False, "error": msg} try: result = skill.run(**params) return {"success": True, "skill": skill_name, "result": result} except Exception as e: return {"success": False, "error": str(e)}

到这里，一个最小可用的 agent-skills 执行器已经跑通了。用户说“计算 2+3”，模型返回一个规划结果：[{"skill": "calculator", "params": {"expression": "2+3"}}]，执行器就按这个规划调用，拿到结果后回给模型组织最终回答。

3.4 真实场景中的扩展点

这个简化版执行器可以直接工作，但放到真实项目里还需要补几个东西。

第一是超时控制。外部技能可能卡住，不能让Agent干等。我给每个技能的执行套一个超时装饰器，默认5秒超时。手写线程超时很麻烦，用concurrent.futures加上一个Future的等待过程即可。如果你在更复杂的框架里，也可以直接用框架自带的超时配置。

第二是重试策略。不是所有技能都适合重试。对于网络请求类技能，我会设置“失败后最多重试2次，间隔1秒”；对于计算类技能，就不需要重试。我会把重试参数写进技能定义，由技能自己决定是否允许重试，而不是全局一刀切。

第三是执行日志。每一步技能调用的入参、出参、耗时、错误信息都要记录下来。我在实际排查Agent问题时发现，绝大多数错误其实不发生在模型推理，而在技能入参不合法。有日志后才能快速还原现场。

4. 技能编排：从单技能调用到多步任务

4.1 让模型生成可执行的计划

如果只做单技能调用，agent-skills 的价值有限。真正的威力在于编排。我通常会让模型输出一个 JSON 数组作为执行计划，数组每一项代表一个步骤。

[ {"skill": "get_weather", "params": {"city": "北京"}, "next": {"success": "step2", "fail": "end"}}, {"skill": "calculator", "params": {"expression": "0"}, "next": {"success": "end"}} ]

执行器拿到这个计划后，就按照数组下标顺序执行。如果某一步失败，读取fail跳转目标。在更精细的设计里，next还可以带着条件表达式，比如“当上一步返回的 temperature 小于 10 时执行技能A，否则执行技能B”。

这个设计让模型从“说一句话”变成了“写一个简单程序”。我一直觉得这是 Agent 能力的分水岭：只会单次调用的是聊天机器人，能够按照计划连续调用技能并处理中间结果的，才是真正意义上的智能体。

4.2 条件分支与循环的一个实例

举个我最常用的例子：一个“穿衣建议”任务。用户问“北京今天适合穿什么？”模型规划后生成计划：

步骤1: get_weather("北京") 步骤2: 判断 temperature > 25 → 输出"短袖"，否则 → 步骤3 步骤3: 判断 temperature > 10 → 输出"夹克"，否则 → 输出"羽绒服"

这里步骤2和步骤3不是技能调用，而是逻辑判断。agent-skills 的执行器需要支持这种“非技能节点”。我的实现方式是给执行器内置一个condition技能，专门做表达式判断。

def condition(kwargs): expr = kwargs["expression"] return {"result": bool(eval(expr))}

然后执行器根据 condition 的结果，决定走哪个next。这种结构并不复杂，但把模型从“纯文本回复”的束缚里彻底解放了出来。

4.3 上下文累积与中间结果

多步任务里，后一步技能的参数常常依赖前面步骤的结果。我不能指望模型在规划时就把所有参数都猜对，因此设计了一个“变量传递”机制。

在计划中可以用$step1.result.temperature这样的占位符，执行器执行完步骤1后，会把结果保存到一个上下文对象里，步骤3需要参数时，就把占位符替换成实际值。这个操作虽然简单，但我认为它是 agent-skills 里最值得花时间优化的地方。一旦占位符替换逻辑出错，后面的技能全都会拿到错误参数。

我在初始版本里遇到了一个经典问题：步骤1的返回结果是个嵌套字典，而模型在生成$step1.result.temperature时路径写错，导致解析失败。后来我给模型提供的技能描述里加上返回结构样例，并严格要求模型生成计划时来自结果字段的引用必须完全匹配技能返回示例，才把这个问题压下去。

4.4 编排的容错与降级

真实任务不免出现“技能A失败，但用户也接受预案”的情况。我在 agent-skills 的编排中增加了“降级技能”字段，一个技能可以定义备选技能。比如 get_weather 失败时，可以降级到 get_climate。执行器在遇到技能失败时，如果发现备选技能，自动尝试备选，并把降级信息记录到日志。

这套机制让整体方案的鲁棒性上了一个台阶。我测试过一个场景：网络不稳定，天气API时不时报错，但我把 get_weather 的备选配置成 get_forecast 后，整个流程的成功率从70%提升到了95%以上。虽然备选结果精度稍低，但用户任务没有被中断，体验好得多。

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

5.1 技能描述模糊导致选错技能

这是我在 agent-skills 使用中遇到概率最高的问题。现象是：用户明明说的是A需求，模型却去调用了B技能。排查方法很简单：打开执行日志，看模型最终实际选择的技能名，再看该技能描述和用户输入的相似度。

我碰过一种很隐蔽的情况：两个技能描述里都有“文件”这个词，模型就分不清该读文件还是该写文件。后来我在每个技能描述开头加上“主动动词+用户意图”的句式：“当用户要求把内容保存到文件时使用”，才彻底解决。所以我的建议是：技能描述一定要包含“什么时候用”和“什么时候不用”。比如读文件技能可以写明“当用户提到查看、读取、打开文件时使用”，写文件技能则写“当用户提到保存、写入、导出时使用”。尽量让两个技能在词汇上减少交集。

5.2 参数校验形同虚设

很多人写了validate函数，但仍然传入错误参数。比如参数定义里写temperature是数值，模型却传了字符串“零上10度”。根本原因是模型不知道如何把用户口语转换成参数格式。

解决办法是：在参数描述中提供转换示例。不要写“温度值”，要写“温度值，数字，如：28”。更稳妥的做法是在技能内部做一次强制类型转换和范围校验。我在 get_weather 技能里加了这个逻辑：如果温度参数不是数字，则调用一个内置解析函数尝试从字符串中抽取数字部分；抽不出来就返回错误。

另外一个技巧是：如果参数可以标准化为枚举值，就尽量用枚举。模型在限定选项里的选择准确率，远高于开放文本生成的准确率。比如城市参数，如果业务只覆盖十个城市，就把这十个城市写到enum里，模型基本不会选错。

5.3 并发调用引发资源竞争

当 Agent 一次编排里包含多个技能，而这些技能之间没有依赖关系时，我们会尝试并行执行。并行速度提上去了，但随之而来的是资源竞争。比如多个技能同时写日志文件，造成日志串行；或者外部API的连接池被占满，触发限流。

我处理这个问题的思路是：给每个技能声明一个“并发等级”。无状态技能可以支持高并发，共享外部连接或操作同一文件的技能则必须串行。执行器在调度时读取技能并发等级，为低并发等级技能加锁。这算是在性能和稳定性之间做了一个折中。

5.4 执行上下文越滚越大

多步任务跑久了，模型规划时会把所有中间结果都塞给技能，导致技能收到的参数里出现大量无关字段。这在“让模型自主规划”的实现里尤其常见。模型倾向于复制整个上下文对象作为下一个技能的参数，结果参数越来越大，最终超过接口限制。

我建议在执行器层面统一过滤参数，只提取技能定义中声明过的字段来组装调用。这个“白名单机制”是必须的，否则技能接口早晚被污染。而且我发现，加上参数过滤后，很多奇怪的调用错误也自动消失了，因为模型乱传的字段根本没有机会进到技能内部。

5.5 模型规划不稳定

同一个用户问题，模型今天规划三步，明天规划五步，后天又只规划两步。这种不稳定性对技能系统影响很大。我最终采用了“规划缓存”和“规则兜底”相结合的办法。对已知的固定任务模板，直接使用人工写好的规划模板，不再让模型自由发挥；只有新任务才走模型动态规划。同时，每次模型规划成功后，会把“用户意图哈希 + 规划结果”存到缓存里。下次遇到相似请求，直接复用。

这套策略有效减少了模型的随机性，也让 agent-skills 的行为可预期了不少。

6. 从技能库到智能体操作系统的延伸

6.1 技能版本管理与权限控制

技能多了之后，版本管理就是绕不开的事。现在我会给每个技能加版本号，并在注册表中做多版本共存。调度层默认调用最新版本，如果最新版本效果不好，可以一键切回旧版本。这种“灰度切换”在实际发布中帮了大忙。

权限控制也很重要。某些技能只能管理员调用，某些技能需要用户显式授权。agent-skills 在技能定义中增加了required_permission字段。执行器在调用前检查当前会话的权限等级，不具备权限就直接拒绝。这是防止Agent在自主执行时越权操作的基础保障。

6.2 技能间依赖与共享服务

当技能量级上来后，你会看到不少重复逻辑。比如多个技能都需要读取配置、获取当前用户信息、记录审计日志。与其在每个技能内部重复写，不如把这些共享能力也做成“内部技能”，供其他技能调用。

这里要区分一个概念：模型调用的技能和技能内部调用的技能不是同一层次。模型调用的技能是业务动作，内部技能是实现细节。我在 agent-skills 里用“外部技能”和“内部工具”两个命名空间把它们分开，避免模型误以为内部工具也是可调用的业务技能。这一步能在很大程度上减少模型误选。

6.3 把技能变成可评测可优化的对象

我最后想说的扩展方向是“技能评测”。既然技能是独立模块，它就应该像代码一样可以被单测。

我会为每个技能准备一批“人工标注用例”，包括输入、期望输出、期望副作用。每次修改技能内部实现后，跑一遍用例，确保没有破坏原有功能。这套用例集虽然维护起来要花时间，但它让我在改动底层实现时不再提心吊胆。没有评测体系的技能库，做大了以后一定会回归混乱。

7. 写在最后：一点真实体会

agent-skills 这套思路带我走过了从“聊天机器人”到“能干活的智能体”之间那段最难的路。最大的教训不是技术实现难，而是千万不要把技能库当成一个普通函数集合来写。每个技能都是一等公民，它有自己的描述、参数、边界、版本、权限和评测用例。只有把它们当作产品长期维护，Agent 才能真正稳定工作。

最后分享一个实用小技巧：在技能执行器里加一个“观察者模式”，把每次技能调用的完整链路发送到一个可视化面板。当Agent某个环节出错时，你能一眼看出是模型选择了错误的技能，还是参数不合法，还是外部接口宕机。这个可视化的调试手段，早期可能看不出价值，等技能库规模超过30个之后，它几乎就是救命稻草。

如果你也在做 Agent 相关的东西，我的建议很简单：先别急着上复杂框架，把技能定义、注册、执行、编排这套最小闭环跑通。跑通了，再往里面加东西。你会发现，智能体的能力上限，不在于模型多聪明，而在于你的技能系统有多扎实。