直接进入正题。
这两年做大模型应用，最深的体会就是：模型能力是一回事，把模型变成一个能干活的Agent是另一回事。很多团队拿着一个很强的基座模型，做出来的Demo效果也不错，但一上真实业务就露馅——要么工具调用混乱，要么技能复用性差，换一个场景就要重写。我在做内部平台的时候，也踩过类似的坑。后来把整个体系重新梳理了一遍，沉淀出一套叫“agent-skills”的技能管理方案，跑通之后效果提升非常明显。这篇就把这套东西的设计思路、核心实现和踩坑记录完整拆一遍，希望能帮到正在做Agent工程化的团队。
这套方案解决的核心问题其实就三个：技能怎么定义、技能怎么注册、技能怎么被Agent正确调用。听起来简单，但把这些理清楚，你就从“能用”跨到了“好用”。下面按我实际落地的顺序来拆。
1. 从需求到架构：agent-skills 到底解决什么问题
1.1 为什么Agent需要一套“技能体系”
先聊一个很实际的现象。早期做Agent，大家习惯把所有的能力逻辑直接写死在Prompt里。比如给模型一段话：“你可以调用A接口、B接口、C接口，它们的入参是XXX”，然后靠模型自己理解。这种做法在Demo阶段完全没问题，模型偶尔也能蒙对，但一旦接口数量超过五个，或者业务逻辑开始变复杂，问题就全冒出来了。
最典型的问题是接口描述过长。LLM的上下文窗口有限，你把十几个接口的详细文档全塞进Prompt，留给业务上下文的空间就所剩无几。而且模型在长文本里找信息时会出现“注意力稀释”，经常漏掉关键参数说明，导致调用参数填错。另一个问题是技能之间没有边界：当你需要给Agent新增一个能力时，只能继续往Prompt里塞描述，Prompt越来越长，模型的行为越来越不稳定。
“agent-skills”的思路就是把这些散落的能力收敛成一个可注册、可检索、可独立维护的技能库。每个技能是一个自包含的模块——用自己的描述、自己的参数Schema、自己的执行逻辑。Agent运行的时候，不是“看到”所有技能，而是先根据用户意图检索最相关的几个技能，再决定调用哪个。这个过程类似人类做事：你不会把菜谱全背下来再做饭，而是想做红烧肉的时候才去翻红烧肉的做法。
这个设计的收益是立竿见影的：
- Prompt大幅瘦身，模型只需要处理与当前任务相关的技能描述；
- 技能可以独立迭代，新增技能不影响已有技能，改一个技能也不用动Agent的主流程；
- 复用性变强，一套技能库可以服务多个Agent，就像同一个工具包给不同的人用。
1.2 整体设计思路与选型考量
确定要建技能体系后，我面临的第一个选型问题是：技能以什么形式存在。
市面上常见的方案有三种。第一种是纯代码函数注册，把每个技能写成一个函数，再用装饰器或者配置文件做映射。优点是性能好、类型安全、容易测试；缺点是灵活度稍差，动态加技能需要重新部署或者走热加载。
第二种是“SQL/规则+执行器”方案，把技能定义存在数据库里，运行时动态加载。这种方案适合有后台管理系统、运营需要经常调整技能的团队，但多了一层查询开销，还需要处理缓存一致性问题。
第三种是“配置文件+代码实现”的混合方案：技能的元信息（名称、描述、参数Schema）用JSON或YAML维护，执行逻辑仍是代码函数。这是我最推荐的方式，因为元信息与实现逻辑分离，既方便Agent读取和检索，又保留了代码的可维护性。
我最终选的就是混合方案。技能目录结构大概是这样的：
skills/ ├── calculator/ # 技能唯一标识 │ ├── skill.yaml # 技能元信息（描述、参数Schema） │ ├── __init__.py │ └── handler.py # 执行逻辑 ├── weather_query/ │ ├── skill.yaml │ ├── __init__.py │ └── handler.py └── registry.json # 技能全局注册表每个技能目录里，skill.yaml是给LLM和检索器看的，handler.py是给执行器跑的。这样不同角色看到的信息不一样，但都围绕同一个技能ID，不会出现各说各话的情况。
选型上还有一个值得注意的点：技能描述的语言和格式要做到一定程度上的统一。我在第一版里让每个技能的编写者自由发挥，结果有的写得很口语化，有的写得很技术化，检索召回时效果差别很大。后来定了模板，描述里必须包含“技能用途”“适用场景”“使用示例”三个部分，召回准确率才稳下来。
2. 核心细节解析与实操要点
2.1 技能的定义与描述规范
技能定义是整个体系的地基。如果描述写不好，后面检索、调用、参数映射全都会受影响。我在这个环节花的时间最多，反复改了四版才定下最终的规范。
一个标准的技能定义包含五个部分：技能ID、技能名称、描述、参数Schema、执行入口。其中最容易出问题的是描述部分。描述既不能太短（信息量不足，模型不知道什么时候该用），也不能太长（占用上下文，且容易引入噪音）。
我最终采用的描述模板是：
name: "查询实时天气" description: | 获取指定城市的实时天气信息，包括温度、湿度、风力、天气现象。 当用户提到“今天天气怎样”“XX市冷不冷”“要不要带伞”等意图时使用。 示例: "查询北京市现在的天气" -> 参数 {"city": "北京"} 说明: 仅支持国内主要城市，暂不支持海外城市。 parameters: - name: city type: string required: true description: "城市名称，需去掉‘市’后缀，例如‘北京’而不是‘北京市’"这个模板里最关键的是“示例”和“说明”两行。示例给模型提供了一个具体的映射参考，说明行则提前告诉模型边界条件，避免模型在参数上自作主张。实际测试下来，加了这两行之后，参数正确率提高了大约三成。
参数Schema的定义同样有讲究。我建议尽量用简单的类型，少用嵌套结构。LLM在生成参数时，对扁平结构的把握要远好于深层嵌套。如果一个技能确实需要复杂的输入，可以在执行逻辑里做二次加工，而不是把复杂度直接暴露给模型。
2.2 工具接口与执行层的边界
技能体系里最容易混淆的是“接口”和“执行层”的关系。很多人觉得技能就是一个API封装，Agent调用技能就等于调API。这个理解在简单场景下没错，但在复杂业务里会出问题。
我给“agent-skills”定的边界是：技能层负责理解意图、组装参数、编排逻辑，执行层负责真正干活。举个例子，一个“订会议室”的技能，它的执行流程可能是：先查空闲会议室，再比对参会人数，然后提交预订，最后发通知。这里面涉及多个底层API的调用，但站在Agent的角度，它只需要知道“我有个订会议室的技能，给我时间和人数就行”。技能本身是一段编排逻辑，而不是一个单一API。
这样设计的直接好处是Agent的认知负担大大降低。它不需要记住每个API的参数细节，只需要理解技能的语义。同时，开发者可以在技能内部做一些容错处理——比如某个API临时挂了，技能可以自动走备用通道，而Agent完全感知不到。这相当于把工程的复杂性封装在了技能内部，给Agent留出一个干净的接口面。
不过这里要提醒一句：技能的粒度要适中。太粗的技能（比如一个“处理订单”技能包含从下单到售后全流程）会让模型难以判断该不该调用；太细的技能（比如一个“获取用户ID”的技能）则会让流程碎片化，编排成本非常高。我实践下来比较合适的粒度是：一个技能对应一个完整可交付的业务动作，用户的一句话意图就能对应上。
2.3 上下文管理与记忆机制
技能体系跑起来之后，我们很快遇到第二个瓶颈：Agent在多轮对话中怎么管理上下文。技能本身是无状态的，但实际业务几乎都有状态——用户在前面说过自己的公司名，后面订会议室就不应该再问一遍。
我的做法是把上下文拆成三层：会话层、用户层、技能执行层。会话层保存当前对话的短期记忆，比如用户刚才提到了哪个需求；用户层保存用户的长期属性，比如常用城市、公司组织架构；技能执行层保存某次技能调用的过程和结果，便于后续回溯。
这个三层结构映射到代码上，就是一个统一上下文对象，技能在运行时可以从上下文里读取需要的信息，也可以把执行结果写回去。这样可以避免“每个技能都自己维护状态”导致的脏数据问题。
实操中还有一个容易忽略的点：技能的响应结果需要做结构化归档。很多Agent只是把技能返回的一串文本直接丢给LLM生成回复，这会导致LLM在后续追问时没有可用的结构化信息。我要求所有技能返回一个JSON对象，包含status、data、message等字段，再由Agent决定如何转述给用户。这样既保留了信息的完整性，又给LLM提供了明确的加工空间。
3. 实操过程与核心环节实现
3.1 技能注册与加载流程
技能注册是整个体系的入口。我把它设计成一个扫描-校验-注册的三步流程，全部自动化。
第一步是扫描，即启动时遍历skills目录下的所有子目录，找到每个子目录里的skill.yaml。第二步是校验，检查YAML的格式是否合规、参数Schema是否完整、执行入口函数是否存在、技能ID是否唯一。校验不通过的直接跳过并输出告警日志，而不是让整个服务崩溃。第三步是注册，把通过校验的技能加载到内存中的技能注册表里，同时为每个技能建好索引，便于后续检索。
这一步的代码结构大概长这样：
import yaml from pathlib import Path from typing import Dict, Any class SkillRegistry: def __init__(self): self._skills: Dict[str, Any] = {} self._index: Dict[str, list] = {} def load_from_disk(self, skills_dir: str): skill_roots = Path(skills_dir).iterdir() for skill_root in skill_roots: meta_path = skill_root / "skill.yaml" if not meta_path.exists(): continue with open(meta_path, "r", encoding="utf-8") as f: meta = yaml.safe_load(f) errors = self._validate(meta, skill_root) if errors: print(f"[skill-registry] skill {skill_root.name} 校验失败: {errors}") continue self._register(meta, skill_root) print(f"[skill-registry] skill {meta['name']} 已注册")校验逻辑是关键，不能省。我遇到过几次线上事故，都是因为某个技能改了YAML格式但没跑测试直接上线，导致整个注册表加载失败。增加校验后，格式问题在注册阶段就被拦住了，对线上服务零影响。
3.2 技能调用的完整链路
技能调用链路是“agent-skills”的核心。我拆成五个环节：意图识别、技能检索、参数填充、执行校验、结果回填。
意图识别负责把用户输入映射到一个候选技能集合。这一步我用了两路策略：一路是LLM基于用户输入做语义匹配，另一路是关键词做粗筛兜底。两路结果做并集后进入下一步。
技能检索负责从候选集合里挑出最合适的技能。这里的核心是计算用户意图和技能描述之间的相似度。第一版我用的是向量检索，效果还行但偶尔召回不准确；第二版改成“关键词粗筛+向量精排”，先通过规则快速过滤掉明显不相关的技能，再对剩下的做向量相似度计算。实测之后，P@5的准确率从71%提升到了88%，这个提升对最终效果影响非常明显。
参数填充是最容易出问题的环节。LLM生成的参数经常出现格式错误、缺字段、多余字段等情况。我的做法是：先让LLM按技能的参数Schema生成JSON，然后做一次严格校验，不通过的做一轮修复。修复仍然失败就把控制权交回Agent，让Agent追问用户补充信息，而不是强行调用技能。
执行校验在真正调用handler之前，先检查前置条件是否满足。比如某个技能要求用户必须先登录，或者某个技能需要某个上游服务可用，校验不过直接返回错误，避免技能内部跑了半天才发现环境不对。
结果回填是整个链路的收尾。技能执行后返回结构化JSON，Agent基于这个JSON组织语言回复用户。我在这个环节特别强调“数据要完整透传”，不要把技能返回的结果擅自截断，因为后续追问很可能需要这些数据。
3.3 参数校验与错误兜底
参数校验这块值得单拎出来讲，因为它是Agent稳定性最关键的屏障。LLM生成参数天然有不确定性，同样的输入，十次可能有八次正确，两次出小差错。如果没有校验和兜底，那两次就会表现为线上偶发故障，排查起来非常痛苦。
我设计了三级校验机制。第一级是格式校验，检查JSON结构是否合法、类型是否正确——字符串不能给成数字，必填字段不能缺失。第二级是逻辑校验，检查参数值是否在合理范围内——比如查天气的城市名是否在支持列表里，订会议室的时长是否超过了允许上限。第三级是执行校验，在技能真正执行业务动作之前，再做一次前置条件确认。
每一级校验失败后都有对应的兜底策略：格式校验失败就重新生成参数；逻辑校验失败则尝试做归一化处理（比如把“北京市”清洗为“北京”）；执行校验失败则直接返回友好错误，让Agent引导用户修改请求。
这套机制上线后，一个我们统计的数据是：技能调用的整体失败率从最初的12%降到了4%以内，其中参数问题导致的失败占比从8%降到了1.5%。
4. 常见问题与排查技巧实录
4.1 技能失效的典型场景与定位思路
技能失效是运行中最常见的问题，表现形式有很多种：Agent该调用技能却不调用、调用了技能但参数填错、技能执行了但结果不符合预期。每种情况的排查思路都不一样。
第一种“该调用却不调用”，大概率是技能描述写得不好，模型不知道这个技能能干什么。排查方法是检索召回日志，看看目标技能有没有进入候选集。如果根本没被召回，问题出在描述；如果召回了但最终没选上，问题出在用户意图和技能语义的匹配度。
第二种“参数填错”，主要是参数Schema和描述不一致，或者是描述里的示例太少、太偏。排查方法是翻调用日志，看模型实际生成的参数和期望值的偏差模式。如果总是某个字段填错，大概率是字段描述不够明确，或者示例里没覆盖到那种表达方式。
第三种“技能执行但结果不对”，问题往往在技能内部逻辑，而不是Agent层。排查手法是先绕开Agent，直接调用技能的手动调试入口，看技能本身有没有问题。技能没问题再看是不是上游依赖服务返回了脏数据。
4.2 上下文超限与模型幻觉的处理
做Agent最烦的就是上下文超限和模型幻觉。上下文超限的根因是：技能召回的数量太多，导致每个技能的描述都被塞进了Prompt。我之前遇到过一个极端情况，一次用户请求召回了八个技能，Prompt里光技能描述就占了六千多个token，用户输入只有几十个token——这明显不合理。
处理方法是限制召回数量，并且给每个技能的描述设置token预算。我最终的策略是：召回数量上限为3个，每个技能描述压缩到300 token以内。如果检索结果确实有多个技能都相关，我会让模型自己做一次挑选，而不是把所有候选都喂进去。
模型幻觉更多是提示词层面的问题。同一个技能，有些描述方式会让模型“一本正经地编参数”。比如技能说明书里没写清楚参数约束，模型就会基于常识脑补。解决思路是在描述里主动写出边界条件，明确告诉模型“哪些情况不要调用这个技能”“哪些参数必须由用户提供”。
4.3 技能冲突与优先级管理
技能多起来之后，冲突不可避免。最常见的冲突是两个技能描述相似，模型不知道该选哪个。比如“查天气”和“查空气质量”，用户在说“北京今天空气怎么样”时，两个技能都有可能被召回。
我的处理方案是给技能增加“优先级”和“适用意图”两个字段。优先级用于检索结果并列时快速决策，适用意图则写成“当用户关心PM2.5、AQI、健康建议时选本技能”。本质上就是让技能明确自己的边界，而不是把选择难题全抛给模型。
实操中还有个细节：技能更新之后，索引要同步刷新。我踩过坑，技能描述改了但检索索引没更新，导致新描述始终没生效。后来在技能注册流程里加了版本号机制，每次描述变更都递增版本号，索引构建时自动检测。
另外，我强烈建议在开发阶段为技能体系搭建一个调试面板。它至少应展示：当前召回候选、召回理由、LLM生成的参数、校验是否通过、执行耗时、返回结果。有了这个面板，排查问题的效率能提升好几倍。很多团队忽略了这个基础设施，遇到问题全靠猜，最后把时间浪费在重复试验上。
5. 写在最后的一些建议
这套“agent-skills”方案在我自己的项目里已经稳定运行了三个多月，支撑了十几个技能的动态注册和调用。我个人最大的体会是：Agent工程化不是把模型调通就完了，真正的门槛在模型之外——如何组织好技能、管好上下文、守住校验和兜底的底线。
如果你现在正准备做Agent类项目，我的建议是先从小规模的技能库开始。别一上来就设计十几二十个技能，那会让你的调试成本失控。先选三五个覆盖核心场景的技能，把注册、检索、调用、校验这条链路跑通，再去扩充。链路稳了，加技能只是往里填东西而已；链路不稳，技能越多，坑越多。
还有一点想强调的是：技能描述是给模型看的“产品文档”。你花时间把描述写得越清晰、越精准，模型的调用成功率就越高。很多时候，与其跑十次实验调参数，不如静下心来把技能描述再打磨一遍，效果可能来得更快。
最后分享一个小技巧：在技能返回结果里加一个hint字段，让技能在返回数据的同时，给Agent留一句“建议的回复口径”。比如天气技能返回时带上“用户询问温度时建议先说体感温度再说具体数值”，这个hint能让Agent的回复风格更贴近业务预期。不需要很复杂，但效果非常微妙。这些细节堆叠起来，用户的体感差异就会很明显了。
