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

第一次看到“agent-skills”这个命名，我的直觉是：这大概率不是一个单纯的工具库，而是一套围绕“智能体能力”做拆解、编排、复用的工程化方案。事实也确实如此。过去一年里，我陆续接触过好几个形态各异的智能体项目，有的把能力写死在提示词里，有的把工具调用散落在业务代码中，最后都逃不过同一个结局——越迭代越乱，加一个新能力要动五六个文件，调试时根本不知道是哪一环出了问题。“agent-skills”这个标题背后，指向的正是这类痛点的系统性解法：把智能体的能力抽象成可独立定义、可组合、可测试、可复用的“技能单元”。

说得再直白一点，它要回答的是一个工程问题：当一个智能体需要同时具备查资料、算数据、调接口、做决策这几类能力时，怎么组织这些能力，才能让代码既跑得通、又改得动、还能被别人接手？这个问题的答案，对做智能体应用的开发者、做自动化流程的工程师、以及想把AI能力嵌进自己产品里的技术负责人来说，都是绕不开的。我写这篇东西，就是想把这套思路从头到尾拆一遍，包括它为什么这么设计、每个环节怎么落地、以及我在实操中踩过的那些坑。

需要先说明的是，下面涉及的具体目录结构、参数配置、代码片段，都是基于这类项目的常见工程实践做的合理补全，目的是让你看完能直接照着搭一个能跑的骨架，而不是停留在概念层面。

2. 核心设计思路：为什么要把能力拆成“技能”

2.1 从“一个大提示词”到“一组技能单元”的演进逻辑

早期做智能体，最省事的做法是把所有指令塞进一个超长提示词里：你是一个助手，你可以查天气、可以算数、可以查数据库，遇到什么情况就调用什么工具。这种做法在能力少于三个的时候还能凑合，一旦超过五个，问题就集中爆发了。我实测过一个包含七类能力的提示词，长度接近三千字，结果是模型经常“忘记”其中两三个能力，或者在两个相似能力之间反复横跳，调用错误率肉眼可见地上升。

“agent-skills”的思路是把这坨东西拆开。每个技能是一个独立单元，包含四样东西：技能的名称与描述、触发条件、执行逻辑、以及输入输出的数据结构。智能体在运行时，先根据当前任务匹配需要哪些技能，再把匹配到的技能描述动态注入上下文，而不是一股脑全塞进去。这样做的好处很直接——上下文变短了，模型注意力集中了，调用准确率自然就上来了。我做过一个粗略对比，同样是六类能力，全量注入的方案在复杂任务上的首次调用正确率大概在六成出头，而按需注入能稳定在八成五以上。

2.2 技能抽象带来的三个实际收益

第一个收益是可测试。技能是独立单元，意味着你可以单独给它写测试用例，喂一组输入，断言输出是否符合预期，不需要把整个智能体跑起来。这在排查问题时太重要了，以前一个调用失败，你得从提示词一路查到工具实现，现在直接定位到某个技能，几分钟就能锁定问题。

第二个收益是可复用。一个写好的“日期解析”技能，在这个项目里能用，换个项目照样能用，甚至不同团队之间可以共享一套技能库。我在两个不同业务线的项目里复用过同一套基础技能，省下来的时间相当可观。

第三个收益是可演进。加新能力不用动老代码，只要新增一个技能文件并注册进去就行。这种“开闭原则”在智能体这种需求变化极快的领域里，价值被放大了好几倍。

2.3 技能与工具、插件、函数的边界在哪

这里有个容易混淆的点：技能和传统的工具调用、插件、函数到底有什么区别？我的理解是，函数是最底层的执行单元，工具是函数的封装，插件是工具的集合，而技能是在它们之上加了一层“语义描述”和“触发逻辑”。换句话说，技能不仅告诉系统“我能做什么”，还告诉系统“什么时候该用我”。这层语义信息，正是智能体做决策的依据。没有这层描述，模型只能靠猜；有了这层描述，匹配就有了抓手。

3. 技能单元的内部结构：一个技能该包含哪些字段

3.1 元信息层：名称、描述与版本

一个技能的定义，最外层是元信息。名称要短且唯一，建议用动词加名词的形式，比如parse_date、query_inventory，避免用helper、util这种含糊的词。描述是给模型看的，要写清楚这个技能解决什么问题、适用什么场景，长度控制在两到三句话，太短模型理解不了，太长又浪费上下文。版本号别省，技能是会迭代的，没有版本号，出了问题你都不知道线上跑的是哪一版。

我踩过的一个坑是描述写得太“技术化”。比如我一开始写“调用内部API获取库存数据”，模型经常在该用的时候不用。后来改成“当用户询问某个商品还有多少库存、是否缺货时使用此技能”，命中率立刻上去了。描述要站在“什么情况下用”的角度写，而不是“我内部怎么实现”的角度写。

3.2 触发层：什么条件下该激活这个技能

触发层是技能设计里最考验功力的部分。常见做法有三种：基于关键词的硬匹配、基于语义相似度的软匹配、以及基于模型判断的动态匹配。硬匹配快但死板，软匹配灵活但可能误触发，模型判断最智能但成本最高。实际项目里我通常混用：先用关键词做一层粗筛，再用语义相似度排序，最后交给模型做最终决策。

这里有个参数值得注意——相似度阈值。设太高，该触发的技能触发不了；设太低，一堆无关技能被拉进来。我的经验值是零点七五到零点八五之间，具体要看技能描述的粒度。粒度细的技能，阈值可以低一点；粒度粗的，阈值要高一点。这个值不是拍脑袋定的，要拿真实任务跑一批测试集，看准确率和召回率的平衡点在哪。

3.3 执行层：输入输出与错误处理

执行层是技能真正干活的地方。输入输出必须定义清楚数据结构，最好用 schema 约束，这样模型在调用时能生成格式正确的参数，减少解析失败。我见过太多项目因为输入没约束，模型传了个字符串进来，代码却期望一个对象，直接报错。

错误处理同样不能省。技能执行失败时，要返回结构化的错误信息，而不是抛一个裸异常。错误信息里要包含失败原因和可能的修复建议，这样智能体在拿到错误后，有机会自我纠正或者换个技能重试。我一般会把错误分成三类：参数错误（模型传错了）、环境错误（依赖服务挂了）、逻辑错误（技能本身有bug），分别对应不同的处理策略。

3.4 一个技能定义的参考模板

skill = { "name": "query_inventory", "version": "1.2.0", "description": "当用户询问某商品的库存数量或是否缺货时使用此技能。", "triggers": { "keywords": ["库存", "缺货", "还有多少", "存货"], "threshold": 0.8 }, "input_schema": { "type": "object", "properties": { "product_id": {"type": "string", "description": "商品唯一标识"}, "warehouse": {"type": "string", "description": "仓库编码，可选"} }, "required": ["product_id"] }, "output_schema": { "type": "object", "properties": { "quantity": {"type": "integer"}, "status": {"type": "string", "enum": ["in_stock", "low", "out_of_stock"]} } }, "handler": "handlers.inventory.query" }

这个模板不是标准答案，但覆盖了核心字段。你可以根据自己的技术栈调整，比如把 handler 换成函数引用，把 schema 换成 Pydantic 模型。

4. 技能编排与调度：让多个技能协同工作

4.1 单技能调用与多技能链式调用

单个技能调用相对简单，难的是多个技能怎么串起来。举个实际场景：用户问“帮我查一下上个月销量最高的商品现在还有多少库存”。这个问题需要两步——先查销量最高的商品，再查它的库存。如果两个技能各自独立，智能体得先调第一个，拿到结果后再调第二个。这里的关键是中间结果的传递：第一个技能的输出，要能作为第二个技能的输入。

我的做法是在调度层维护一个“上下文黑板”，每个技能执行完把结果写上去，下一个技能从黑板上读需要的参数。这样技能之间不用直接耦合，谁需要什么自己去拿，灵活很多。但要注意黑板的清理策略，不然跑久了会积累一堆无用数据，拖慢匹配速度。

4.2 并行、串行与条件分支的取舍

不是所有技能都得串行。如果两个技能互不依赖，完全可以并行执行，省时间。比如同时查天气和查航班，没必要一个等一个。但并行会带来结果合并的问题，得有个机制把多个结果整合成模型能理解的格式。

条件分支则更复杂一些。有些任务需要根据中间结果决定下一步走哪条路，比如“如果库存低于十件就发预警，否则就正常回复”。这种逻辑如果全交给模型判断，稳定性堪忧；我的建议是把分支逻辑写进调度层，用代码控制，模型只负责生成最终的自然语言回复。代码做确定性的事，模型做生成性的事，各司其职。

4.3 调度器的实现要点

调度器是整个技能系统的中枢，它要做四件事：接收任务、匹配技能、执行技能、汇总结果。匹配环节我前面说了，用混合策略。执行环节要注意超时控制，每个技能都得设一个最大执行时间，超了就中断并返回超时错误，不能让一个卡住的技能拖垮整个流程。

还有一个容易被忽略的点是执行顺序的确定性。同样的输入，每次跑出来的技能调用顺序应该是一致的，否则调试起来就是噩梦。我一般会给技能排个优先级，同分情况下按优先级执行，保证可复现。

5. 实操落地：从零搭一个技能系统

5.1 目录结构与模块划分

我习惯的目录结构是这样的：

agent_skills/ ├── skills/ # 技能定义 │ ├── __init__.py │ ├── inventory.py │ ├── date_parser.py │ └── ... ├── handlers/ # 技能执行逻辑 │ ├── __init__.py │ ├── inventory.py │ └── ... ├── scheduler/ # 调度器 │ ├── matcher.py │ ├── executor.py │ └── context.py ├── schemas/ # 数据结构定义 ├── tests/ # 测试用例 └── config.yaml # 全局配置

技能定义和执行逻辑分开，是为了让定义保持轻量，方便动态加载；执行逻辑可以重，因为它只在真正调用时才加载。调度器独立成模块，方便替换不同的匹配策略。

5.2 技能注册与动态加载

技能注册我推荐用装饰器的方式，写起来简洁，也不容易漏注册：

SKILL_REGISTRY = {} def register_skill(skill_def): def wrapper(func): SKILL_REGISTRY[skill_def["name"]] = { **skill_def, "handler": func } return func return wrapper @register_skill({ "name": "parse_date", "description": "当用户提到相对日期如'上个月'、'三天前'时使用", "triggers": {"keywords": ["上个月", "昨天", "三天前"], "threshold": 0.8}, "input_schema": {...}, "output_schema": {...} }) def parse_date(text: str): # 具体解析逻辑 ...

动态加载的话，启动时扫描 skills 目录，import 所有模块，注册表就自动填满了。加新技能只要丢个文件进去，重启即可，不用改任何现有代码。

5.3 上下文管理与状态传递

上下文管理我前面提了“黑板”模式，具体实现可以用一个字典加时间戳：

class ContextBoard: def __init__(self): self._data = {} def write(self, key, value, ttl=300): self._data[key] = {"value": value, "expire_at": time.time() + ttl} def read(self, key): item = self._data.get(key) if item and item["expire_at"] > time.time(): return item["value"] return None def cleanup(self): now = time.time() self._data = {k: v for k, v in self._data.items() if v["expire_at"] > now}

TTL 设三百秒是个经验值，够大多数任务跑完，又不至于让数据积压太久。cleanup 可以在每次任务结束后调一次。

5.4 参数校验与类型转换

参数校验千万别省。模型生成的参数经常有类型问题，比如该传整数的传了字符串，该传数组的传了单个值。我一般用 Pydantic 做校验和转换，定义好 schema 后，传进来的数据自动校验，不合法就抛结构化错误，模型拿到错误后有机会重试。

from pydantic import BaseModel, ValidationError class InventoryInput(BaseModel): product_id: str warehouse: str | None = None def execute_skill(skill_name, raw_params): skill = SKILL_REGISTRY[skill_name] try: params = skill["input_model"](**raw_params) except ValidationError as e: return {"error": "invalid_params", "detail": str(e)} return skill["handler"](**params.dict())

这样一层封装，参数问题在入口就被拦住了，不会污染到业务逻辑。

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

6.1 技能匹配不准的三种典型表现

第一种是该触发不触发。用户明明问的是库存，系统却去调了别的技能。排查思路：先看关键词列表覆盖够不够，再看相似度阈值是不是设太高了。我遇到过一次，阈值设了零点九，结果“还有货吗”这种口语化表达匹配不上，降到零点八就好了。

第二种是不该触发乱触发。用户问天气，系统却调了库存技能。这通常是关键词太宽泛导致的，比如“查”这个字被多个技能共用。解决办法是把关键词写具体，或者引入否定词过滤。

第三种是多个技能同时触发。这倒不一定是坏事，有时候确实需要多个技能协作，但如果是不相关的技能被一起拉进来，就要检查描述之间是不是有语义重叠。

6.2 执行超时与资源占用的处理

超时问题我踩过最惨的一次，是一个技能调外部接口，对方挂了，请求一直不返回，整个智能体卡死。后来我强制给每个技能加了超时，用线程池或者异步任务实现，超时就中断并返回错误。超时时间设多少？我的经验是，纯本地计算设两秒，调外部接口设十秒，具体看接口的 P99 延迟再留点余量。

资源占用方面，要注意技能的并发数。如果多个任务同时跑，每个任务又调多个技能，线程数会爆炸。我一般用信号量控制并发上限，超过就排队，避免把机器拖垮。

6.3 技能版本升级引发的兼容问题

技能升级是必然的，但升级不能破坏已有调用。我的做法是版本号遵循语义化版本，主版本号变了才允许不兼容，而且旧版本要保留至少一个迭代周期。调度器在匹配时，默认用最新版，但如果任务上下文里指定了版本，就用指定版本。这样新老任务可以共存，迁移有缓冲期。

6.4 常见问题速查表

7. 我在实操中总结的几条经验

技能描述要站在“使用场景”角度写，不要站在“实现细节”角度写。这是我最想强调的一条。描述是给模型看的，模型关心的是“什么时候用”，不是“你怎么实现”。我见过太多描述写成“调用XX接口”，模型根本不知道什么时候该调。

阈值和关键词要拿真实数据调，不要拍脑袋。我一般会准备一批真实用户问法，跑一遍看匹配结果，根据准确率和召回率调整参数。这个过程可能要迭代几轮，但值得。

技能粒度要适中。太细了，技能数量爆炸，匹配成本高；太粗了，一个技能干太多事，复用性差。我的经验是，一个技能对应一个明确的业务动作，比如“查库存”是一个技能，“查库存并计算补货量”就该拆成两个。

错误信息要结构化，不要抛裸异常。模型拿到结构化错误后，有机会自我纠正，比如参数错了就重新生成参数，技能不存在就换个技能。裸异常模型看不懂，只能干瞪眼。

测试用例要覆盖边界情况。空输入、超长输入、特殊字符、并发调用，这些都得测。我吃过亏，一个技能在正常输入下跑得好好的，遇到空字符串直接崩了，线上才发现。

日志要记全。每次技能调用，输入、输出、耗时、是否命中缓存，都要记。出了问题，日志是唯一的线索。我一般用结构化日志，方便后续做分析和告警。

这套东西搭起来不算复杂，但细节很多。真正跑起来之后，你会发现最花时间的不是写技能，而是调匹配参数和处理各种边界情况。不过一旦跑顺了，后面加能力就是复制粘贴改改的事，那种顺畅感还是很值的。