Agent技能封装实战：从混乱提示词到可复用Skill体系

最近在折腾一件事把大模型 Agent 的各种能力从“临时让模型自由发挥”改成“像工具箱里的标准件一样定义、注册、复用”。这就是标题里写的 agent-skills。这个项目不绑定某个具体框架它是一套关于 Agent 技能的设计思路和实现集合每个技能都有清晰的声明、上下文、执行入口和校验规则Agent 在回答问题时能按需挑选技能而不是靠提示词碰运气。它能解决的实际问题很直接当你的 Agent 需要处理几十个不同任务比如查库存、算价格、写周报、调用内部 API如果全塞进一个 prompt结果会越来越不可控如果把每个任务拆成一个 skill分开维护、分开展测试再交给 Agent 调度整个系统就变得可观测、可回滚、可复用。适合正在做 Agent 应用开发或者准备把 LLM 接进业务系统的人参考。接下来我把设计思路、实现步骤和踩坑记录都摊开讲尽量给你一套能直接抄作业的方案。1. 先搞清楚agent-skills 到底解决什么问题1.1 大模型 Agent 的“能力碎片化”困境做 Agent 应用的人应该都有这种感觉项目刚开始只接两三个工具提示词里写清楚“你有这些工具根据用户问题调用”效果还不错。但随着业务场景变多工具从三个变成三十个提示词越写越长模型的调用准确率开始往下掉经常出现该调 A 工具的时候偏偏调了 B 工具或者一个简单问题触发了连环调用。我见过最典型的一个客服 Agent既要查订单又要处理退款还要记录用户投诉最后还要根据用户情绪决定是否需要人工介入。所有逻辑都写在系统提示词里工具列表也全部平铺。结果就是模型经常把“用户抱怨物流慢”理解成“用户要求退款”直接调用了退款接口。这不是模型笨而是你的 Agent 没有“能力边界”的概念。agent-skills 的思路就是解决这种碎片化问题。它把 Agent 的每一项能力收敛成独立、可测试、可复用的 skill告诉模型两件事第一你有哪些 skill 可用第二每个 skill 在什么条件下才能被调用。模型不再需要从一个巨大的 prompt 里推断流程它只需要做选择和调度。1.2 Skill 不是 Prompt 模板也不是普通工具很多团队会把 skill 理解成“一段更长的提示词”或者“一个工具函数”这个理解不够准确。Prompt 模板是静态的它帮模型组织语言但它不能被调用、不能被执行、不能返回结构化结果。普通工具函数是动态的它执行具体操作但它没有业务上下文不关心什么时候该调用也只接受固定参数无法承载多步骤流程。Skill 是介于两者之间的东西。一个 skill 可以包含系统提示词片段、工具函数、业务规则、输入输出校验、异常兜底甚至包含一个带固定顺序的多步流程。你可以把 skill 想象成“一个带操作规程的工位”普通工具是一把螺丝刀给你了还得自己知道怎么用、用在哪skill 是一个装配工位里面有螺丝刀、操作手册、质检标准和失败处理流程你只需要告诉它“装这个件”它就知道按标准做完。这个区别很关键。如果你的 Agent 只是一堆工具函数本质上还是在考验模型临场发挥如果用 skill 封装相当于把“临场发挥”变成“按选项作答”稳定性会高很多。1.3 什么时候值得引入 Skill 体系不是所有 Agent 都需要上 skill 体系。如果你的项目只有一两个工具模型随便调调就能完成那引入 skill 反而增加维护成本。但出现下面几个信号时就该认真考虑了同一个业务动作在多个场景反复出现但你每次都要在 prompt 里重复描述或者写一堆条件分支。工具数量超过十个模型开始出现明显的调用混淆。同一类操作需要多步完成比如“查订单”后面经常跟着“算剩余可退金额”。上线后的错误无法快速定位不知道是模型判断错了还是工具返回错了还是 prompt 写脏了。业务人员希望把某些流程固定下来不允许 Agent 自由发挥。skill 体系核心收益不是“更强的推理”而是“更好的控制”。你给 Agent 圈定了能力边界它才可能稳定地执行复杂业务。2. 怎么设计一套可复用的 Agent Skill2.1 Skill 的核心构成声明、上下文、执行体、校验我建议每个 skill 至少拆成四层缺一层后面都会难受。第一层是元信息声明。包括技能名、版本号、描述、标签、作者、输入输出 schema。这一层是给 Agent 看的“说明书”也是给开发者和运维看的检索目录。描述写得好不好直接决定 Agent 会不会正确调用。第二层是上下文。这是 skill 运行时的系统提示词用来引导模型在调用该技能时如何组织语言、如何处理边界情况。比如一个“生成退款原因”的 skill它的上下文里应该写明“退款原因需从预设枚举中选择不要自行编造业务术语”。上下文不需要很长但必须把该 skill 的专属规则写清楚。第三层是执行体。实际操作逻辑可以是一个函数、一个 API、一个低代码流程甚至是一次外部服务的调用。执行体负责把模型传进来的参数落地成真实操作并返回结构化结果。第四层是校验与兜底。校验包括输入检查、输出格式检查、业务规则检查。兜底是指在超时、报错、参数非法时返回一段模型可以理解和转述的友好错误信息而不是直接抛出一个堆栈。没有这一层Agent 遇到异常就只能“胡编”一个假结果。一个可参考的 skill manifest 长这样name: get_order_status version: 1.2.0 description: 当用户询问订单当前状态、物流进度、预计送达时间时使用。 仅当订单号存在且用户身份校验通过后才可调用。 不要用于查询售后、退款或发票状态。 tags: [ecommerce, order] input: order_id: type: string required: true description: 订单号通常以ORD开头 output: status: type: string enum: [pending, paid, shipped, delivered, canceled] logistic_track: type: array required: false executor: type: http endpoint: /v1/order/status timeout_ms: 3000 fallback: type: default message: 订单查询失败请稍后重试这样的 manifest 有两个好处一是人和机器都能读二是可以作为后续自动化测试和版本对比的基础。2.2 接口设计让 Agent 知道“什么时候用、怎么用”Skill 的接口设计最核心的不是参数类型而是描述。模型不像人一样看代码它只能通过描述来“理解”技能。描述写得太笼统模型会过度调用写得太死板模型该用的时候又不用。我自己的写法习惯是三个要素触发条件、执行边界、排除条件。触发条件说明“什么情况下用”执行边界说明“调用时要注意什么”排除条件说明“什么时候千万别用”。比如好的描述 当用户询问订单当前状态、物流进度、预计送达时间时使用。 调用前必须确认用户已登录且订单号属于当前用户。 如果用户是在询问退款进度请使用 refund_status 技能不要使用本技能。 差的描述 处理订单相关的问题。差的描述里“订单相关”四个字模型的解读空间太大了它会把用户关于退货的、发票的、投诉的所有问题都往这个 skill 上靠。描述写清楚边界以后调用准确率通常能提升一大截。参数设计上尽量让模型填写“少而准”的字段。能枚举的用枚举能默认的给默认值不要放太多自由文本。自由文本越多模型越容易编造。比如“用户意图”这种字段就不要让模型推断直接让模型从几个固定选项里选。2.3 技能编排从单 Skill 到组合 Skill单 skill 解决的是单一动作但真实业务里 Agent 经常需要组合动作。比如“用户申请退款”可能涉及查订单状态、算可退金额、校验售后规则、创建售后单。如果这四步全部暴露给 Agent它就得自己编排顺序稍不注意就会漏掉中间某一步。所以在 agent-skills 的设计里我会额外区分“原子 skill”和“流程 skill”。原子 skill 执行一个不可再拆的动作流程 skill 编排多个原子 skill并且固定内部顺序。模型只需要调用流程 skill流程 skill 自己按顺序执行子步骤步骤之间不需要模型参与判断。这个设计的好处是关键路径被代码或者配置锁死了模型无法跳过风控校验也无法先创建售后单再查可退金额。对于高风险的业务流程这种“锁顺序”的做法非常有必要。不过要注意一点流程 skill 不要做得太死要给模型留一点选择空间比如同一个流程里某些可选步骤根据实际情况跳过。死板和稳定之间需要拿捏。2.4 命名和目录组织直接影响调用成功率命名这件事很多人不重视实际上它直接影响 Agent 的调用准确率。模型在决定使用哪个 skill 时会同时看名字和描述。如果你的 skill 叫handle_order还有另一个叫process_order模型大概率会困惑。我建议用“动词 业务对象 领域”的格式比如get_order_status.ecommerce、create_refund.after_sale。动词用英文标准词汇不要自创缩写。目录组织上我会按业务域建目录每个 skill 独立一个文件夹里面放 manifest、执行代码、测试用例和文档。目录结构类似这样skills/ ecommerce/ get_order_status/ skill.yaml run.py tests/test_cases.yaml create_refund/ skill.yaml run.py tests/test_cases.yaml finance/ get_invoice/ skill.yaml run.py tests/test_cases.yaml每个目录就是一个可以独立发布、独立回滚的单元。团队协作时不同人负责不同业务域互不干扰。Agent 启动时会扫描整个目录把每个 skill 的声明注册进技能库供模型调用。3. 实操从零实现一个最小可用的 Skill3.1 选型用 LangChain / 自研 / 开源框架实现 skill 前先解决一个现实问题用什么框架。如果你已经在用 LangChain、LlamaIndex 这类框架那直接在工具层做封装就行。LangChain 里的BaseTool、Tool本质上就可以作为 skill 的载体你把 metadata、description、校验逻辑塞进去Agent 就能识别和调用。好处是上手快坏处是框架本身升级频繁有时候接口一变技能包就得跟着改。如果你希望完全掌控也可以自己写一个轻量注册器。一个基础抽象类加上一个注册表再加一个加载目录的函数其实不到两百行就能搞定。自研的好处是逻辑透明不依赖框架坏处是所有能力都得自己造轮子比如长上下文记忆、模型调度这些还是要自己接。我个人更推荐“轻量抽象 实现分离”的方式。核心只定义 skill 的规范和接口执行体可以是任意后端。这样不管外面用 LangChain 还是自研框架都能适配。agent-skills 这个项目的核心价值其实就在于这层抽象规范。3.2 Step 1定义 Skill 元信息拿最经典的“查订单状态”举例。第一步是写好skill.yaml这个文件是所有后续工作的基础。name: get_order_status version: 1.0.0 description: 当用户询问订单状态、物流进度、预计送达时间时调用。 调用前必须确保 order_id 格式正确且属于当前用户。 不要在用户询问退款进度时调用请使用 create_refund。 tags: [order, query] input: order_id: type: string required: true pattern: ^ORD\\d$ description: 用户订单号通常以 ORD 开头 user_id: type: string required: true description: 当前登录用户 ID output: status: type: string enum: [pending, paid, shipped, delivered, canceled] carrier: type: string tracking_number: type: string元信息里我最看重三个字段description、input的required、output的enum。描述决定模型会不会调用必填字段决定调用时的参数完整度枚举值决定模型拿到结果后怎么理解。这三个字段一旦设计错后面改起来成本很高。3.3 Step 2实现 Executor 与校验逻辑元信息定义好后写执行体。执行体可以是 Python 函数、HTTP 接口、数据库查询或者调用第三方服务。我通常把校验放在执行体最前面宁可多花几毫秒校验也不要让脏参数流到业务系统里。一个简单的注册式执行体如下from agent_skills import Skill, register register class GetOrderStatus(Skill): name get_order_status version 1.0.0 def run(self, order_id: str, user_id: str) - dict: # 基本校验 if not order_id.startswith(ORD): raise ValueError(order_id 格式不正确) # 这里可以调用内部订单服务 result order_service.query(order_id, user_id) # 输出结构标准化 return { status: result[status], carrier: result.get(carrier, ), tracking_number: result.get(tracking_number, ) }这里有一个很容易踩的坑执行体里不要写大段业务注释更不要把模型可能用到的判断逻辑写进注释。执行体只负责执行和返回业务规则应该写在上下文或者校验逻辑里。注释写太多模型读不到反而让代码不好维护。3.4 Step 3把 Skill 注册进 Agent 的工具箱执行体写完后需要把 skill 注册到 Agent 运行时的工具库。如果你用的是 LangChain可以这样做from langchain.tools import tool from agent_skills import load_skill_registry registry load_skill_registry(skills/) tools [] for skill in registry: tools.append( tool(skill.name, skill.run, skill.get_schema()) ) # 然后把 tools 传给 Agent agent create_agent(toolstools, instructions...)注册本身不复杂复杂的是注册前的“技能可见性”设置。并不是所有 skill 都应该对模型可见。我把 skill 分为三档默认可见、按用户可见、按上下文可见。比如内部财务数据查询的 skill只对财务域用户可见而“生成问候语”这类通用 skill 对所有用户可见。这个可见性过滤要在注册时做掉不能让模型自己去猜能不能用。3.5 Step 4用测试集跑通并记录效果skill 上线前我通常会准备一组评测问题集每个 skill 至少二十到五十条。问题集覆盖正例、反例和边界情况目的是测模型的调用决策不是测执行体本身。正例是应该调用这个 skill 的问题比如“我的订单 ORD12345 到哪了”。反例是绝对不该调用这个 skill 的问题比如“我要退款”。边界情况包括订单号缺失、订单号带空格、用户同时问多个订单。跑完测试集后我会记录几个指标调用准确率、漏调率、误调率、参数完整率。调用准确率是模型正确选择 skill 的比例漏调率是该调用但没调用误调率是不该调用了。这三个指标能帮你快速发现 skill 描述写得有没有问题。4. 踩坑记录我把 Agent Skill 用坏的几个瞬间4.1 技能描述写得太“文学”Agent 根本不按规矩来我第一次给退款 skill 写描述时用了“优雅地处理用户退款诉求”这种说法结果模型把所有带情绪的投诉都识别成了退款诉求退单率飙升。后来我把描述改成“仅当用户明确表示要求退款并且订单处于可退款状态时调用”误调率立刻降了下去。经验是描述里不要用形容词不要用模糊的业务黑话要用“明确信号 排除条件”的结构。“明确信号”是用户话术里出现的具体词比如“退款”“退钱”“排除条件”是你不希望模型误入的路径比如“如果用户同时在投诉物流请先调用投诉登记技能”。描述越具体模型的判断越准。4.2 技能之间互相打架参数冲突当技能数量多了以后会出现两个技能功能重叠。比如我有get_order_status和track_order功能几乎一样模型随机挑一个导致日志里同一种操作出现两套调用链后续数据分析完全对不上。后来我把重复技能合并只留一个并且把所有同义词写进描述里。另外参数冲突也很常见一个技能用date另一个技能用time模型在跨技能传参时会传错。我建议所有 skill 统一一套公共参数命名规范比如日期统一用date时间统一用datetime用户标识统一用user_id。4.3 校验过严把正确结果也拦掉了为了安全我给输出加了很严格的 schema 校验要求每个字段都不能为空。结果模型的正确输出反而被拦截了比如物流公司名确实为空因为订单还没发货。模型为了通过校验开始编造“默认物流公司”这种假数据。后来我改成“必要字段强校验非必要字段弱校验”。status不能为空carrier可以为空但必须显式传空字符串。校验失败时不要直接抛错要把失败原因记录到日志里并把原始结果传给下一层判断。这个改动之后假数据问题彻底消失。4.4 盲目追求“全自动”忘了人在回路有一段时间我尝试把退款流程也做成全自动Agent 判断、Agent 执行、Agent 确认结果虽然快但出了一次问题用户其实没想退款只是问“如果退款的话能退多少”模型直接提交了退款申请。从那以后我把高风险 skill 改成“提议模式”Agent 只负责给出方案执行前必须由人确认。具体实现是在 skill 里加一个require_confirm: true字段。Agent 执行完前置判断后先输出“我准备执行以下操作”等用户确认后才真正调用执行体。这样既保留了 Agent 的效率又守住了业务底线。凡是涉及资金、权限、外发消息的操作我都建议走这个模式。5. 进阶Skill 的版本管理与跨项目复用5.1 把 Skill 做成“配置驱动”等 skill 多到一定程度你会发现直接在代码里加注册注解这种方式不好维护。新增一个技能要改代码、重新部署效率太低。我现在会把 skill 的 manifest 放到配置中心里执行体仍然发版但注册信息和描述支持热更新。这样做的好处是当你发现某个 skill 的描述导致误调率偏高可以直接在配置中心改描述不用重新部署整个 Agent。改完以后系统自动记录新版本跑一轮测试集就能对比效果。这个链路跑通之后模型侧的优化节奏会快很多。5.2 测试回归与效果基线Skill 描述是一个“脆弱的优化点”改一次可能提升准确率也可能引入新问题。所以每一次改动都要有回归记录。我会把测试集固定下来每次改完描述或参数后跑一遍记录调用准确率、误调率、漏调率。如果某个指标下跌超过两个点就自动告警。这个测试集不是死的也要持续补充新的真实用户语料。每周我会抽一些线上日志里调用失败的案例加入测试集确保回归集和真实场景不会脱节。说白了技能质量不是开发出来的是养出来的。5.3 社区生态与协议统一agent-skills 的终极目标应该是让不同团队、不同公司的技能包可以像 npm 包一样互相分享。当前最大的障碍是协议不统一你的 skill 描述结构是这样我的工具列表是那样模型接入时还得适配。好消息是社区已经有一些可参考的方向比如模型上下文协议MCP它把工具和服务之间通信方式做了标准化。如果你正在设计自己的 skill 注册表最好在设计时就预留出对外暴露接口的出口比如支持把 skill 快速包裹成标准协议供外部 Agent 调用。这样你的技能包才能跨项目、跨团队复用而不是只活在某一个项目里。5.4 后续可以怎么扩展再往后走我想把 skill 的自动生成也纳入流程。输入一段业务描述系统自动生成 manifest 草稿、测试用例建议和上下文提示词开发人员只负责审核和调整。这样做能大幅降低新技能的接入成本。另外还可以做 skill 的依赖关系分析。当一个底层 API 被多个 skill 依赖时出现故障时能快速算出影响面并按依赖树做降级。这个能力一旦有了Agent 的运维复杂度就不会随着技能数量线性增长。6. 一些零碎的体划算作结尾做 agent-skills 这类项目时间越长越觉得“能力封装”比“能力生成”更重要。大模型本身能做的事情很多但在真实系统里我们需要的不是它什么都会而是它在特定边界内把事情做对。Skill 就是在模型和业务之间加一道“边界闸门”既保留模型的灵活性又把关键路径锁死。我自己在实际操作中最受益的一个小习惯是每次写新 skill 之前先逼自己写三个反例问题出来。反例不是代码而是用户可能真的会发出来的、但你不希望这个 skill 去处理的话。把这些反例写进测试集再倒推描述怎么写。这样做下来skill 的上线质量会明显好于“先写功能再补描述”的流程。另一个小技巧是不要指望模型从零开始记住所有技能。技能库大了一定要分层常用技能放第一层长尾技能放第二层让 Agent 先做粗分类再做细调用。这个过程听起来复杂但实际上就是把每个 skill 打上更细的标签让调度路径更清晰。以后这个项目还可以继续做技能可视化、技能依赖图、技能自动降级。但眼下最值得做的还是把每个 skill 的定义、测试、上线、回滚这条链路做扎实。毕竟 Agent 应用真正拼的不是谁的模型大而是谁的能力边界更稳。