前段时间我在重构一个基于大模型的智能客服系统碰到了非常典型的问题业务逻辑越加越多Prompt 越来越长每新增一个功能都要去动主流程代码改完还会影响原有功能的稳定性。后来我把一套叫 agent-skills 的设计思路落地到项目里才算是把问题从根上解决了。这篇文章想聊聊 agent-skills 到底在解决什么问题、一个技能库该怎么设计、以及我实际落地时踩过的那些坑。先说清楚agent-skills 不是某个特定框架而是一套让智能体具备“可复用能力单元”的设计模式。它的核心思想是把 Agent 能做的各种操作从纠缠在一起的主流程里拆出来封装成一个个独立、可描述、可注册、可调用的“技能”。智能体本身只负责理解目标和做决策具体怎么做交给技能去执行。这就像你开车不需要每次从零思考怎么打方向盘、踩油门一样技能就是 Agent 的肌肉记忆。适合谁看如果你正在做大模型相关的应用开发尤其是做 Agent、工作流、自动化工具或者被“Prompt 越来越长、逻辑越叠越乱”的问题折磨过这篇内容可以直接参考。我会从设计思路讲到代码实现再到排查实录尽量把你落地时会遇到的问题一次说透。1. 为什么 agent-skills 会成为智能体落地的关键拐点1.1 单体 Agent 的三大通病我最早做 Agent 时也是典型的“单体式”写法一个超长 System Prompt里面塞满了角色设定、任务描述、工具列表、使用说明、约束条件然后让模型自由发挥。刚开始功能少还没什么感觉等接了五六个外部 API 之后问题就全冒出来了。第一个问题是 Prompt 长到一定程度模型会出现“意图漂移”。你明明让它去做 A 任务它非要先解释一遍 A 任务再顺带提一下 B 任务甚至把 B 任务的工具描述也当作操作指令执行。不是模型变笨了而是过长的上下文里有效信息密度被大幅稀释注意力被分散到无关描述上。我们实测过当 System Prompt 超过 3000 token 时工具调用的准确率会有明显下降而且带业务色彩的描述越多下降越严重。第二个问题是工具调用逻辑和业务逻辑高度耦合。比如我需要一个“查询订单状态”的功能代码里既要写如何调用订单 API又要写如何解析结果、如何判断是否超时、如何生成用户可读的回复。这些逻辑一旦散落在主代码里后续维护就是灾难。要么造成重复代码要么改一处崩三处。更尴尬的是你还很难复用换个项目或者换个场景这些逻辑又得重新复制一遍。第三个问题是能力无法沉淀。团队里可能已经有人写好了 PDF 解析模块、有人写好了数据图表生成模块但因为没有一个统一的技能接入标准这些模块只能躺在各自的项目里。新启动的项目如果需要类似能力往往选择重写而不是复用因为“接进来要改的代码太多了还不如自己写”。长期看这是非常大的隐性成本。这三个问题叠加起来让我意识到Agent 的核心问题不只是“怎么回答得更聪明”而是“怎么组织它的行为能力”。这时候技能化的思路就应运而生了。1.2 技能化到底解决了什么agent-skills 的出发点很朴素把 Agent 能做的事像乐高积木一样拆成一个个标准颗粒需要哪个就拼哪个不用的就不让它出现在上下文中。这里的“技能”包括几个层次有简单的函数级别技能比如计算、格式转换、字符串处理有工具调用类技能比如查天气、查库存、发消息也有复杂的组合类技能比如“整理周报”内部可能要调用数据查询、文本摘要、格式排版等多个步骤。但无论哪一层它们都遵循同一套接口规范Agent 不需要关心内部实现只需要知道“这个技能叫什么、有什么用、需要什么参数”。这个设计带来三个直接收益。第一上下文可以被精确控制。需要用到哪些技能就把对应描述注入到 Prompt 里其他技能完全静默这就从根源上缓解了 Prompt 过长带来的意图漂移。第二技能变成了一等公民可以独立编写、独立测试、独立发布。一个团队完全可以分成技能开发组和智能体业务组两组之间只通过技能接口契约沟通开发效率提升非常明显。第三能力真正开始沉淀。每做一个新项目你的技能库里都会多出几个新的通用技能下一次同类需求直接从库里选就行而不是从零开发。我自己的体会是技能化最大的价值不在于某一个技能的编写而在于它帮你把“Agent 应用”和“Agent 能力”这两个概念彻底解耦了。应用会变、场景会变但能力库可以越来越厚这才是 agent-skills 长期价值的核心。恰恰是这个拐点决定了 Agent 从实验室玩具走向工程化落地时选哪条路可以走得更远。2. 技能库设计agent-skills 的核心抽象与调度逻辑2.1 技能的接口契约长什么样在动手写代码之前得先定义一个清晰的技能接口契约。我见过很多失败的例子就是因为技能接口没定义好导致后面每加一个技能都要为它单独写适配代码。好的技能接口应该包含这几部分技能名称、描述信息、参数 Schema、执行函数、依赖声明。其中最重要的是描述信息。很多人会觉得执行函数才是核心其实在 agent-skills 体系里模型能不能正确调用你的技能百分之六十以上取决于描述写得好不好。描述要让模型清楚三件事这个技能是用来干什么的什么时候应该使用它使用时需要注意什么边界条件。我举个例子下面这个技能描述就写得很糟糕技能天气查询 描述查询天气 参数城市名模型看到这种描述根本不知道它内部做了几天的预报、是否需要 GPS 坐标、支持哪些城市。结果就是要么不调用要么拿着用户的一句话强行调用然后就报错。更好的写法是这样的技能weather_query 描述查询指定城市未来三天的天气预报信息。当用户询问天气、气温、降水、风力等情况时使用。支持国内主要城市参数使用标准城市中文名称。如果用户未指定城市必须询问用户后再调用。 参数 - 城市 (city_name, string, 必填) - 日期 (date, string, 可选, 格式YYYY-MM-DD默认当天)这个描述把触发条件、支持范围、参数格式、边界情况全说清楚了模型在调用时就不容易犯模糊错误。我建议在定义技能时把描述模块当作一项正式工作来做而不是随手写一句话。一个技能描述写得好不好直接决定你的技能命中率。除了描述之外参数 Schema 也很重要。强烈建议使用 JSON Schema 格式来定义参数这样既能给模型明确的参数结构又能在运行时做完整的参数校验避免模型输出一个缺少必填字段的调用请求。执行函数的部分只需要保证输入输出都是纯 JSON 即可内部可以调用 HTTP API、读文件、操作数据库但对外只暴露一个干净的 JSON 边界。2.2 注册表与动态发现机制有了技能接口之后还要考虑“技能从哪来、模型怎么知道有哪些技能”。这一步我把它分成两个场景静态场景和动态场景。静态场景比较简单项目里技能数量少比如十几个以内可以直接在代码启动时把所有技能加载到一个全局技能注册表中然后把技能名称和描述拼进 System Prompt。这是最稳妥的做法所有技能都会暴露给模型调用路径最短调试也直观缺点是上下文会随着技能数增长而膨胀。动态场景就复杂一些适用于技能数量较大、或者技能本身是插件化动态加载的情况。这时候你不能把全部技能描述都塞给模型而是需要做两件事一是技能注册表支持按需注册和查询二是有一个路由层负责在模型决策前先根据用户意图去筛选候选技能。我采取过的做法是给每个技能维护一个标签列表包含功能分类、适用场景、以及若干关键词。当用户消息进来时先用一层轻量分类模型或简单的向量相似度检索把相关性最高的一批技能提取出来只把这些技能的描述注入到 Prompt 中的工具列表里。还有一个容易被忽略的环节动态发现后的“版本一致性”。技能是动态加载的但模型生成调用请求时参数结构必须与当前加载的版本完全一致。我曾经踩过一种坑同一套技能代码旧版本参数是city_name新版本改成了city但注册表缓存还在用旧版本描述。结果模型生成了新字段运行时代码却去找旧字段导致运行时参数校验失败。现在我的做法是所有技能加载时强制校验版本号任何变更必须同步更新注册表不允许出现新旧字段混用这个约定在多人协作时尤其重要。2.3 上下文窗口与技能加载策略技能数量一多AI 上下文窗口就是必争之地。一个技能描述平均要占 100 到 200 token如果注册表里有 50 个技能光技能描述就要吃掉近 1 万 token还没算上聊天历史和业务数据。这显然不可持续所以必须制定加载策略。我常用的策略分三层常驻层、候选层、隐式层。常驻层是所有核心决策技能无论如何都要出现在上下文中这个集合尽量控制在 5 到 8 个。候选层是当前用户意图相关的技能前面讲的动态检索就是这一层在做的事数量控制在 3 到 5 个。隐式层指的是那些不需要模型记住、只需要运行时能调用的内部函数比如日志记录、数据落库、格式清理这些完全不进 Prompt由主流程直接调用。这样的分层设计既保证了模型做决策时有足够的信息又不至于让上下文被技能描述挤占。实测下来同样的任务分层加载比全量加载在响应 token 上平均节省了 30% 到 40%而且因为输入噪声少了调用的精准度反而更高。需要注意的是常驻层的技能列表不是一成不变的要根据业务发展趋势定期复盘。我自己每两周会拉一次模型调用日志统计哪些技能是高频的、哪些几乎没有被调用过然后调整分层策略。你可能会发现有些你认为很重要的技能实际上从来没有被触发过反而是某些边缘技能高频使用这时候就要果断调整常驻集合。3. 实操记录从零搭建一个可用的 agent-skills 技能库3.1 基础架构与目录结构前面理论聊得不少这一节我直接分享一套可以照着落的代码结构。为了不依赖特定框架我用纯 Python 做示例但你完全可以用 TypeScript、Java 等语言复刻同一套思路。我习惯的目录组织方式是把技能库当作一个独立包来管理每个技能独占一个模块文件对外暴露一个统一的register(registry)方法。agent_skills/ ├── core/ │ ├── registry.py # 技能注册表 │ ├── schema.py # 参数Schema定义与校验 │ └── skill.py # 技能的抽象基类 ├── skills/ │ ├── weather_query.py # 天气查询技能 │ ├── remind.py # 定时提醒技能 │ ├── report_weekly.py # 周报生成技能 │ └── __init__.py # 自动扫描注册 ├── loader.py # 技能加载器分层策略 └── tests/核心抽象基类skill.py大致长这样# core/skill.py from abc import ABC, abstractmethod from typing import Any, Dict, List class BaseSkill(ABC): name: str # 唯一技能名 description: str # 给模型看的描述 tags: List[str] # 检索标签 version: str # 版本号 param_schema: Dict[str, Any] # JSON Schema abstractmethod def execute(self, params: Dict[str, Any]) - Dict[str, Any]: 执行技能逻辑以JSON格式返回结果 pass其实就这么简单。每个技能只需要继承这个基类完成execute方法的实现。注册表registry.py则维护一个字典提供register_skill、get_skill、list_skills三个基础方法再加一个从文件夹自动扫描加载的能力方便新技能写完后直接放进skills/目录就被自动注册。3.2 编写第一个技能模块我拿一个实际用过的“定时提醒”技能当例子完整走一遍。场景需求是用户可以让我在某个时间点提醒他做某件事。这个技能既要解析自然语言里的时间又要处理提醒触发逻辑。在 agent-skills 的设计下我只需要把“解析时间”和“执行提醒”封装在技能内部模型负责把用户的自然语言对应到参数上。# skills/remind.py from core.skill import BaseSkill class RemindSkill(BaseSkill): name remind version 1.0.0 description 创建定时提醒任务。当用户要求在今天或未来某个时间提醒他时使用参数task为提醒内容remind_time为ISO 8601格式时间字符串。 tags [remind, timer, todo, 提醒] param_schema { type: object, properties: { task: {type: string, description: 提醒内容}, remind_time: {type: string, description: ISO 8601格式时间如2025-06-01T09:00:00} }, required: [task, remind_time] } def execute(self, params): # 实际逻辑写入提醒任务表并启动定时检查 task, remind_time params[task], params[remind_time] # 落库、创建调度任务等操作略 return {status: scheduled, task: task, remind_time: remind_time}写好这个模块后在skills/__init__.py里加上一行导入技能库启动时就会把它扫描进注册表。做完这些模型就能在聊天中收到这样的工具定义并根据用户的“下午三点提醒我给客户回电话”生成一个调用请求把task设成“给客户回电话”remind_time设成当天下午 15:00 的 ISO 时间。这里有个实操细节提醒时间一定要让模型输出标准格式时间最好是 ISO 8601而不是“下午三点”这种中文描述。因为模型生成的是字符串后续代码解析越是标准化越不容易出错。如果条件允许可以再加一层参数后处理允许模型传相对时间比如“一小时后”然后在技能内部做转换。不过建议第一版先让模型输出标准时间减少解析复杂度。3.3 技能编排与组合调用单技能写好之后真正的复杂度在“多技能组合”。一个复杂的用户请求往往要调用多个技能才能完成。比如用户说“帮我整理一下本周的项目进展并发给团队”这个需求至少涉及查询任务数据、生成摘要、查找团队成员邮箱、发送消息四个步骤。最简单也最稳的组合方式是自己在主流程里做硬编排定义好步骤顺序按顺序调用技能。这种方式的优点是逻辑透明、易于调试和兜底缺点是每接入一个应用场景都要写一份编排代码。更进阶的方式是利用模型做动态规划。把技能列表暴露给模型让它自己决定调用顺序和参数传递。这种方式的灵活性高但需要非常强的容错设计因为模型可能跳步、可能传错参数、可能在一个技能失败后不知道如何恢复。我自己的实践是在 agent-skills 体系里同时保留这两种方式用技能描述里的一个requires字段来声明跨技能依赖比如“周报生成”技能声明依赖“数据查询”技能模型在规划时会优先找到依赖项并串联执行。另外组合调用场景下技能之间的输出传递也要约定清楚。我规定所有技能执行结果必须返回结构化 JSON并且至少要包含status和data两个字段。status标记成功、失败或部分成功data内是具体的业务数据。这样主流程在判断下一步时可以统一根据status做分支而不是去解析千奇百怪的错误文本。组合技能还有一个容易忽略的坑幂等性。尤其在面对重复调用时一个技能如果执行了两次会不会产生两条重复的提醒、两封重复的邮件如果有副作用就要在技能定义里明确标注“非幂等需要调用方保证只执行一次”同时在上层做一个执行去重机制。我自己就在发送通知的技能上吃过亏模型因为生成太慢重试了一次结果用户收到两条一模一样的消息从那以后所有写操作类技能我都要求做幂等控制。4. 踩坑实录agent-skills 的常见问题与排查方法4.1 技能命名冲突与命名空间管理技能数量从十几个增长到几十个的时候第一个撞上的就是命名冲突。不同开发者可能各自写了“发送邮件”技能一个叫send_email另一个叫email_send功能相近但实现不同。更严重的是同名技能互相覆盖注册表里后加载的会把先加载的顶掉而模型看到的还是同一个名字生成的调用请求语义就完全跑偏了。我建议从一开始就引入命名空间前缀比如公司级技能统一用acme_前缀项目级技能用proj_前缀个人实验技能用exp_前缀。虽然命名会变得长一些但换来的是全局唯一性和可追溯性。同时注册表里要做“重复注册检测”一旦发现同名技能直接报错并暴露两个冲突模块的信息而不是静默覆盖。这个检测逻辑看起来不起眼实战里救了我好几次。还有一点技能间如果有调用关系引用名称一定要用全名不要用简写否则在分布式或插件化部署时很容易出现找不到依赖的问题。4.2 上下文污染与记忆管理技能执行过程中会产生中间结果这些结果要不要放回对话上下文里是个需要谨慎控制的问题。我之前遇到一个场景技能 A 执行后返回了很长一份 JSON 数据主流程没有做截断直接把整个数据拼进了下一条模型输入里。结果模型在后续决策时被这些数据细节带偏开始模仿 JSON 结构输出生成的内容一团糟。后来我定了一个规则技能返回数据在注入上下文前必须经过“提炼”处理。提炼可以是截断到指定长度、转换成自然语言摘要、或者提取核心字段。比如查询订单列表返回了 200 条记录注入上下文前只保留前 5 条和总条数、热门品类等聚合指标模型关心的数据足够做决策就好不需要看到全部明细。这个规则让输出的稳定性提升非常明显。记忆管理的另一面是历史消息里的技能调用记录。模型为了生成下一步动作可能会去“回忆”前面某次的技能调用细节但那些细节已经过时了。我的做法是在每次技能执行完成后把执行结果和当时的用户意图合并成一条摘要记忆放在单独的 memory 区干净的上下文只保留当前轮次的必要信息。这样做的好处是既保留了技能执行的关键信息又不会让历史缓存拖慢推理速度。4.3 技能不命中为什么模型就是不调用你的技能这是整个 agent-skills 落地过程中最让人头疼的问题。明明技能已经注册了模型却频繁不用或者干脆直接根据自己的常识来回答。排查这个问题我把经验总结成一个检查表按顺序排查第一技能描述是否精准匹配用户表述。如果你的技能描述里写的是“查询股票行情”而用户的表达习惯是“看看今天股票涨了没”模型可能意识不到这是同一件事。要让技能描述的语料风格尽量贴近用户的自然表达习惯必要时从历史对话里抽取高频问法充实到描述里。第二技能是否被加载进当前上下文。如果你实现了动态加载但当前轮的候选技能筛选没有覆盖到目标技能那模型再聪明也调不到。我遇到过很多次问题不在模型而在检索层的召回条件写窄了。排查时打印出每一轮实际注入的技能列表一眼就能看出来。第三参数是否可以轻松从对话中提取。有时候模型想调用但你要求的参数它很难从用户话里提取到比如你要一个 user_id但用户从头到尾只提了手机号又没有相关映射信息模型就只能放弃调用转而乱猜或者给一句“暂时无法处理”。解决方案是降低技能对信息的提取要求或者增加一个默认值机制无法确定的参数不要去死磕允许技能内部再向用户追问。第四多个相似技能互相干扰。如果两个技能功能重叠模型在决策时会产生犹豫随机选择一个甚至来回切换。这就要从技能设计层面做整合或者给每个技能增加更明确的适用边界描述。我把排查时最常用的几个操作整理成一个速查表方便大家遇到问题时按图索骥。现象可能原因排查方法模型完全不调用技能技能描述质量差 / 技能未加载检查加载日志重写描述模型调用了错误的技能相似技能互相干扰收敛技能边界增加排他说明模型生成了非法参数Schema 定义与实际调用不一致用 JSON Schema 做运行时校验并反馈给模型技能执行成功但模型没引用结果返回结果未正确注入上下文检查结果提炼逻辑确认注入字段调用超时技能执行链路过长拆分技能增加超时兜底这个表并不是面面俱到但覆盖了绝大多数会直接导致业务异常的场景。每次排查完我都会顺手给技能库补一条日志监控项把相关指标加进监控看板避免下一次踩同一个坑。最后再分享一个我觉得对整个技能库长期迭代帮助最大的动作建一个技能使用率的周报机制。每周回顾一次所有技能的调用次数、成功率、平均耗时和用户反馈定期把不常用的技能下线或合并把高频技能做重点优化。这个习惯坚持下来后我的技能库不仅没有越来越臃肿反而越来越精练每次项目启动时的接入成本都大幅降低。如果你正在构建自己的 Agent 技能体系我建议从第一天就把这个复盘机制设计进去它带来的长期价值会远超你的预期。