1. 先把Agent技能化这件事说清楚
最近一段时间，“agent-skills”这个词在AI应用开发圈子里出现得越来越频繁。如果你关注过几个智能体项目，大概率见过类似的代码结构：一个skills目录，里面按功能拆了一堆子文件夹，每个文件夹里放着描述文件、执行脚本和参数校验规则。很多人第一反应是“这不就是工具函数吗”，但真正上手做过一轮之后会发现，技能化跟传统的函数封装完全是两码事——它解决的是大模型应用里一个非常要命的问题：如何让模型稳定、可预期地调用你准备好的能力。
我最早接触技能化改造，是因为一个很现实的痛点。当时手头有一个跨平台的数据处理系统，需要智能体自动完成数据清洗、格式转换、异常上报一系列操作。最初的做法是把所有逻辑写在一个大控制器里，模型拿到用户指令后，自己判断该走哪条分支。结果就是：指令稍微绕一点，模型就开始乱选路径，偶尔还会跳过必要的前置步骤，直接去执行后面的操作。调试了两周，整个人处于一种“不知道下一个用户问题会从哪里踹我一脚”的状态。
后来参考了技能化设计的思路，把整个系统拆成了十几个独立的技能模块，每个技能只做一件明确的事情，输入输出全部规范化。改造完之后，同样是那个模型，同样一批测试用例，成功率直接从七成出头拉到九成以上。而且后续加新功能也不再需要动主流程，只要按规范往技能库里塞一个新模块就行。这就是Agent技能化的核心价值：把不可控的模型自由发挥，变成可控的能力组合。
这篇文章里我会把技能化设计的完整思路、代码结构、注册机制、编排方式、踩坑排查全部过一遍，偏向工程落地。适合正在做智能体应用开发、被模型调用不稳定折磨过的人，也适合想从零开始搭一套技能库的开发者。内容不绑死任何具体框架，核心方法论可以直接迁移到你自己的项目里。
2. 技能化设计的关键拆解：不是把所有函数都塞进去就完事
2.1 技能的粒度——多大算合适，怎么判断边界
技能粒度是整个技能库设计里最容易被搞砸的地方，也是我最早栽跟头的地方。一开始我图省事，把一个大功能整个塞进一个技能里，表面上看技能数很少、结构干净，但实际用起来根本不是那么回事。举个例子，当时做了一个“数据处理”技能，内部包含读取文件、字段校验、格式转换、结果输出四步，模型只要调一次这个技能就能全跑完。听起来很高效，对吧？但真正的问题是，模型在处理用户问题时，经常只需要其中某一步，比如用户只问“这个文件里哪些字段是非空的”，模型依然会傻乎乎地把整个技能调起来，把所有流程跑一遍，浪费大量运行时长和token。
反过来，如果粒度切得太细，也会出问题。我之前试着把“读取文件”拆成“读取CSV”、“读取JSON”、“读取Excel”三个独立技能，结果模型面对一个格式不明确的文件时，会在三个技能之间反复犹豫，甚至连续调用两三个都失败。因为这个层面的决策对模型来说太细了，它根本不该在这个粒度上做判断。
我自己实践下来觉得，技能粒度的判断标准有三个，缺一不可：
- 技能必须对应一个完整的用户意图。比如“查询订单状态”是一个完整意图，而“拼接查询字符串”不是。
- 技能内部的处理流程要相对独立。别的技能不应该需要知道这个技能内部的中间状态。
- 技能的数量要控制在模型能“看见”的范围。我个人的经验是，暴露给模型直接调用的技能，单次任务中最好不超过几十个，再多模型的选择准确率会肉眼可见地下降。
这里有一个很关键的补充：技能库里可以有大量底层能力，但不是所有能力都需要暴露给模型。我后来把仓库分成了两层：一层是内部工具，只被其他技能调用，模型看不到；另一层才是真正注册给模型的技能。模型只需要在几十个技能里做选择，剩下的细节在技能内部消化掉。这个结构调整之后，选择准确率又上了一个台阶。
2.2 输入输出规范——让模型能够稳定地“理解”技能
技能的输入输出规范，决定了模型能不能正确使用这个技能。大模型本质上是在做模式匹配，如果你的输入参数设计得含糊、字段名有歧义、类型定义模糊，模型就会用各种奇怪的方式去填充它。我自己见过最离谱的一次，是给一个“发送邮件”技能定义了收件人参数，字段名叫to，类型是字符串。结果模型拿到一条“发给A、B和C三个人”的指令时，把三个名字用中文逗号连在一起塞进了一个字符串里，然后在技能内部解析时直接炸掉。
后来我总结了一套比较稳定的输入参数设计规则：
- 所有参数必须有明确的类型声明。能枚举的字段尽量用枚举值，让模型在有限选项里选，比让它自由填字符串可靠得多。
- 参数描述要写“对模型说的话”。比如一个日期参数，描述里写“用户提到的时间，格式为YYYY-MM-DD，如果用户只说‘下周一’请返回具体日期”要比只写“日期”两个字好用得多。因为模型是靠语义理解来填参的，你给它的信息越多，它填得越准。
- 避免让模型自己推断上下文里没有的信息。如果一个参数必须由前置步骤产生，那就应该把这个参数标记为“调用方注入”，并在技能描述里说明不允许模型自行猜测。
输出这边同样重要。最开始我的技能返回值设计得很随意，有时候返回纯文本，有时候返回JSON，有时候直接返回一个对象。结果就是模型拿到返回值后，经常不知道接下来该干什么。后来我统一了所有技能的返回结构，大体上分成三块：执行状态、结构化结果、面向用户的说明文本。结构化结果永远用JSON，状态码统一，成功和失败的返回值形态保持一致。这样模型在拿到任何一个技能的返回之后，都能用同一套逻辑去判断下一步动作。
2.3 命名与描述——技能说明文档是给模型读的，不是给人读的
这一点很容易被忽略。很多人写技能描述的时候，默认是写给同事看的，所以会出现“本模块提供数据清洗相关能力”这种说法。但事实是，技能描述是写给大模型看的prompt，它决定了模型什么时候该调这个技能、什么时候不该调。写得越具体、越贴近用户问题的表述方式，模型的调用准确率越高。
我举一个自己优化过的例子。修改前，一个技能描述是“对输入文本进行情感倾向分析”。看着没什么问题，但实际模型在遇到“帮我看看这条评论是不是在骂人”的时候，不会把“骂人”和“情感倾向分析”联系起来，于是选择不调用这个技能，自己硬答。优化后的描述是“分析一段文本的情感倾向，可用于判断评论是正面、负面还是中性；用户说‘帮我看看这条评论好不好’、‘这是不是在喷人’、‘顾客满意吗’时，调用本技能”。改完之后，类似问题的调用率明显上升。
命名也值得花点心思。我推荐技能名用“动词+对象”的短结构，比如analyze_sentiment、generate_report、parse_resume。动词让模型知道这个技能是干什么的，对象让模型知道它作用在什么东西上。尽量避免用抽象名词当名字，因为模型很难从抽象名词推断出具体动作。
提示：技能描述不是写一次就完事的。我习惯每周把模型漏调技能、错调技能的日志拉出来看一遍，凡是描述引发误会的，立刻改描述。技能描述是跟模型“磨合”出来的，不是一次成型的。
3. 技能注册机制与调用链路的底层逻辑
3.1 注册表设计——别让模型直接面对技能代码
技能注册表在整个架构里处于一个中间层的位置。它的作用是把散落在各个文件里的技能统一管理起来，给每个技能分配ID、名称、描述、输入输出schema，并向模型提供一个统一的调用入口。模型不直接接触技能实现代码，它只跟注册表暴露出来的接口打交道。
我常用的注册表结构是这样的，每个技能在注册时至少包含以下几个字段：
@dataclass class SkillMeta: skill_id: str # 唯一标识，如 "parse_resume" name: str # 展示名，如 "简历解析" description: str # 给模型看的调用说明 input_schema: dict # 输入参数JSON Schema output_schema: dict # 输出结果JSON Schema version: str # 技能版本号 enabled: bool # 是否注册给模型 executor: Callable # 实际执行函数 dependencies: list[str] # 依赖的其他技能/工具ID这个注册表的核心价值有两个。第一个是让模型可以“按目录查找”技能。每次请求进来时，系统把当前启用的技能元信息全部塞给模型，模型在这份目录里做选择。第二是让技能实现可以进行热更新。注册表指向的是执行器入口，执行器内部改代码不影响注册信息，只要保持输入输出规范不变就行。
需要注意的一点是，注册表元信息不是越多越好。完整的技能描述加JSON Schema，一个技能可能占掉几百个token，如果你有上百个技能，光技能清单就能把上下文窗口吃穿。所以我通常会对技能做两级暴露：一级是只放技能名和一句话描述，让模型做粗选；模型选中某个技能后，再把完整的输入输出schema注入上下文。这样既保证了模型能看见所有技能，又不会一次性占用太多上下文。
3.2 调用链路的三个环节：识别、选择、执行
一次技能调用从用户输入到最终执行，中间要经过三个环节。理解这三个环节，才能知道每个环节里该做什么优化。
第一个环节是“意图识别”。这个环节不直接调技能，它把用户的话翻译成一个意图描述。比如用户说“帮我查一下上个月的电费”，意图描述就是“查询指定时间段内的电费账单”。这一步可以由主模型来完成，也可以用一个轻量级分类模型单独处理。我个人的实践是，对于技能数量在十几个到几十个的场景，直接用主模型做意图识别就够了，不需要额外引入分类模型，省掉一条链路反而少一个出错的环节。
第二个环节是“技能选择”。模型根据意图描述和技能列表，选出最匹配的那个技能。这个环节最考验技能描述的准确性。很多时候模型选错技能不是因为模型笨，而是因为两个技能的描述有重叠，边界模糊。比如“查询账单”和“导出账单明细”，一个偏查询汇总，一个偏导出数据，如果描述里没有把边界说清楚，模型就可能选错。
第三个环节才是“执行”。执行阶段相对机械，系统根据模型填好的参数去调执行器，执行器跑完返回结果。但这里有一个容易被忽略的点：执行器运行时的异常信息，必须转换成模型能理解的语言返回。如果你的执行器抛出一个Python异常，直接把堆栈信息扔回去给模型看，模型十有八九看不懂，更不知道下一步该怎么办。我后来在所有执行器外层套了一层统一异常处理，把异常翻译成“技能执行失败，失败原因是XX，请尝试YY”这种结构化提示。
3.3 落地一个最简单的技能调用，长什么样
光讲概念容易飘，我直接给一个最小可运行的示例。假设我们要实现一个“获取当前天气”的技能，模型看到描述后，填充城市名参数，系统去调用天气接口，返回结果。
技能注册部分长这样：
weather_skill = SkillMeta( skill_id="get_weather", name="天气查询", description="查询指定城市当前的天气状况。用户问天气、温度、适不适合出门时调用本技能。", input_schema={ "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如‘北京’‘上海’。如果用户没有明确说城市，请先询问。" } }, "required": ["city"] }, output_schema={ "type": "object", "properties": { "temperature": {"type": "number"}, "condition": {"type": "string"}, "humidity": {"type": "number"} } }, version="1.0.0", enabled=True, executor=fetch_weather_executor, dependencies=[] )执行器部分长这样：
async def fetch_weather_executor(city: str) -> dict: # 这里实际调用的是天气服务的HTTP接口 # 不同服务商的API key、接口地址只需要写一次，后续技能复用 data = await weather_api.query(city=city) return { "temperature": data["temp"], "condition": data["weather_desc"], "humidity": data["humidity"] }这就是一个非常标准的单技能调用链路。在真实项目里，技能会比这个复杂得多，会涉及多参数校验、前置条件检查、外部服务依赖，但整体框架是一致的。先把这种最小链路跑通，再往里面加复杂度，比一上来就设计一个庞大的技能框架要稳妥得多。
4. 技能编排：从“单个技能”走向“复杂流程”
4.1 顺序执行模式——最基础也最常用的编排方式
当单个技能解决不了问题时，就需要多个技能按一定顺序配合。最简单的配合模式是顺序执行：技能A的输出，作为技能B的输入，一级级向下传递。这种模式适用于那些处理流程天然线性的场景，典型的就是数据处理任务。
拿我刚才提到的数据处理系统来说，一个典型的处理流程是：先用read_file技能读取原始文件，得到结构化数据；接着用validate_data技能检查字段完整性和类型正确性；然后交给transform_format技能做格式转换；最后用write_output技能把结果写出去。这四个技能按顺序执行，前一个的返回值直接作为后一个的参数输入。
顺序执行看着简单，但有一个关键设计要提前想清楚：技能之间的数据契约。A技能输出的字段名，必须和B技能期望输入的字段名完全一致。很多人开发时习惯各自为政，A技能返回的字段叫temperature_value，B技能却期望输入temp，对不上。这种问题在单技能场景里不会暴露，一旦做编排就会频繁卡壳。所以我在设计技能输出schema的时候会多花一点心思——每个技能的输出，就是它作为上游供给下游的标准数据格式。这个格式一旦定下来，所有消费这个输出的技能都按这个标准来接。
还有一个顺序执行里的常见问题：技能失败后要从哪里重跑。如果四个技能跑到第三步失败了，是整体重跑还是从第三步重跑？我的建议是尽量让技能具备“幂等”性质，也就是同一个输入，不管执行几次，结果都一致。这样重跑的时候就可以从失败点继续跑，不需要把前面成功的步骤也重新执行一遍。文件读取、数据校验这类纯计算操作实现幂等相对容易，但涉及到写外部系统（比如发消息、写数据库）时，就需要引入操作ID之类的机制来防止重复执行。
4.2 分支和并行——什么时候需要，怎么用而不失控
编排里稍微进阶一点的是分支和并行。分支的意思是，根据前置技能的返回结果，决定后续走哪条技能路径。比如一个客服工单处理系统，先调用classify_ticket技能判断工单类型，如果是“售后问题”就走退款流程，如果是“技术问题”就走工单指派流程。这种动态路由在复杂业务场景里几乎必然会出现。
实现分支的关键在于，系统要把前置技能的返回值解析成结构化的“决策信号”，而不是让模型凭感觉判断。我通常的做法是，在技能返回里单独设一个decision字段，专门存放给编排器看的决策结果。比如工单分类技能的返回里就包含"category": "after_sale"这样的结构化信息，编排器读取这个字段来决定下一步。决策逻辑写在代码里，不是让模型再读一遍技能结果去决策。模型在单一节点上做选择还勉强靠谱，连续多个节点上做选择就很容易累积错误，所以编排分支尽量代码化。
并行执行要更谨慎一些。并行能节省时间，但代价是系统复杂度大幅上升。你要处理并发请求的资源竞争、多个技能同时写一个共享状态时的冲突、部分成功部分失败的最终一致性。我自己刚开始做并行的时候踩过一个坑：两个并行技能同时向同一个用户记录追加标签，因为读写不是原子的，后写入的覆盖了先写入的，导致数据丢失。以后遇到这种共享资源的场景，我会先给数据加锁或者换成独立字段写入，避免并发覆盖。
并行真正适合的场景是那些互相之间没有依赖关系的任务。比如报告生成时，analyze_metrics和fetch_chart_data两个技能可以并行跑，因为它们互不依赖；但“先生成图表再插入报告”就只能是顺序执行。编排器在设计之初就应该有依赖检测能力，能判断两个技能之间是否存在数据依赖，有依赖的强制顺序，无依赖的才允许并行。
4.3 状态管理与失败恢复——编排真正难的地方
编排逻辑里最考验功底的部分，其实是状态管理和失败恢复。一次复杂的Agent执行可能涉及好几个技能、运行好几分钟，如果中间任何一步挂了，你都需要知道：现在执行到哪了、哪些步骤已完成、哪些状态需要回滚或补偿、下一步该从哪接。
我采用的方案是维护一份执行状态记录，这个记录贯穿整个编排过程。每次技能执行成功，就把它的输入输出摘要追加到这份记录里；每次技能执行失败，也把失败原因和当时的数据快照写进去。这样一方面能回溯整个执行过程，方便排查；另一方面也给失败恢复提供了依据。
失败恢复的策略需要根据技能类型区别对待。对于只读查询类技能，失败后直接重试通常没问题。对于写操作类技能，比如“发送邮件”“创建订单”，重试前必须要判断上一次调用到底成功没有——如果上一次其实已经成功，只是响应超时，重试就会造成重复发送。这类问题我的处理方法是在技能内部生成一个请求唯一ID，目标系统收到同一个ID的第二次请求时主动去重。这套机制在发出邮件、创建支付订单这些场景里实测非常管用，能挡住大多数重复执行的隐患。
失败恢复另一个关键是“部分成功”时的最终状态定义。比如六个技能里三个成功、三个失败，整个任务是算成功还是失败？这取决于业务语义。如果失败的是无关紧要的步骤（比如日志上报失败），任务可以继续；如果失败的是核心步骤（比如支付失败），任务就算失败并进入补偿流程。我建议每个编排器里都显式定义一个success_criteria，明确哪些步骤是强必需的、哪些是可以容忍失败的。没有这个定义，全局状态就是一个说不清的灰色地带。
5. 实操过程：从零搭一套技能库的完整记录
5.1 目录结构与加载规则——先搭骨架再添肉
我搭技能库的习惯是先把目录骨架定好，再往里填技能。一个清晰统一的目录结构，能让后续的技能维护省掉大量沟通成本。下面是我现在用的结构：
agent-skills/ ├── core/ # 核心运行框架：加载器、注册表、编排器 │ ├── registry.py │ ├── loader.py │ └── orchestrator.py ├── skills/ # 技能存放目录，一个子目录一个技能 │ ├── get_weather/ │ │ ├── SKILL.md # 技能描述（给模型看） │ │ ├── schema.json # 输入输出JSON Schema │ │ ├── executor.py # 执行逻辑 │ │ └── tests.py # 技能测试 │ ├── parse_resume/ │ ├── generate_report/ │ └── ... ├── tools/ # 内部工具，只被技能调用，不暴露给模型 │ ├── http_client.py │ ├── token_counter.py │ └── ... └── logs/ # 调用日志与调试记录这个结构的核心原则是“一个技能一个目录，内部自成一体”。每个技能目录下必须包含描述文件、schema文件、执行器和测试。这样的好处是：新增技能只需要复制一个目录模板，改完四个文件，注册表扫描到新目录后自动加载，主流程零改动。
加载器的实现逻辑其实不复杂。启动时扫描skills/下所有目录，读取每个目录里的SKILL.md、schema.json，把执行器函数动态导入，然后合并成一份技能清单交给注册表。有一点要提醒：执行器必须是纯函数式的入口，尽量不要在模块加载时执行副作用代码，否则热重载和并发调用都会出问题。
5.2 技能元信息清单——写描述文件容易忽略什么
写SKILL.md是技能开发里门槛最低、但影响最大的一件事。我见过很多技能，代码写得没问题，但描述文件写得太差，导致模型根本不知道该调它。这里我给出一个可以照抄的描述文件模板：
# 技能名称 ## 触发条件 当用户出现以下意图时，必须调用本技能： - 用户询问XX信息 - 用户要求执行XX操作 - 用户反馈XX问题时 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | param1 | string | 是 | 参数含义及取值示例 | ## 执行结果 成功时返回XX结构，失败时返回错误码XXXX。 ## 注意事项 - 如果用户没有给参数，必须先询问，不能擅自假设 - 本技能只处理XX，不处理YY模板里，“触发条件”写的是用户可能的口语化表达，方便模型做匹配；“注意事项”写的是边界约束，防止模型越权执行。这两块内容是我经验中最影响调用效果的部分，值得多花时间打磨。
有一个细节很多新手会忽略：描述文件里的参数表格，字段名要和schema.json里的完全一致。如果两边写的不一样，模型读取了描述文件后，填了描述文件里的字段名，却被schema拦截下来，就会出现调用失败。这类问题排查起来非常隐蔽，我建议在加载器里加一个校验逻辑，启动时自动比对SKILL.md和schema.json的字段一致性，不一致直接报错，把问题提前暴露在开发阶段。
5.3 一个完整技能的实现过程——以解析简历为例
空讲规范不如走一遍完整流程。我拿一个实际做过的技能——简历解析——来演示从注册到执行的完整实现过程，你照着这个流程可以复刻到自己的项目里。
第一步，确定技能边界。简历解析要做的输入是一份PDF文件，输出是结构化的候选人信息，包括姓名、工作经历、教育背景、技能标签。这个边界很清晰，不需要再往下拆，直接作为一个完整技能注册。
第二步，写schema。输入参数定义两个：一个是文件路径（或上传后的临时文件ID），一个是是否启用OCR增强识别。输出参数定义成简历的标准字段结构。
{ "input_schema": { "type": "object", "properties": { "file_id": { "type": "string", "description": "待解析的简历文件在系统内的临时ID" }, "use_ocr": { "type": "boolean", "description": "是否对扫描件启用OCR识别，默认false", "default": false } }, "required": ["file_id"] }, "output_schema": { "type": "object", "properties": { "candidate_name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}, "work_experience": {"type": "array"}, "education": {"type": "array"}, "skill_tags": {"type": "array"} } } }第三步，写执行器。执行器内部的处理流程是：先检查文件是否存在；然后判断是文本型PDF还是扫描件；如果是扫描件且use_ocr为true，就调OCR服务做识别；不管是哪种情况，最终都进入解析逻辑提取字段；最后把所有字段打包成输出结构返回。如果中间任何一步失败，直接抛一个技能层级的异常，由外层统一处理。
第四步，写测试。测试用例要覆盖正常简历、带扫描页的简历、内容很短的简历、格式异常的文件至少四种类型。我习惯在测试里直接断言输出结构的关键字段，而不是只看“有没有报错”。比如给一个明确包含“姓名：张三”的测试文件，断言输出里candidate_name必须是“张三”，这样才真正锁定了解析质量。
5.4 注册、调试与观察——怎么知道技能好使不好使
技能写完之后，最关键的一步是回到真实场景里去观察模型的实际调用情况。我每次刚接入一个新技能时，都会用一套固定的调试方法：
首先做“直呼测试”，给模型一条非常明确要调这个技能的指令，看它能不能正确选中目标技能。这个测试不过，一定是技能描述或命名有问题。接着做“近义测试”，用同义但不同表达方式的指令去调同一个技能，比如“解析一下这份简历”和“帮我看看这个候选人的信息”，看模型能否都识别为同一个技能。这个测试没过，说明描述里的触发条件覆盖不够。
然后做“边界测试”，给一条理论上不应该调这个技能的指令，看模型会不会误调。比如给“帮我写一份简历模板”，看它会不会错误地调用简历解析技能。如果误调了，边界描述没写清楚。
这些测试跑完，我会把结果记录到技能目录里的tests.py中，留下完整的调试轨迹。等技能在线上跑了一段时间后，我还会安排一次集中的日志分析，统计每个技能的实际调用次数、成功率和平均耗时。调用次数几乎为零的技能，说明它的存在对模型来说不可见，要么是描述问题，要么是这个技能本身就多余，需要重点排查。
注意：一个技能只有在真实流量里被验证过的调用率，才算数。开发环境里所有技能都“能用”，不代表模型在真实环境下“会想起用它”。
6. 常见问题与排查技巧实录
6.1 模型就是不调用技能，怎么办
这是所有技能化改造里最让人头疼的问题——技能写得没问题，注册表也没问题，手动调试也能跑通，但模型在实际对话中就是绕过技能，自己瞎回答。遇到这种情况，我总结了一套排查顺序，按顺序走下来绝大多数问题都能定位。
第一步查描述。看技能描述里是否包含了用户真实口语里的关键词。模型遵循的是语义匹配，不是严格的关键词匹配。描述里写的触发条件越贴近用户的真实表达，匹配准确率越高。我习惯找几个真实用户问题原话，直接贴进描述里作为示例。比如用户说的是“这份简历看起来不太靠谱，帮我看看”，描述里就写“用户对简历内容质量存疑，期望分析简历中的疑点”之类的话。
第二步查上下文位置。如果技能描述在系统提示里排得离模型最近的任务说明太远，模型可能会忽略掉。尤其是当系统里同时塞了很长的人格设定、行为规范时，技能清单被挤到中间部位，模型对它的注意力会显著下降。我在实际项目中试过把技能清单挪到系统提示的最末尾，就在“现在开始处理用户消息”之前，整体调用率有明显提升。这算是位置带来的影响，看着玄学，实际是上下文注意力分布的现实情况。
第三步查竞争对手。如果某个问题有多个技能都可能命中，描述之间又有重叠，模型就会随机选一个或干脆不选。这时候要回头把重叠技能的边界写清楚，或者直接合并成一个技能，减少选择难度。我在一个案例里把三个边界模糊的查询类技能合并成了一个带query_type参数的技能，调用率反而上升了——因为在模型看来，选一个技能填个参数，比在三个技能里挑一个，判断成本低得多。
还有一种很常见的情况是模型把技能调用和自由回答混在一起，以为调了技能就可以直接输出结果，导致日志里根本没有调用记录。这通常是系统提示里对“什么时候必须调用技能”的约束写得太弱。我处理的方式是加一条硬性指令：“所有涉及XX的请求，必须先调用对应技能获取数据，再基于数据回答；禁止在未调用技能的情况下直接作答。”指令是强制性的措辞，不要用“可以调用”这类商量的语气。
6.2 技能之间互相干扰的几种典型场景
技能数量一旦超过二十个，互相干扰的问题就会浮出水面。最典型的是同名参数冲突。比如analyze_sentiment和analyze_topic两个技能都需要一个text参数，但第一个期望的是用户原话，第二个期望的是清洗后的文本。当模型在同一个会话里连续调用这两个技能时，很容易把第一个技能的返回值再当作第二个技能的输入，导致参数错位。
这种问题的根源是技能之间的数据契约不统一。我通常会用两种方式解决：第一种是给参数加语义前缀，比如source_text和clean_text，让模型能区分两者；第二种是让下游技能内部做一次输入检查，发现传入内容不符合预期时，主动报错而不是带病执行。前者靠规范，后者靠防御。
另一个常见干扰是会话上下文污染。当模型在一个长会话里先调用了一个技能，拿到返回结果，这些结果会残留在上下文里。等它接着调下一个技能时，如果下一个技能的描述不够精确，模型会误把上一个技能的返回值当成用户的最新意图来处理。我有一个印象深刻的案例：用户先问了天气，模型返回了天气结果；用户紧接着说“那明天呢”，模型把这个“明天”跟天气关联起来，但下一个需要调用的却是日历查询技能，模型被之前的天气结果带偏了，没能正确转向。这一类问题主要靠系统提示里的“技能边界重置”来缓解，就是在每次技能调用结束、准备处理新的用户消息时，提醒模型重新判断意图，不依赖前一轮的结果。
6.3 性能和成本问题——技能越多越要留意
技能化设计在功能和稳定上有好处，但代价也很直观：token消耗和响应延迟都会上升。每次请求要把全部启用的技能描述都发送给模型，几十个技能的描述加起来可能就是几千token的固定开销。这个开销随着技能数量线性增长，解药是前面提到的两级暴露机制，或者在应用层面做初步意图路由，只把相关的技能子集注入上下文。
延迟方面，技能编排如果设计得不好，会把本来可以并行的步骤串行化，导致整体响应时间翻倍。我通过给每个技能的执行时间加上自动统计，定期拉出耗时排行榜，把那些单次执行超过3秒的技能列为重点优化对象。优化手段包括启用缓存、减少不必要的重试、把高延迟的外部调用放到后台异步执行。
缓存是技能化场景里性价比最高的优化手段，没有之一。对于查询类技能，只要输入参数完全相同、数据源在短时间内不会变化，就可以直接返回缓存结果。我在系统里做了两个层级的缓存：进程内缓存应对高频重复调用，外部缓存应对跨进程共享场景。缓存命中一次，省下的是一整个外部服务的往返时间加token开销。这里要注意的是，缓存过期时间不能一概而论，要结合数据源的更新频率设置。
6.4 技能版本升级时容易踩的兼容性问题
技能一旦上线，后面必然要迭代升级。版本升级最怕的不是改逻辑，而是改输入输出结构。你在新版本里加了一个必填参数，下游所有依赖这个技能的编排流程如果在传参时没跟上，就会集体失败；你把某个输出字段改名，凡是消费这个字段的技能都会静默出错。
我踩过一次比较深的坑：把一个“生成报表”技能的summary输出字段重命名为report_summary，当时以为全局搜索替换一下就没事了，结果有一个编排流程里是通过字符串拼接来引用这个字段的，搜索时没有匹配到，导致线上运行时那个流程一直拿到空值，还查了半天才定位。
现在的做法是在技能schema里增加一个兼容性标注：哪些字段是“不能变”的稳定字段，哪些是“可以扩展”的追加字段。一旦有变更，先走一个内部审查流程，把该技能的上下游全部拎出来检查一遍再上。加载器这边还会在启动时做一次静态依赖图校验，凡是发现有别的技能或编排引用了某个不存在的字段，直接启动失败，不让问题留到运行时。
7. 关于“技能化”这个方向的一些个人经验
技能化改造做了一年多，回头看，这个思路之所以有效，本质原因在于它让大模型从“既要理解问题、又要记住实现细节、还要自己编排动作”的重担里解放了出来。模型只需要做它最擅长的事情——理解意图、选择方案；而具体怎么实现、参数怎么校验、异常怎么兜底，通通下沉到确定性的代码里去。这两者各司其职，整个应用才变得可控、可测、可维护。
顺着这个方向往后想，技能库是可以不断生长的。一个项目沉淀下来的技能，稍微抽象一下就能复用到另一个项目。比如“解析简历”抽象成“解析文档并提取字段”，“发送邮件”抽象成“通过模板生成内容并调用外部接口发送”，到了新项目里借用起来非常顺手。技能库本质上是一个项目里最值得积累的资产之一，它比某个具体的Agent逻辑更能保值。
最后再分享一个小技巧：给技能库建一个变更日志，记录每次新增、修改、删除技能的动机。三个月后再回头翻这个日志，你会惊讶地发现很多当初拍脑袋做的决策，后来都被证明是错的。这个日志帮你记住了当时的判断依据，下一次设计新技能时你就不容易沿着错误的方向再来一遍。我自己就是靠着这份日志，一步一步把技能库从混乱整理到了今天的相对有序。
