你要是最近在做智能体Agent相关的东西多半已经发现“agent-skills”这个词在项目文档、代码仓库和团队讨论里出现的频率越来越高。自己搭一套技能层或者把零散的工具函数整理成标准技能已经成了从“能聊天的模型”走向“能干活的智能体”之间最重要的一道工序。agent-skills 不是什么玄学它就是给智能体准备的可复用、可校验、可组合的能力模块。我这一年多接触过的项目里凡是拆分得清楚的技能层后续迭代和排障都顺很多凡是把逻辑堆在 Prompt 里或者把所有函数塞给模型随便选的基本都会在半路返工。这篇文章就围绕 agent-skills 这个主题讲清楚它解决什么问题、怎么设计、怎么实现以及哪些坑是真实踩过之后才明白的。1. agent-skills 到底是什么为什么说它不是一堆“工具函数”1.1 从“会聊天”到“会干活”智能体缺少什么大模型本身是个对话系统它最擅长的是文本生成。但智能体要完成任务必须完成三件事理解意图、拆分步骤、调用外部能力。前两件现在有很多 Prompt 工程和规划框架在处理真正容易卡住的是第三件。很多团队一开始的做法是“把接口都做成 Function Calling 传给模型”。比如写一个query_inventory(product_id)函数再把 JSON Schema 描述给它模型就能在对话中决定要不要调用、传什么参数。这种做法跑几个 Demo 没问题一旦技能数量超过十个、业务逻辑变得复杂问题就来了函数签名只能表达“输入输出”表达不了“什么时候该用我”名称稍有不准确模型就把库存接口当成订单接口来调用参数校验和错误处理分散在每个函数里模型拿到一堆堆栈信息根本没法继续决策函数之间没有统一的执行上下文同一个会话里数据互相串。agent-skills 要解决的就是这一层问题。它不是简单地把函数列出来而是把每个可复用的能力封装成一套有名字、有描述、有参数契约、有错误规范、有执行上下文的完整模块。模型看到的不是一段代码签名而是一张“技能说明书”。1.2 技能层和普通函数/工具 API 的核心区别有人会问我已经封装好 API 了给它加个描述不就行了为什么非要单独说“技能”我的理解是普通函数是给人或代码调用的技能是给模型选择和执行的两者的契约完全不一样。普通 API 调用调用方已经知道自己要什么参数类型清晰、错误处理靠文档和异常。模型调用技能时它其实是在一堆描述文本里做“语义匹配”。你给它的描述如果只是“获取库存信息”它就会在用户说“还有货吗”时调用哪怕用户问的是另一个渠道的库存你给它描述“仅当用户明确提及广州仓且需要当前库存数量时调用不处理预计补货时间”它就能把边界划分得很清楚。另外技能层必须天然具备这些普通函数不太会关心的事情元数据名称、版本、适用场景、触发条件、不适用场景、成本等级参数 Schema在执行前做类型校验、默认值填充、必填项检查统一错误返回不能让技能把底层异常直接抛给模型执行上下文把 session_id、user_id、请求追踪 ID 注入每一次技能调用超时和幂等控制不让一个技能卡住整轮任务。所以 agent-skills 更像是一层“面向模型的适配层”把底层业务能力翻译成模型能够理解和可靠使用的语言。这一层设计得越好模型表现出来的稳定性就越高。2. 搭技能系统前先把这几个设计问题想明白2.1 技能粒度怎么切既不要万能技能也不要原子黑洞我见过不少失败的技能拆分要么是“大而全”要么是“小而碎”。“大而全”的技能比如一个handle_order技能里面既查订单又改地址还能申请退款。它的描述会非常长模型很难准确判断当前意图到底匹配哪一部分参数也会变得极其复杂。最要命的是你没法单独调整某一段逻辑每次改动都可能影响其他场景。“小而碎”的技能比如把“读取文件”拆成“读取文件名”“读取文件路径”“读取文件大小”三个技能。表面上看很纯粹但智能体为了完成一个简单任务可能要连续调用七八次技能中间任何一次选错或参数出错整条链路就断了上下文也被撑大成本翻倍。我的经验是粒度以“一个可以在智能体任务中独立完成、且不需要再拆步骤的最小动作”为准。举个例子一个周报助手可以拆成“查询工时记录”“查询任务完成状态”“生成周报正文”三个技能。它们彼此独立组合起来能完成完整任务单独调用也有意义。粗到这个程度就够了再往下拆“查询工时记录”里的数据库连接、字段过滤那不是模型该管的事。2.2 技能注册表名称、描述、参数和校验规则缺一不可有了合适的粒度下一步就是给技能做注册表。我的做法是每个技能对应一个类对外暴露统一接口内部持有执行函数和执行配置。至少要有下面这些字段字段作用示例name技能唯一标识模型和代码都用它引用query_stock_leveldescription给模型的说明书写清触发条件和边界当用户询问广州仓当前库存可用数量时使用不处理调拨、在途和补货时间parametersJSON Schema 格式参数定义校验入库前完成{type:object,properties:{...},required:[warehouse,sku]}version技能版本帮助排查行为变更v2.3.0timeout单次执行最长耗时8sside_effect标记是否有写操作、是否幂等true / false / idempotentauth_scope需要的最小权限范围order:read注册表里一定要把“参数定义”单独做不要和执行函数内部的入参混在一起。原因很简单模型输出参数时经常出现类型混乱、缺字段、多出未知字段的情况如果没有一层独立的 Schema 校验错误会一路跑到业务代码深处才爆炸定位成本非常高。参数 Schema 用现成的 JSON Schema 或 Pydantic 都行关键是必须在进入业务函数前完成校验和补全。执行函数永远假设自己收到的参数是干净的如果还有错说明 Schema 定义得不够细。2.3 技能之间的依赖关系不要让技能互相调用设计技能层时最容易犯的错是让技能之间直接互相调用技能 A 内部调技能 B。刚开始可能觉得很方便几个月后就会失控——调用链深、排查难、复用时根本不知道它会连带触发什么副作用。我踩过这个坑之后定了一条规矩技能层只向上暴露给唯一的编排者Agent 主循环技能之间不允许横向调用。Agent 主循环根据用户目标先调技能 A拿到结果再决定是否调技能 B。这样的好处是每轮决策都是模型基于当前最新结果做出的比技能内部死板地写死“先 A 后 B”灵活得多也更符合智能体的语义。两个技能需要配合时可以通过共享上下文对象传递状态。比如“查询库存”的结果可以写入上下文供“生成补货建议”读取但这个写入是在 Agent 主循环里完成的不是库存技能自己去调补货技能。3. 动手实现一个可复用的 agent-skills 服务3.1 技能基类和参数 Schema先定好执行的“接口契约”我拿 Python 项目举个例子思路在其他语言上同样适用。先定义一个技能基类规定好名称、描述、参数、执行时间和校验入口。# skill_base.py from pydantic import BaseModel, Field from typing import Any class SkillContext(BaseModel): 一次技能调用所处的全局上下文 session_id: str user_id: str request_id: str class BaseSkill: name: str description: str parameters: dict {} version: str 1.0.0 timeout: float 10.0 side_effect: bool False def __init__(self): self.schema { type: object, properties: self.parameters, additionalProperties: False, } def check_params(self, raw_params: dict) - dict: 统一入口校验参数类型补全默认值丢弃未知字段 from pydantic import create_model fields {} for prop_name, prop_desc in self.parameters.items(): # 这里按你的 Schema 生成 Pydantic 字段 fields[prop_name] (Any, Field(defaultNone, descriptionprop_desc)) ParamsModel create_model(f{self.name}Params, **fields) return ParamsModel(**raw_params).model_dump() def run(self, params: dict, ctx: SkillContext) - Any: 子类实现真实业务逻辑 raise NotImplementedError这段代码只是骨架重点不是框架本身而是把“参数校验”“上下文传递”“超时控制”这三件事固定下来。每个子类只需要实现run方法参数在进入run前已经被check_params清洗过一遍。我建议把check_params做成基类的__call__这样外面不管是谁调用技能都必须经过同一道关卡。如果有人绕过基类直接执行子类方法代码评审时可以直接打回。3.2 把技能暴露给智能体的三种方式原生 tools、MCP 与自描述文本技能层建好之后要把技能列表告诉模型。根据对接的模型生态我通常用下面三种方式。第一种是原生 Function Calling。OpenAI、Claude、通义千问这些模型都支持在请求里传一段tools列表模型会在合适的时机返回一个工具调用请求。这种方式最直接模型生态支持好接入成本低适合绝大多数场景。但要注意每家模型的 tool schema 细节有差异切模型时要做好映射层。第二种是通过 MCPModel Context Protocol工具协议暴露技能。MCP 的优点是“一次定义多处复用”技能作为 MCP Server 跑起来支持的客户端都能直接发现和调用。适合团队里有多个 Agent 项目、需要共享同一套技能资产的情况。缺点是多了一层服务治理排障时链路变长小项目会感觉有点重。第三种是在系统 Prompt 里以纯文本形式描述技能模型输出动作编号和参数自己做解析。这种方式不受模型厂商约束什么模型都能跑但解析和纠错成本高适合无法使用结构化工具调用的边缘场景。三种方式可以并存。我一般把核心业务技能用第一种暴露通用技能做成 MCP Server 供多个项目复用一些测试性质的小技能才用文本方式塞进 Prompt。3.3 最小可跑通的调用链路技能选择、执行、结果回填给你一个稍微具体一点的链路方便理解。假设你现在要做一个“仓库补货助手”技能表里有query_stock_level查询指定仓库、指定 SKU 的现有库存query_backorder_status查询在途补货单状态suggest_replenishment根据库存阈值生成补货建议。用户对模型说“广州仓的 A001 库存还够吗不够的话帮我看看补货到哪了。”一次正常的执行链路是这样Agent 主循环拿到用户问题把技能列表和描述交给模型。模型判断用户意图是“查库存”返回调用请求query_stock_level(warehouseguangzhou, skuA001)。技能层校验参数执行函数结果如{on_hand: 20, safety_stock: 50}。结果回填给模型模型发现库存低于安全阈值继续返回调用请求query_backorder_status(skuA001)。第二次结果回填后模型判断需要给出补货建议但用户没明确要求于是只输出自然语言“A001 库存只剩 20 件低于安全库存 50 件目前在途补货单已发出 500 件。”这个过程中技能层做了很多隐蔽工作参数校验、超时控制、结果截断以及把每次调用的输入输出存进日志。一次跑通不难难的是每轮都稳定执行。关键是把“技能描述”写对以及让错误信息以模型能理解的方式返回。4. 现实世界的坑我在 agent-skills 上踩过的、你会遇到的4.1 描述写得太“官方”模型会选错技能我第一次给技能写描述时走的是文档风“该函数用于查询仓库库存信息。”结果上线一周模型在两个场景里频繁选错用户问“A001 多久能到货”模型去调了库存查询因为描述里有“库存”两个字用户问“广州仓和上海仓哪个库存多”模型只调了一次广州仓查询没有并发查询两个仓。后来我把描述改成了更接近“决策规则”的写法仅当用户询问某个仓库、某个 SKU 的当前可售库存数量时调用。如果用户关注到货时间、在途数量、补货建议请使用query_backorder_status或suggest_replenishment。一次只查一个仓库如果用户提及多家仓库对比需要为每个仓库分别调用一次。描述从“功能定义”变成“决策边界定义”模型的选型准确率明显提高。我现在写描述会固定按这个结构触发条件、直接可用场景、不适用场景、特殊参数规则。这部分值得花时间打磨因为它直接决定了模型会不会“乱用技能”。4.2 参数校验不严执行期才会崩给你看模型填充参数时类型错误非常常见。比如我定义warehouse是字符串模型可能传[guangzhou, guangzhou]或者干脆传{name: gz}。一开始check_params没有强制类型这些脏数据直接进 SQL 查询语句报错五花八门。最气人的是有时候模型把时间参数传成了2024-13-45数据库报错了模型收到的是一大段看不懂的堆栈。解决办法是两层校验。第一层在check_params里用 Pydantic 严格类型转换传字符串就转字符串传列表就报错并返回标准错误信息。第二层在业务执行函数入口包一层try-except任何异常统一转换成三段式错误错误类型、可读原因、建议动作。给模型的标准错误示例{ error_type: INVALID_PARAMETER, message: 参数 warehouse 应为单个仓库编码实际收到数组, suggestion: 请确认是要对比多个仓库如需对比请多次调用本技能 }模型拿到这种错误可以自己修正参数重试而不是陷入无尽报错。4.3 无状态设计缺失session 之间互相串数据有一次我写了一个技能为了省数据库请求把用户上次查询的仓库编码缓存成了模块级变量。结果在线上一跑A 用户查完广州仓B 用户再来查上海仓技能内部却误以为默认是广州仓返回了错误的库存。沟通群里一度以为库存数据同步有问题最后定位到是这个缓存变量惹的祸。从那以后我规定技能执行必须是可选的、必须显式传入上下文。所有跨调用的状态都放进SkillContext技能内不要用任何模块级可变变量保存用户相关数据。如果确实需要缓存缓存的 key 必须包含session_id或request_id并且在会话结束后自动清理。技能尽可能保持无状态这样才能放心并发和复用。4.4 超时与幂等技能卡住会拖垮整轮对话接第三方服务时一个技能最长可能跑 30 秒。对用户来说30 秒内模型完全没有决策能力体验极差对成本来说这一轮对话的 token 消耗已经发生了还要白等一个慢接口。更麻烦的是慢接口重试时如果没做幂等还会产生重复的写入操作。我给每个技能都配置了默认超时外部 HTTP 类技能统一不超过 8 秒数据库类不超过 3 秒。超时后不是直接放弃整轮任务而是把超时错误返回给模型让模型决定是换个技能重试还是如实告知用户“服务暂不可用”。幂等控制也不能依赖外部系统自觉。写操作技能一定要在参数里带上业务请求 ID 或幂等 key技能执行前先检查相同 key 是否已经处理过。没有这个习惯补货单创建、订单状态更新这类操作很容易出线上事故。4.5 返回结果过长上下文窗口被“撑爆”库存查询结果可能几百条订单明细可能几千条全都直接回填给模型会迅速消耗上下文窗口。第一次遇到这个问题时我直接截断返回字符串结果模型看到不完整的数据反过来瞎猜。后来我把技能返回值统一成三种类型纯文本结果适合短内容直接回填结构化摘要只返回关键字段和统计信息如{total: 320, top_items: [...], summary: ...}结果引用返回数据的查询 ID 和访问方式模型如果想看详情再调用“查询详情”技能。这样一来模型每一轮拿到的都是精简信息能让它做出正确决策的数据都保留着窗口占用大幅下降。5. 版本化、评测和维护节奏让技能层不沦为技术债5.1 技能改名要克制版本和别名比重构更划算技能一旦上线就会被写进对话历史、缓存和日志里。你贸然把query_stock_level改成query_inventory_quantity旧会话里的模型可能还带着旧技能 ID服务端找不到就报错。语音助手和聊天机器人类产品尤其容易出这种问题。我建议技能名称保持“永久稳定”业务逻辑的变化用版本号记录。如果描述和实现发生了很大变化可以为新版本增加别名比如query_stock_level_v2并在技能列表里同时保留旧版本一段时间等线上流量基本切完再下线旧的。版本迁移时还要在注册表标记deprecated true让模型优先选择新版本。5.2 最简回归集20 个用例盯住技能层的质量技能好不好用不能靠感觉。我维护了一个“最小回归集”大约 20 个真实用户请求每个请求都标注了期望的技能调用序列和期望输出。每次发布技能或修改描述后跑一遍回归集对比模型选择是否发生变化。回归集不用很长但要覆盖典型高频场景、易混淆场景、异常输入场景、多技能组合场景。比如以补货助手为例场景输入示例期望技能调用单仓库存查询广州仓 A001 还有多少query_stock_level多仓对比广州和上海的库存数量对比一下query_stock_level× 2易混淆A001 补货单到哪了query_backorder_status参数缺失库存够吗没说哪个仓模型应追问仓库信息组合任务库存不够的话给我补货建议query_stock_level→suggest_replenishment跑回归集时建议把温度设为 0固定 Prompt 结构这样对比结果才有意义。不要只看“最终是否成功”还要看技能选择准确率和调用次数。一个请求本来两次技能调用能完成模型绕了五次虽然结果对但成本和体验都在劣化。5.3 发布前必须过的三道检查每次给技能做更新我都会走三道检查第一道是 Schema 检查。参数定义和返回结构是否清晰未知字段会不会被静默丢弃必填项是否真的必填第二道是错误演练。故意传错误类型、缺失字段、非法时间范围确认技能返回的都是标准错误格式不会把底层异常泄漏给模型。第三道是回归对齐。跑回归集对比增量改动前后的技能调用序列差异。差异如果是预期的比如本来就会选错现在修正了记录下来如果不是预期的回滚二次检查。三道检查都在本地或者测试环境完成确认没问题再注入线上技能列表。别小看这一步技能层的改动风险比普通代码高因为它的调用者是模型输出存在随机性必须用回归集兜底。这套技能层的方案是我在几个真实项目里反复磨出来的没有用到什么特殊框架核心就是把“给模型用的技能”当成一个独立产品来设计。如果你正准备给自己的智能体补上技能层我的建议是从两三个高频场景开始先定义好基类和注册表再让模型跑通一遍完整链路。别等设计完美了再动手技能层的重构成本其实比想象中低很多先跑起来后面再慢慢收敛边界收益会来得比你预期的更快。