agent-skills实战：从单体Prompt到智能体技能模块化设计

最近在折腾一个智能体项目的时候，踩了这么个坑：同一个能力，换了个场景就失效；同一个技能，换个说法就调用不到；Prompt写了一长串，结果模型该漏的还是漏。直到我把整个结构从“一段完整的系统提示词”拆成“一组可独立描述、独立调用的技能模块”，事情才真正开始变得可控。这篇文章想分享的，就是围绕agent-skills这个思路做智能体技能模块化的完整经验：它解决的是什么问题、技能描述怎么写才有效、调度机制怎么设计、以及我在实际项目里踩过的那些坑和最终的排查链路。

agent-skills本质上不是一个具体的技术框架，而是一种设计思路：把智能体的能力拆成若干个边界清晰、描述精准、可被动态调用的技能单元。这个思路适合所有正在做AI Agent应用、想把多轮对话里的复杂行为拆解清楚的人，不管是做客服机器人、代码助手还是智能工作流编排，都会有参考价值。

1. agent-skills到底是什么：从单体Prompt到技能模块化的转变

1.1 单体Prompt的痛点：看起来能用，实际很脆弱

最早我做智能体的时候，习惯把所有指令塞进一段系统Prompt里。比如做一个“文件管理助手”，我会写：

你是一个文件管理助手，支持以下操作：列出文件夹内容、读取文件、写入文件、删除文件、重命名文件。当用户说要列出文件夹时，执行list_files工具；读取文件时要先检查权限；写入文件时要确认路径存在……

这段Prompt在Demo阶段跑得很顺，但一旦场景复杂起来，问题就集中暴露了：

• 指令冲突：文件读取的安全规则如果和写入规则有重叠，模型在处理跨界任务时很容易混乱，不知道该优先遵守哪条。
• 工具选择不稳：用户换一种说法描述需求（比如“帮我看看这个目录里有什么”），模型可能就不知道该不该调用list_files了。
• 排障困难：任务失败时，你很难判断是Prompt写得不够清楚，还是工具本身返回了问题——没有独立的技能边界，所有东西搅在一起。

这类问题的根子在于：单体Prompt把“能力描述”和“调用策略”耦合在了一起，模型每一次推理都必须从一大段话里提取指令，再映射到具体的工具行为。一旦指令变多，注意力分配就会出偏差。

1.2 技能模块化的核心思想：每个技能都是一个独立单元

agent-skills的做法不一样。它把智能体的能力拆成一个个独立的技能单元，每个技能单元包含：

• 技能名称：一个稳定的、不易混淆的标识。
• 技能描述：说明这个技能能做什么、在什么条件下用、有什么限制。
• 调用参数：技能需要的输入，以及这些输入的类型和约束。
• 执行逻辑：实际执行操作的代码、函数或子Agent。

模块之间保持低耦合。模型不是从一大段指令里去搜自己该干什么，而是先看到一份“技能清单”，每个技能都自带“何时使用”的提示，然后根据用户意图去匹配。

我这样比喻：单体Prompt像是一个什锦大礼包，里面什么都有，但你要找一个特定零件，得把整包倒出来翻；技能模块化像是一个工具箱，每种工具挂在自己的位置上，标签清晰，取用的时候只取需要的部分。

1.3 这个设计直接带来的四个好处

第一，可靠性显著提升。技能模块之间互不干扰，每个技能的触发条件独立描述，模型不会因为上下文中有一段无关指令而误判。我实测过，同一套技能的调用准确率大概提升了20%以上，尤其是多轮对话场景。

第二，可维护性变强。技能是独立维护的，改读取文件的权限规则，不需要动写入文件的描述。在单体Prompt里，任何一处改动都可能引发蝴蝶效应。

第三，可扩展性变好。新增一个技能就是新增一个独立模块，不需要回头修改系统提示词的整体结构。这对经常要迭代功能的项目很重要。

第四，可观测性提升。因为每个技能都有独立入口和出口，日志里能清楚看到哪个技能被调用了、返回了什么、为什么失败。这个问题在单体Prompt时代几乎是不可Debug的。

2. 技能描述的质量决定Agent的天花板：描述词编写方法论

2.1 模型靠什么选择技能：描述的匹配精度

在技能模块化的架构里，模型的“路线选择”完全依赖技能描述。可以这样理解：技能描述就是模型在决策树每个节点上看到的“路牌”，路牌写得不清楚，模型就会迷路。

比如一个技能叫“整理待办事项”，描述如果写成：

将用户的待办事项进行整理。

这个描述太模糊。它没有说清楚“整理”到底是什么动作——是排序？归类？去重？还是生成提醒？模型很可能把它和另一个技能“创建待办事项”搞混。

好的技能描述至少应该包含以下维度：

• 触发条件：什么场景下应当调用这个技能。写得越具体，误触率越低。
• 能力边界：这个技能能做什么、不能做什么。边界越清晰，模型越容易做排除。
• 输入输出：它需要什么参数，会产出什么结果。
• 典型示例：给一两个典型的用户请求示例，帮助模型建立映射。

2.2 写技能描述的实用模板与正反例

我在项目里总结了一套技能描述的写法，基本上每个技能都按这个模板组织（不同框架的Schema字段名称略有差异，但思路是一样的）：

name: todo_list_manager description: > 处理用户对待办事项的创建、查看、勾选完成、删除操作。 当用户表达"帮我记一下明天开会""列出我的待办""完成任务A"等意图时使用。 不要处理日程时间类需求，这类需求使用 calendar_scheduler。 本技能一次只处理一个待办操作，如果用户一次提出多个请求，拆分为多次调用。 parameters: action: type: string enum: [create, list, complete, delete] content: type: string description: 待办事项的具体内容

对比一个常见的反面案例：

name: todo_manager description: 管理待办事项。

前者给了模型明确的触发边界和动作分类，后者则要求模型自行推断“管理”到底包含哪些操作。在复杂场景下，前者的稳定性会好很多。

我做过一组对比测试：同一个Agent，一组使用详细技能描述，一组使用简要技能描述，在100条混合用户请求（含相近意图、绕弯表达、多意图叠加）下，详细描述组的技能选择准确率为89%，简要描述组只有61%。差距非常明显。

2.3 描述中的语气与措辞：为什么会引入歧义

写技能描述时要避免使用带主观色彩的词。比如“高效地”“智能地”“适当地”这类词，模型无法基于它们做出稳定判断，它们不是可执行的指令。

“安全地删除文件”就是个典型的模糊表达。什么算安全？是二次确认，还是备份后再删？应该直接写成“删除前先确认回收站已开启”，越具体越好。

另外，技能名称也要注意。不能取两个语义上很接近的名字，比如“获取天气”和“查询天气”，这会让模型在选择时摇摆。名称之间要有明显的区分度，必要时可以在描述里明确互斥关系——就像上面例子里的“不要处理日程时间类需求”。

2.4 描述长度的平衡：太短不达意，太长会分散注意力

虽然描述要详细，但也并非越长越好。太长的描述会占用上下文窗口，同时降低模型匹配关键信息的效率。经验是：每个技能的描述控制在150到300个英文字符之间，核心信息前置，把最重要的触发条件和边界放在前两句话里。

如果某个技能确实复杂，无法压缩，那就说明这个技能本身可能拆得还不够细。应该继续拆分，而不是加长描述。

3. 调度机制与技能路由：从静态规则到语义匹配的演进

3.1 常见的四种技能调用方式，优劣对比

技能定义好之后，下一个核心问题就是：模型怎么决定在什么时候调用哪个技能？我所接触到的方案大致分为四种，这里做一个对比。

我在实际项目里最常用的是“模型直接选择”，并叠加了一层“嵌入向量匹配”作为备选路由。具体逻辑是：先让模型根据对话上下文判断技能；如果模型输出置信度较低或没有产出有效技能，再降低阈值用向量匹配去兜底。这种“双通道”设计显著降低了误调用率。

3.2 双通道路由的架构设计：

我在模拟项目X中实现过一个双通道路由模块，核心逻辑伪代码如下：

def route_skill(user_input, context, skill_registry): """ 先尝试模型直选技能，不满足条件时使用嵌入兜底。 """ # 通道一：模型直选 model_selection = llm_route(user_input, context, skill_registry) if model_selection and model_selection.confidence > 0.8: return model_selection.skill_name # 通道二：嵌入兜底 fallback = embed_route(user_input, skill_registry) if fallback and fallback.similarity > 0.75: return fallback.skill_name # 都失败则走默认回复逻辑 return "fallback_response"

这种实现的关键在于两个阈值：模型直选的置信度阈值和向量匹配的相似度阈值。数值并不是随便定的。我在模拟项目X里通过收集测试样本，统计了正确调用和错误调用的得分分布，发现大多数正确选择的置信度集中在0.8到0.99之间，而错误选择往往低于0.7；向量相似度则呈现明显的双峰分布，正确样本集中在0.8以上，错误样本集中在0.6左右。最终定了0.8和0.75这两个阈值，误杀率和误放率都控制在了可接受范围内。

3.3 技能数量多了怎么办：分组建索引

当技能数量超过30个后，让模型一次性阅读全部技能列表是不现实的，因为注意力会分散，上下文也会过长。我的做法是分层路由：

• 先按领域域分组，比如“办公协作”“信息查询”“数据操作”。
• 第一层路由先判断用户的请求属于哪个领域。
• 第二层路由只在对应领域内的技能里做选择。

这样每次让模型阅读的技能数量控制在10个以内，选择精度明显回升。

分组的时候要注意：分组的语义边界必须清晰，而且每个技能只能归入一个组。如果一个技能同时横跨多个组，意味着它本身定义得不够清晰，需要重新调试。还有一个容易遇到的问题：热门技能的调用频率明显高于冷门技能，导致冷门技能长期没有正样本。这种情况下，我会对技能描述做定期复盘，看冷门技能到底是没人用，还是描述让模型找不到。

4. 技能注册表与生命周期管理：让技能变成可维护的资产

4.1 技能注册表：一切技能的单一事实来源

技能模块不能散落在各个脚本里，需要有一个统一的注册表来管理。注册表记录每个技能的元信息、当前版本、启用状态、依赖关系等。我在项目里用的注册表结构大致是：

skills: - name: todo_list_manager version: 2.3.0 enabled: true group: office_collaboration description_ref: ./descriptions/todo_list_manager.md implementation: ./implementations/todo_list_manager.py dependencies: [user_session_store] changelog: | - 2.3.0: 支持批量删除待办事项 - 2.2.0: 修复列表排序不稳定的问题

注册表的好处是：审计起来一目了然，知道当前系统动态加载了哪些技能、各自的版本是什么。出现问题回滚时，也能准确回到某个技能的某个版本。

4.2 版本管理与灰度发布：改技能描述是一次线上实验

技能描述不是写一次就一劳永逸的，它需要随业务需求不断调整。但改描述有风险：你可能提高了某个场景的准确率，但破坏了另一个场景的调用。

我推荐的做法是“描述即配置，配置走版本库”，每个技能描述的变更都走一次完整的版本记录流程。结合线上日志做A/B对比：老版本描述跑一周，新版本描述跑一周，比较技能选择准确率、任务完成率等指标，再决定是否全量切换。

这个流程看起来重，但对于生产级Agent来说非常值得。技能描述是整个系统里最有杠杆效应的部分，改一行描述的影响可能比改十行代码还大，不能用“拍脑袋”的方式去改。

4.3 健康度监控：让技能自己“汇报”状态

技能模块化还有一个优势是可以做细粒度的健康度监控。我会定期统计以下指标：

• 技能调用频率
• 技能选择准确率（通过用户反馈或结果校验获得）
• 技能执行成功率（执行逻辑失败的情况）
• 技能平均响应耗时

这些指标汇总成一张技能健康度看板。如果某个技能的调用频率突然下降，大概率是描述发生了回归；如果某个技能的响应耗时偏高，则可能是执行逻辑有问题。

我在模拟项目X里就遇到过这样一个情况：某个技能近一周调用率跌了一半，排查后发现是上一次更新描述时把关键词“导出”改成了“生成”，而用户习惯使用的还是“导出”，导致匹配度大幅下降。这就是监控能直接反映出来的问题。

5. 实测环节：一个技能跨模块冲突的完整排查链路

5.1 问题现象：两个技能开始互相“打架”

事情是这样的：模拟项目X里上线了一个“智能日程助手”模块，包含create_event和find_free_slot两个技能。上线初期表现稳定，但某次更新后，用户说“安排周二下午3点的会议”，系统却调用了find_free_slot，没有直接创建日程，导致日程丢给用户确认后没有被执行。现场反馈很明确：技能路由错乱了。

5.2 排查链路第一步：看日志定位输出现象

我先导出了两类日志：技能路由日志和实际操作日志。发现这个问题的触发率大概是12%，没有触发时行为又正常。这台问题有很强的不确定性，指向的是模型层面的路由判断问题，而不是代码逻辑问题。

5.3 排查链路第二步：比对技能描述与疑似冲突案例

我把create_event和find_free_slot的描述重新列出来逐字比对，发现了一个关键差异点。create_event的描述里有“当用户明确表达了会议的日期和时间时使用”，而find_free_slot的描述里有“当用户需要查找可用的空闲时间段时使用”。问题出在“周二下午3点”这个表达上：系统设计时认为这算“明确日期时间”，但对模型来说，它可能会把“周二下午3点”理解为“一个查询请求”，不能完全确定是否要直接创建。

排查前我推测“描述不够具体”是根因，实际比对后确认：find_free_slot的描述里缺少“不要处理已知固定时间点的日程创建请求”这一边界说明，导致模型在两种意图之间摇摆。

5.4 排查链路第三步：构造最小复现样例

为了验证这个推测，我构造了五条相近的测试请求：

1. “安排周二下午3点的会议”
2. “周二下午3点有空吗”
3. “帮我约周二下午3点”
4. “查一下周二下午3点的空闲情况”
5. “周二下午3点安排和A同学的会”

跑了一轮对比，结果清晰地显示：第1、3、5条请求在旧描述下倾向于误调用find_free_slot，而第2、4条则保持正常。问题锁定成功。

5.5 修复方案与验证结果

我做了两处修改：

• 在find_free_slot的描述末尾增加“如果用户已经指定了固定的会议时间并希望创建日程，应调用create_event而不是本技能”。
• 在create_event的描述开头增加“创建日程是唯一处理‘确定时间+确定参与者’请求的技能”，强化互斥性。

修改后同一组测试请求的调用准确率从修改前的82%提升到了100%（测试集共50条相近表达，修改前错误8条，修改后错误0条）。连续观察一周，线上误调用率从12%降到了1.5%以下。

这个排查链路的收获总结成一句话：技能冲突很多时候不是模型的问题，而是技能描述里的边界条件没写清楚。排查时不要急着改代码，先比对描述、再做最小复现、再逐条验证，整个过程其实很快。

6. 扩展方向：从单技能模块到技能编排与自动组合

6.1 复杂任务怎么处理：编排层与技能层分离

当单个技能无法满足用户的复杂目标时，需要引入编排层。编排层负责拆解任务、规划子步骤、按步骤调用技能、汇总结果。

我处理过的一个典型场景是“帮我整理本季度的项目汇报材料”。这个请求至少涉及文件查找、数据汇总、文档生成三个技能，而且三者之间存在依赖关系。编排层先调用文件查找技能定位材料，再调用数据汇总技能提取关键数据，最后调用文档生成技能形成汇报初稿。每个技能只负责自己的部分，编排层负责串联。

6.2 技能的自我组合：模型作为动态编排器

确定性编排适合固定的流程，更灵活的方案是让模型根据任务动态编排技能。

我在一个“个人助理Agent”的模拟项目Y上实验过类似方案。用户说“周五和A同学开会对吧？帮我准备一下”，系统需要：

• 从日程里取到会议信息（调用日程查询技能）
• 查参会人背景（调用联系人查询技能）
• 生成会议议程大纲（调用文档生成技能）

整个过程没有固定的第一步到第五步，模型需要根据上下文自行决定调用顺序和组合方式。技能描述依然是最关键的一环：只有每个技能都被描述得足够清晰，模型才可能在动态编排时做出正确判断。

6.3 风险提示：动态编排失控的可能性

动态编排看起来很强大，但也更容易失控。用户随口一句“随便安排一下”，模型可能就会连续调用五六个技能，产生不可预期的影响。我会在编排层设置几个安全阀：

• 单次请求的技能调用次数上限；
• 涉及写入、删除、执行类技能时强制二次确认；
• 中间步骤失败时明确返回错误位置，而不是“假装成功”。

这些约束本质上是对动态编排的信任边界，没有它们，动态编排曝光的问题会远超它的收益。

7. 几个容易被忽略的细节：我在实际项目中反复踩过的坑

7.1 技能描述里的每一个字都有可能被模型“当真”

模型是非常字面的。你写“这个技能适合处理简单问题”，它可能真的只在简单问题时才调用。这种微妙的语义暗示会直接影响模型判断。所以技能描述里不要写修饰性的评价词，只写事实和边界条件。

7.2 上下文窗口的长度影响技能选择的稳定性

当对话轮数变长，上下文里堆满历史消息，模型对技能清单的关注度会下降。我的做法是：让技能清单保持在系统上下文的最前面，同时在关键轮次把已选择技能的名称和状态重新“钉”在最新消息里，提示模型“当前流程使用的是哪个技能”。这个小改动在长对话场景下人感觉效果很明显。

7.3 日志记录不能只记录“调用了哪个技能”

还要记录“用户请求原文”“模型决策文本”“技能返回的原始结果”。很细节，但排查问题的时候，缺一个部分都可能导致结论错误。我现在每个技能调用都会记录完整三元组：输入、决策、输出。

7.4 先跑通最小闭环，再优化路由策略

很多人在第一次搭建技能系统时就想把双通道路由、动态编排一步到位。但我的建议是：先只用模型直选跑通一个最简单闭环，确认技能定义、执行逻辑没问题，再渐进加入向量兜底、分域路由、编排层。否则出现问题时，你根本不知道是哪个环节出了问题，排障成本极高。

7.5 技能描述更新后必须做回归测评

每次更新任何技能描述，都应该跑一遍预设的回归测试集。测试集覆盖各技能的典型请求、边界请求、相近意图请求、多意图组合请求。很多人跳过了这一步，结果在线上一路飘红才发现问题，那个时候再定位就晚了。

回归测试可以做成一个简单的脚本：给定一批输入，调用路由模块，输出预测技能与期望技能进行比对，自动汇总准确率。每次描述变更后跑一次，就能快速建立信心。

8. 把这些经验收敛成一套可行的落地路径

如果你正在考虑把自己的智能体重构为agent-skills模式，我建议按以下顺序推进：

先盘点当前已有能力，列出所有需要提供给用户的功能点，逐一抽象成候选技能。为每个候选技能写描述，重点写清楚触发条件和边界。然后搭建注册表，把技能集中管理起来。用“模型直选”作为唯一的调度方式先上线跑一遍。收集一轮线上日志，分析误调用案例，针对性修正描述。接着视需求加入向量兜底路由，降低漏调率。再对技能数量超过30的场景做分组路由。最后考虑编排层，把多步骤任务拆解成技能组合。

这个过程不需要一步到位，但每一步都有明确的价值。尤其是第一步，不要跳过去。很多人在设计时顺手写技能描述，写出来的描述质量往往不够，最终拖垮了整个系统的稳定性。花时间去把技能描述打磨到“不需要额外解释也能被模型准确理解”的状态，是整个架构里性价比最高的一步。

还有一点：不要因为“示例项目里这么写”就照抄别人的技能描述。同一个能力，在不同业务语境下的触发条件差异巨大。认真写自己的描述，比复制任何模板都重要。

agent-skills这条路，本质上是在用一种工程化的方式驯服模型的不确定性。它不会让模型突然变得全能，但会让模型的每一次选择更有据可依。至少，当你需要排查问题时，你面对的不再是一段晦涩的整体提示词，而是一堆边界清晰、可单独测试、可单独修改的技能模块——这一点带来的幸福感，只有被单体Prompt折磨过的人才能真正理解。