最近一直在琢磨agent-skills这个东西。说句实话，真正把 Agent 项目推上线之后，我才发现大部分团队对 Agent 的理解还停留在"提示词工程+大模型闲聊"的阶段，而决定一个 Agent 到底能不能干活、能不能稳定干活的分水岭，恰恰是技能层。所谓agent-skills，你可以把它理解成 Agent 的"手"——大模型负责想、负责说，技能层负责做、负责执行并返回结果。没有技能的 Agent 只能输出建议，有技能的 Agent 才能真正完成任务。
这篇文章不聊概念，只聊我在几个真实项目里拆 Agent 技能、建技能库、调技能协同过程中总结出来的经验。包括：技能和任务、工具的区别到底在哪；一次技能调用在系统内部经历了什么；怎么把一个业务动作拆成可复用的技能；多个技能打架的时候怎么排优先级；以及那些让你半夜起来修线上问题的坑。适合正在做 Agent 应用、打算把 LLM 接到业务流程里去的开发者，也适合想给团队培训 Agent 落地思路的技术负责人。
1. 为什么"会写提示词"不等于"会做 Agent"：技能层才是能力上限
很多团队起步做 Agent 时，第一反应是"把提示词写细一点、把 few-shot 示例给多一点"。这个思路没有错，但天花板非常明显。提示词再精细，模型也只是在"生成内容"，它没有办法真正去查数据库、调接口、操作文件、触发工单系统。Agent 要落地，必须有一层东西替它把这些动作做了，并且把动作的结果重新组织成语义清晰的文本喂回给模型，模型才能继续往下推理。这一层，就是技能层。
1.1 技能不是任务，也不是工具
我见过好几种混淆。有人把技能等同于任务，说"我的技能是做一个 PPT"，这不对。任务是目标，技能是实现目标的能力单元。做 PPT 这个任务，背后至少需要"生成大纲""收集素材""排版渲染"三个技能协同完成。还有人把技能等同于工具，说"技能就是封装好的 API 调用"，这也不完整。工具是执行器，技能应该包含工具定义、输入参数协议、输出规范、错误码语义、触发条件描述，甚至包含一小段"这个技能适合在什么场景下用"的说明。工具是零件，技能是带说明书和接口协议的完整组件。
打个比方。你雇了一个助理，助理会使用 Excel，这是工具能力；但助理懂得"当老板说整理销售数据时，应该先清洗空值、再按区域汇总、最后生成带趋势注释的表格"，这才是技能。技能 = 工具 + 使用工具的规则 + 处理边界情况的经验。
1.2 agent-skills 要解决的核心矛盾
实际项目里最大的痛苦是：大模型返回的结果天然不确定，而业务流程不能容忍不确定。今天模型心情好，调用了技能 A；明天同样的输入，它可能自作聪明绕过 A 直接口胡答案。agent-skills要解决的，就是把这层不确定压缩到最小。
解决思路不是用更多提示词去"教育"模型，而是把能确定的部分全部固化成代码逻辑和协议校验。什么技能可以被调用、参数必须符合什么 Schema、返回结果必须是什么结构、失败时必须返回什么错误码，全部在技能层用规则限定。模型只在"选哪个技能、传什么参数"这两件事上保留自由裁决权。调度越规范，系统越可靠。
1.3 为什么技能库需要持续沉淀和治理
一旦 Agent 接入真实业务，技能数量不会停留在两三个。我见过一个做内容运营的 Agent 项目，半年时间技能数量从 5 个膨胀到 80 多个。技能多了之后，新问题出来了：描述相似的技能互相覆盖、参数命名混乱、返回结构不统一、多个技能写同一个数据源导致状态错乱。没有治理机制，技能库就是垃圾堆。
所以在这篇文章里，我给的实操方案不是简单的"封装几个函数给模型调用"，而是把agent-skills当作一个独立的子系统去设计：有注册规范、有参数协议、有冲突策略、有测试回归。这听起来重，但一旦技能数量超过 20 个，你的维护成本会指数级下降。
2. 一次完整的技能调用长什么样：协议、状态与反馈闭环
想设计技能库，先得弄清楚一次技能调用在系统内部到底走了哪些环节。很多人在第一步就漏了反馈闭环，导致技能结果没有回流到对话上下文，Agent 变成了"答非所问的传声筒"。
2.1 技能调用的七步链路
我习惯把一次技能调用拆成七个环节，任何环节断了，整个交互都会出问题。
用户请求进来后，Agent 先做意图识别，判断"用户想要的结果需要哪些能力"。然后是技能选择，模型基于技能名和描述决定用哪个。接着是参数填充，把用户输入、上下文信息映射到技能 Schema 定义的字段上。此时会过一个参数校验器，不合法的直接被拦截，不会进入执行器。
校验通过后执行器开始跑真正的业务逻辑，可能是一次 API 调用、一次数据库查询、一段本地计算。执行完之后要格式化输出，把真实结果整理成预设的结构化数据。最后一步最容易被忽略：状态回填。执行日志、耗时、结果摘要、错误信息必须写回系统状态，供 Agent 后续决策使用。我见过有人做到第三步就停了，参数填进去、接口调通了，但模型完全不知道结果是什么，根本没有闭环。
2.2 技能协议的本质：给大模型一份"机器可读的契约"
技能层的核心产物是一份协议，而不是一段代码。这份协议要让大模型"看得到、看得懂、敢使用"。看得到，指的是技能名和描述能出现在模型可视范围内；看得懂，指的是参数定义清楚、枚举值明确、示例齐全；敢使用，指的是模型调用之后要么返回预期结构，要么返回明确的错误码，不会出现"调了等于没调"的情况。
以下是我在项目里常用的技能注册结构，用 Python 伪代码表示：
# 技能注册示例（伪代码） register_skill( name="content_risk_check", description="检测文本内容是否包含违规或高风险信息，返回风险等级与命中类别。" "当用户输入疑似广告、低俗、侮辱性内容时使用。", input_schema={ "text": {"type": "string", "required": True, "description": "待检测的原始文本，不超过5000字"}, "scenes": {"type": "list", "required": False, "description": "检测场景，可选值：comment, article, chat", "default": ["comment"]} }, output_schema={ "risk_level": {"type": "string", "enum": ["pass", "review", "block"]}, "hit_rules": {"type": "list", "items": {"type": "string"}}, "summary": {"type": "string"} }, error_codes={ "PARAM_ERROR": "输入参数不合法，请检查 text 长度或 scenes 枚举值", "SERVICE_UNAVAILABLE": "检测服务暂时不可用，可让用户稍后重试", "TIMEOUT": "检测超时，建议缩小文本规模" }, labels=["content_safety", "moderation"], version="1.2.0" )这个结构里有几个细节很讲究。description不仅要写技能是干嘛的，还要写清楚"什么时候应该调用"和"什么时候不应该调用"。比如内容审核技能，描述里最好加上"仅用于用户生成内容，不用于权威信息发布"，否则模型会把它误用于所有文本。error_codes的意义是让模型在技能失败时能向用户解释原因，而不是编造一个自己没做过的操作。labels用于技能检索和路由过滤，后续做多技能编排时非常有用。
2.3 输出格式化的三种常见模式
技能输出回填给模型时，有三种格式我常用的，各有利弊。
第一种是纯 JSON 结构化输出，适合后续还要做逻辑判断的场景。风险检测返回{"risk_level": "block", "hit_rules": ["广告词命中"]}，模型看到block就知道必须拒绝。
第二种是 Markdown 文本，适合面向用户的生成类技能。摘要生成、报告生成就是用这种，模型可以直接引用文本片段。
第三种是混合格式：关键字段留在 JSON 里做逻辑判断，同时在summary字段放一段人话摘要供模型理解。这是我最推荐的。既要让模型"会执行"，又要让模型"会解释"，缺少summary的纯 JSON 输出会让模型在跟用户沟通时显得很生硬。
2.4 超时与幂等：技能执行器的两条铁律
技能校验通过后跑业务逻辑，必须遵守两条铁律：超时要有上限，执行要幂等。大模型是流式推理的，它不会像人一样耐心等一个慢接口。我在项目里设的默认超时是 3 秒，超过就返回TIMEOUT错误码，同时清空当前技能占用的执行资源。
幂等性更容易被忽略。用户说了一句"把这篇内容推送到全部分发渠道"，如果技能执行了一半网络断了，系统重试时可能会推送两遍。设计技能时，凡是会写外部系统的操作，一律要求业务方提供幂等键。权衡原则是：宁可重试，不可重复生效。这个问题在技能并发执行时会放大，后面的章节专门展开。
3. 从 0 搭建技能库的方法：清单拆分、Schema 设计与参数校验
技能库不是拍脑袋堆出来的。我在一个新项目里做 Agent 能力规划时，基本会走一套固定的拆解流程：先做业务动作盘点，再做动作归类，然后逐个技能写协议，最后做交叉评审。这个过程看起来很重，但能避免后期大量返工。
3.1 第一步：用"动词清单"拆出候选技能
我可以直接给一个可复用的模板。召集业务负责人和一线执行人，一起列当前业务流程里所有"由一个角色独立完成、有明确输出物"的动作。规则只有一条：动词开头。
比如一个内容社区的后台 Agent，可能列出的动作有：审核文章、提取关键词、生成摘要、查重、封禁用户、发送通知、导出日报、生成周报、拉取异常评论、识别刷量账号。一个动作就能对应一个技能候选。如果一个动作包含了多个子步骤，继续往下拆。比如"审核文章"可以拆成"风险内容检测""敏感信息扫描""格式合规检查""审核结论输出"。拆到每个技能的执行逻辑能用一段函数说清楚为止。
我见过团队在这里偷懒，把"审核文章"直接封装成一个巨大的技能，输入一篇长文，输出一个审核结论。表面上看简单了，实际上这个技能内部有几十个分支，任何一个小改动都要重新回归，而且返回结构过于笼统，模型无法理解到底因为什么被拦截。技能拆分的粒度标准，应该是"一个技能只对一类问题产生一个响应动作"。
3.2 第二步：定义输入参数时要站在"模型的角度"
写技能协议时，最容易犯的错误是从后端接口的角度定义参数，而不是从大模型的角度定义参数。这两者经常不一样。
举个实际例子。某个审核技能要接收"用户名、年龄、注册时间"，这个信息后端接口里有，但模型通常不会精确知道用户的注册时间。把注册时间设为必填参数，模型要么瞎编，要么拒绝调用。正确做法是：必填参数只保留模型一定能从上下文拿到的字段，比如用户 ID、评论文本；拿不到的信息要么设成可选，要么在技能内部通过用户 ID 反查补充。
再强调一个参数设计的细节：枚举值要尽量给全，并且每个枚举值要带语义说明。比如场景字段scenes的可选值["comment", "article", "chat"]，模型看到这三个英文单词不一定能准确映射用户意图。协议里可以加一层描述映射，明确告诉模型："content_post 包含动态、文章、评论等所有用户可发布的内容类型"。参数类型也要严格限定。字符串、整数、数组、对象必须区分清楚，否则模型经常把["a", "b"]传成"a,b"，执行器做.split(",")就出乱子。
3.3 第三步：输出 Schema 要同时兼顾"机器判断"和"模型人话"
我强烈建议每一个技能的输出结构里都配置一个summary字段。这个字段用来给大模型生成一段自然语言结果摘要。为什么必须单独做？因为模型不擅长自己解读 JSON。它看到{"status": 3, "code": "LIMIT_EXCEEDED"}，跟用户解释的时候很可能说"状态码是 3"，而不是"您的发布频率超过限制，请明天再试"。
summary应该由技能执行器生成，它可以是一段模板文本加参数占位，也可以是接入专门的小模型生成。关键是把逻辑判断结构（给系统看的）和语义表达结构（给语言模型看的）分离。我在技能规范里直接规定：summary必须不超过 50 字，必须包含面向用户的操作建议。少了这句话，技能输出再准，用户也感受不到 Agent 的智能。
3.4 参数校验器比模型更值得信任
参数校验器必须在执行器之前拦截非法参数。有些人觉得模型会自己遵守协议，不校验也没关系。这是侥幸。模型在上下文很长、多技能混跑的时候，很容易传错类型、传错枚举值、漏传必填项。校验器的作用是挡住这些错误，而不是把它们传递给后面的业务处理。
校验器要返回足够清晰的错误原因，比如"text 字段长度超出 5000 字限制，请分段提交""scenes 包含非法枚举值 xxx，仅支持 comment/article/chat"。这些错误原因会通过error_codes回传给大模型，大模型才能据此调整自己的调用。如果你的校验器只返回一句"参数错误"，模型还是会一脸懵。
4. 多技能协同中的调度难题：优先级、冲突与失败降级
单个技能的治理相对简单，真正复杂的是多个技能组合完成一个任务。Agent 的业务价值也在这里体现：它能像人一样把"查重 → 生成摘要 → 内容审核 → 发布 → 归档"串成一条流水线。但多条技能链路放在一起，调度上的问题很快就会暴露。
4.1 三种常见的技能编排范式
我在不同项目里总结出三种编排范式，适用场景差异很大。
第一种是顺序流水线。技能 A 的输出直接作为技能 B 的输入，比如"先提取实体，再基于实体做知识库检索"，这种结构简单，链路稳定，适合确定性强的流程。
第二种是路由分流。模型根据输入内容，把用户请求路由到不同的技能分支。典型如客服 Agent：查订单走订单查询技能，退换货走售后流程技能，投诉走人工升级技能。这种编排能降低单技能的复杂度。
第三种是动态规划。模型自己决定技能的组合顺序，甚至并行执行多个技能。这是最灵活也最不可控的，适合开放性任务，比如"分析一份合同"需要并行调用条款抽取、风险识别、关键信息校验三个技能。做动态规划时，必须依赖前面说的技能定义质量和上下文回填机制。
4.2 技能冲突的本质：共享资源的写权限
技能之间最容易打起来的是共享资源的写操作。两个技能同时更新同一个用户的状态字段，或者两个技能同时对同一个工单执行了"关闭"操作，结果必然互相覆盖。
我在架构里加了一个简单的资源锁服务，规则是：涉及写操作的技能，必须声明自己需要操作的资源 ID，系统在技能调用前检查该资源是否被其他技能持锁。冲突发生时，后到的技能返回RESOURCE_LOCKED错误，让大模型决定是等待重试还是向用户解释稍后再试。
同时，我给每个技能配置了一个优先级权重，并在技能描述里标注互斥关系。比如"账号封禁"技能的优先级永远高于"发送通知"技能。当模型同时选中这两个技能时，调度器会把通知延后，确保不会出现"先发通知说账号正常，下一秒又被封禁"的荒诞结果。
4.3 失败降级：最容易被低估的环节
技能一定会失败。接口超时、数据不存在、上游服务限流、参数被校验器拦截，这些都是常态。一个没有失败降级策略的技能系统，等于把 Agent 的可靠性交给了运气。
我落地的降级策略分为四级。第一级是重试，仅在错误码明确标识"临时失败"时执行，重试两次，间隔递增。第二级是降级方案，主技能不可用时切换副技能。比如"在线查重服务超时"时降级到"本地词库比对"。第三级是缓存兜底，读类技能优先查缓存，缓存里没有再去查真实数据源。第四级是人工接管，连续失败超过阈值时，把任务推到人工工作队列。每一级降级都要生成一条日志，供后续分析技能质量时使用。
4.4 组合技能的可观测性：链路 ID 是必需品
多个技能串成一条链路之后，排错难度比单技能调用高一个量级。用户反馈"刚才还能查，现在查不了"，如果没有链路 ID，你连是哪个技能出的问题都不知道。
我给每次用户请求生成一个全局链路 ID，每个技能调用都携带该 ID 写日志。定位问题时，只需要按链路 ID 拉出事件序列：意图识别记录、技能选择记录、参数校验记录、执行器返回记录、降级记录。日志里每一条都要带耗时和状态码。这套东西看起来是基建工作，但真正线上出了问题，它能救你一次。
5. 踩坑记录：技能误触发、上下文污染与安全边界
这部分全是真金白银换来的教训。我在不同项目里遇到的技能层问题，多数可以归结为五类：误触发、参数幻觉、上下文污染、权限越界、状态错乱。每一条单独拿出来都值得仔细复盘。
5.1 技能描述写得太抽象，模型就会"戏精附体"
有一段时间，我们给一个内容运营 Agent 加了一个"smart_reply"技能，描述写的是"智能回复用户消息"。结果模型几乎每个用户输入都优先调用它，不管用户是在问物流、在投诉、还是在下单。原因很简单：描述里的"智能回复"太泛了，它像一块万能砖，模型觉得什么墙都可以用它补。
后来我把描述改成了："该技能用于生成面向用户的回复文案。仅当已有明确回复观点且需要润色表达时使用。禁止用于查询类、操作类问题的最终答复。"加了两个限定词之后，误触发率显著下降。技能描述要像给 API 写 README 一样，把边界条件写在第一段，比把功能写在第一段更重要。
5.2 参数幻觉：模型会编造它没有见过的东西
有一次线上事故让我印象很深。用户问某商品能不能发到某个地区，Agent 调用了运费计算技能，参数里竟然出现了用户收货地址里根本不存在的门牌号。仔细查日志发现，模型在参数填充时"脑补"了一个合理解释，把之前对话里另一个用户的地址拼接进来了。这就是参数幻觉。
应对办法是在技能协议里加一条约束："未从上下文中获取的字段，一律置为空，不得自行推断。必填字段缺失时返回 PARAM_ERROR，交给用户确认。"同时，参数校验器要增加基础合法性校验，例如地址字段必须包含省市区关键字，手机号字段必须匹配 11 位数字。这些规则可能看起来幼稚，但它是防幻觉的最后一道防线。
5.3 上下文污染：技能结果不该无节制回填
大模型的上下文窗口是有限资源。早期我们图省事，把技能返回的完整 JSON 全部塞回上下文。结果跑了十几轮对话之后，上下文里堆满了几百行原始日志和字段定义，模型开始产生幻觉，甚至把历史执行结果当作当前状态。我称之为上下文污染。
现在我的规范是：执行器回填给模型的不是原始返回，而是经过裁剪的摘要。具体做法是，输出 Schema 里的summary字段就是设计用来回填的，原始 JSON 只落到日志存储，不进入上下文。另外，技能调用结束后要写一条系统级提示："已调用内容检测技能，得到风险等级 block，历史命中规则详见执行日志。"让模型知道结果有了，细节可以去日志里找。
5.4 技能权限越界：不是所有技能都该被所有用户调用
权限问题是最危险的一类。某个 Agent 项目开放了"内部报表生成"技能给前台客服使用，结果客服无意中触发了一次大规模数据导出。那时候我才意识到，技能层的权限控制不能依赖 Agent 的自我判断，必须在代码层面强制执行。
我现在会为技能打两个标签：可见性标签和操作权限标签。可见性标签决定技能是否出现在大模型的候选列表里，普通用户看不到"导出全量数据"技能；操作权限标签在执行器入口校验，用户身份的权限等级不够，直接返回NO_PERMISSION。技能层的权限本质上是"最小暴露原则"：只有确实需要的技能才暴露给模型，避免模型在复杂场景下选择了不该选的能力。
5.5 状态错乱：并发场景下的用户上下文隔离
技能设计为无状态是最理想的，但现实中很多业务技能需要记住前后状态。比如一个"多轮图书借阅"流程，第一轮技能记住了用户要借的书，第二轮技能要根据第一轮的结果做库存查询。如果状态保存在全局变量里，用户 A 和用户 B 同时操作，状态就串了。
我们的解法是把技能状态绑定到链路 ID，而不是绑定到会话级全局缓存。所有状态读写都通过带链路 ID 的键值存储完成。这样即便两个用户同时走同一套技能组合，状态也能彻底隔离。这个改造做完之后，并发场景下的错乱问题基本归零。
6. 技能质量的度量与回归：给 Agent 技能做"单元测试"
很多人把技能库上线之后就不再管了，这是很危险的。技能的触发率、成功率、参数非法率、回填污染指数都会随业务变化而波动。我在项目里建立了一套轻量的技能度量体系，有点像传统开发的单元测试和监控报表的合体，但它针对的是"大模型调用外部能力"这一层。
6.1 四个核心指标，代替拍脑袋评估
第一个指标是技能覆盖率。用户请求中，真正命中技能的比例。覆盖率太低说明模型经常选择自己回答而不是调用技能，需要检查技能描述质量。第二个是技能调用成功率。技能执行器成功返回比例，这个指标低通常意味着参数校验太严格或上游服务不稳定。
第三个是参数非法率。参数被校验器拦截的比例。这个指标偏高，说明技能描述和参数 Schema 没有对齐模型的理解。第四个是上下文回填增量。衡量一次技能调用占用了多少上下文 token，防止污染发生。我建议每个指标都按月做环比，一旦异常波动，优先检查最近一次技能协议调整。
下面是我常用的一张技能评估表：
| 技能名称 | 覆盖率 | 成功率 | 参数非法率 | 回填增量 | 主要问题 |
|---|---|---|---|---|---|
| content_risk_check | 92% | 98.7% | 2.1% | 180 tokens | 无 |
| smart_reply | 45% | 91.2% | 12.4% | 95 tokens | 描述边界不清，需收紧触发条件 |
| freight_calc | 78% | 88.5% | 8.7% | 240 tokens | 参数缺失率高，增加必填校验提示 |
6.2 黄金样本集：给技能做回归测试
技能协议一改，影响范围往往超出预期。我在项目里维护了一个"黄金样本集"，每个技能配了 10 到 20 条真实历史请求，包含触发场景、期望命中的技能、期望传入的参数、期望输出结构。每次调整技能描述或 Schema，都会跑一遍全量回归，查看覆盖率是否下降、参数非法率是否上升。
更重要的是，这个样本集不只是给开发看的。我会让业务同事也参与标注，把一线遇到的反常请求不断补充进样本集。样本集越贴近真实，技能回归就越有参考价值。测试不是为了证明技能没坏，而是为了尽早发现"模型对技能的理解是不是悄悄偏移了"。
6.3 让 Agent 自己报告"为什么没调用技能"
除了指标监控，我还有一个习惯：在 Agent 的系统提示词里加入一条指令，让模型在跳过技能直接回答时，附上一行reason，说明为什么没有调用任何技能。这些理由会累积成一份珍贵的数据集，用来分析是不是技能描述覆盖不到真实问题。
比如模型写"用户问题与现有技能的触发条件不匹配，因此未调用"，这可能意味着技能库存在盲区；如果写"担心调用技能会延迟响应"，说明模型对技能失败率有顾虑，需要检查技能可靠性。这些反馈信息比任何运维告警都更能帮你理解 Agent 的决策过程。
6.4 一次好的技能迭代，应该包含三个同步更新
最后分享一下我定义"一次完整技能迭代"的标准：必须同时更新代码逻辑、技能描述和测试示例。代码逻辑负责真实执行，技能描述负责让模型正确选择，测试示例负责防止回归。三者是铁三角，缺了任何一个，技能迭代都是在给自己埋雷。
举个实际例子。修改风险检测技能，让它支持新的违规类型，光把检测模型换掉是不够的。技能描述里必须加入"支持检测诱导分享类内容"的触发说明；测试示例里必须补充 3 到 5 条诱导分享的真实语料。这样下次模型遇到类似内容，才能想到调用这个技能去拦截，而不是自己凭感觉回答。
我在多个项目里验证下来，只要坚持这套铁三角式的迭代方式，技能库的质量是能持续向好的。而技能库质量，最终会直接决定你的 Agent 在用户眼里是"聪明的助手"还是"花哨的聊天机器人"。
