1. 从“提示词堆叠”到“技能库治理”agent-skills解决的三个真实痛点如果你最近在搭建Agent类应用大概率经历过同样的窘境项目初期靠着一大段精心设计的System Prompt把任务跑通感觉一切尽在掌握可一旦功能变多、分支变复杂提示词开始互相打架改一个需求牵一发动全身最后连自己都不知道这段逻辑为什么会在那里。我在这段摸索期里反复折腾了几个月最终把重心从“写提示词”转移到“建技能库”上也就是围绕agent-skills这套思路做重构。这篇文章就把我在这条路上踩过的坑、沉淀下来的方法、以及真正扛住线上压力的经验完整梳理一遍。先说清楚agent-skills到底是什么。它不是某个单一框架的专有名词而是一类实践方向把Agent能够执行的原子能力从对话提示词里剥离出来做成结构化、可注册、可编排的技能单元。每个技能单元有明确的名称、触发条件、输入输出契约、校验逻辑和失败回退策略。Agent本身只负责理解意图和做调度决策真正的执行动作全部下沉到技能层。这套思路能落地的原因也很朴素。LLM天然擅长语义理解和多轮交互但在执行确定性操作时并不可靠——同一个句子换个说法LLM就可能给出不同判断更别说涉及数值计算、时间计算、字符串处理这类对精度敏感的场景了。把这类操作固化成技能本质上是给LLM提供了“知道自己能做什么、不能做什么、做的时候输入什么、做完怎么验证”的确定性底座。我见过太多团队在项目初期用一句“你是我的全能助手”开局后面越接越痛苦。真正可维护的Agent核心思路恰恰相反把“全能”拆成若干“专能”再通过编排把它们组合成更像全能的效果。这就像一个人不会每个领域都精通但一个分工明确的团队可以完成跨领域的复杂任务。技能库就是给Agent配的这支队伍。我整理了一个常见痛点和对应解法的对照方便你快速判断自己是否也处于这个阶段症状根因agent-skills思路提示词超过2000字后改不动逻辑耦合在文本里将行为拆成独立技能提示词只剩调度逻辑同一个操作在不同对话里结果不一致LLM每次推理都有随机性用确定性代码实现操作LLM只负责决定用哪个新功能上线后老功能回归没有隔离和契约技能内部自治契约不变则行为不变测试只能靠手动对话验证没有可执行单元技能可脱离对话独立测试这个表基本概括了我从“提示词驱动”转向“技能驱动”的全部理由。接下来我会从技能的构造、搭建流程、编排方式、踩坑记录和进阶方向五个层面展开内容会更接近实操手册而不是概念科普。2. 一次技能拆解三层结构和两条铁律很多人以为“把函数封装一下给Agent调用”就算技能化这其实只完成了一半。一个能够稳定嵌进Agent工作流的技能至少要包含三层结构。2.1 接口层让LLM知道技能“长什么样”接口层解决的是“可发现性”问题。LLM需要通过自然语言描述来理解技能的存在、何时使用、怎么传参。接口描述写得模棱两可LLM就会在关键时刻把技能视而不见。我在实践里会为每个技能维护五要素技能名称短、无歧义、动词优先如calculate_unit_price而不是unit或compute功能摘要一句话说清楚“这个技能做了什么”控制在30字以内避免和别的技能重叠触发场景告诉LLM什么情况下应该调用。这里要写具体“当用户提到价格对比时”比“需要计算时”更明确参数说明每个参数的类型、取值范围、默认值、是否必填。这个部分必须精确到字段级别输出说明返回值是什么结构、错误时返回什么。LLM需要知道调用后能得到什么才能决定下一步接口层还有一个反直觉的经验与其写“灵活处理各种情况”不如写死边界。例如某个技能只处理国内快件运费估算那么接口描述里就要明确“非国内快件请调用另一个技能或直接告知用户不支持”。边界写清楚反而能减少LLM擅自发挥。2.2 行为层把“大模型推理”变成“确定性执行”行为层是技能的实际执行代码。它应该做到给定相同的输入永远返回相同的输出。这也是技能区别于提示词最大的地方。我通常会在这个阶段思考一个问题哪些操作必须下沉为代码标准有三条涉及精确计算的金额、时间差、百分比LLM的算术能力不可靠涉及外部数据查询的数据库、API、文件系统需要稳定完成网络请求和鉴权涉及格式转换的JSON重组、CSV生成、日期规范化LLM经常会在格式细节上犯错反过来说那些开放性强的任务——比如“用一句话总结这篇文章的情绪”——不太适合做成技能内部的确定性逻辑更适合交给LLM本身。技能库不是为了消灭LLM而是为了让它专心做自己擅长的事。行为层实现时我建议把可能的异常全部显式捕获并且返回结构化错误。一个大致的错误返回模板如下{ success: false, error: { code: INVALID_PARAM, message: 参数price必须是大于0的数字实际收到: -12.5 } }LLM看到这种结构化错误能做两件事一是修正参数后重试二是向用户解释失败原因。最怕的是技能内部throw一个堆栈信息LLM读不懂只能硬着头皮瞎猜。2.3 校验层不信任任何人传进来的参数校验层是很多人会忽略的部分但我觉得它是整个技能库最能减少线上事故的设计。规则很简单技能内部不能信任任何来源的参数无论是LLM生成的参数、用户输入、还是上游系统传过来的数据进入技能前一律过校验。举个例子一个send_email_reminder技能参数里有recipient和subject。你以为LLM会规规矩矩传一个合法邮箱但实际运行时可能出现空字符串、无符号的假邮箱、甚至换行符注入。如果技能不做格式校验一封错误邮件就发出去了。校验逻辑我一般直接放到行为层入口处不会单独抽层保证每个技能自我完备。常用校验手段包括必填字段硬校验缺失直接返回MISSING_PARAM类型和范围校验数值类字段判断是否在合理区间格式校验依赖正则表达式匹配邮箱、手机号、日期等关联校验比如时间范围的开始时间不能晚于结束时间校验层的价值不光是防错更重要的是给LLM提供了一次自我纠错的机会。当它收到INVALID_PARAM这类错误时会重新审视自己的参数构造逻辑往往第二次就能传对。这个流程叠加到Agent调度循环里能显著提升任务成功率。2.4 两条铁律低耦合、可组合最后总结我在设计技能时最看重的两条铁律。第一条技能之间不互相调用。技能A和技能B如果需要协作由上层编排逻辑串联而不是技能内部直接import另一个技能。技能之间保持低耦合测试时才能独立验证。一旦允许技能互相调用依赖关系会迅速膨胀改一个技能的行为可能引发连锁回归排查成本不可控。第二条技能追求“小而专”拒绝“大而全”。一个技能只做一个逻辑单元。拿商品价格计算来说拆成fetch_price_data、calculate_discount、format_price_report三个技能比做一个handle_pricing巨石技能要灵活得多。前者的组合方式更多后者的复用场景几乎为零。这两条铁律让我在做技能编排时省了大量心。接下来讲具体搭建流程时你会发现它们贯穿始终。3. 从零搭技能集一套可以直接抄的六步流程不少朋友看了前面的概念会觉得有道理但真到自己动手时不知道从哪里切第一刀。这里我分享一套经过反复验证的流程每一步都是实操过的不是纸上谈兵。3.1 盘点现有交互圈定技能边界第一步不是写代码而是回看Agent的历史对话日志。把你目前所有需要Agent完成的任务全部列出来然后逐条问三个问题这个操作是否具备确定性答案即给定输入是否应当得到唯一输出这个操作是否会被多个场景复用这个操作是否需要外部资源API、数据库、文件配合三个问题里有两个及以上回答“是”这条操作就值得技能化。我见过一个典型误判把“写宣传文案”也做成技能。这个任务本质上需要创造性和语境理解写成确定性技能反而会让文案变得僵化。它的归宿应该是Agent自身的生成能力而不是技能库。用这套筛选标准当时我手头二十几个交互需求里真正值得先技能化的大概只有一半。3.2 定义技能契约先写“说明书”再写实现这一步往往最反直觉先不要急着写代码而是把技能接口定义写清楚。我会为每个技能创建一个skill.yaml文件放在专门的skills目录下。这个文件是技能对外界唯一的承诺也是LLM获取技能信息的主要来源。一个最小可用的定义长这样name: estimate_shipping description: 根据重量和目的地估算快递运费仅支持国内地址 trigger: 用户询问运费、快递费用、邮寄价格 params: weight_kg: type: number required: true min: 0.1 max: 100 destination: type: string required: true description: 省级行政区名称如浙江、广东 origin: type: string required: false default: 上海 output: success: 返回含预计运费金额的JSON对象 failure: 返回带错误码的结构化错误这个文件的价值有三个层面。第一它是人和人之间沟通的契约团队成员不用翻实现代码就能理解技能。第二它是LLM获取能力的入口技能注册就是把这些yaml喂给模型。第三它是测试和文档的统一来源接口稳定意味着周边依赖稳定。3.3 实现行为逻辑保持纯粹性说明书定了之后再动笔写行为代码。这里我坚持一个原则行为逻辑内部不直接感知“大模型”的存在。什么叫不感知就是技能的入参、出参、异常处理全部是纯粹的程序行为不依赖LLM的流式输出、不假设上下文、不读取外部Prompt。这样做的最大好处是技能可以被单元测试直接覆盖也可以在命令行里单独调用验证。以Python为例一个技能模块的结构大概是def run(params: dict) - dict: validated validate_params(params) try: result calculate(validated) return {success: True, data: result} except DomainError as e: return {success: False, error: {code: e.code, message: str(e)}}这段代码不关心是谁调用了它也不需要知道外面是不是Agent环境更不需要引入LangChain之类框架的抽象。技能是整个链路里最稳定的部分稳定到可以直接被任何人调用。3.4 编写离线测试用例摆脱对话调试技能写完后的验证方式建议大家直接放弃“在对话流里反复试”这种路径转而写离线测试用例。我会给每个技能准备两组用例。一组是正常路径覆盖典型输入和边界输入。另一组是故障路径覆盖缺参、类型错误、超范围、外部服务超时等情况。离线测试的意义在于把技能的稳定性验证从黑盒对话中剥离出来让每一次改动都有快速反馈。故障路径用例尤其重要。比如estimate_shipping技能在被传入weight_kg为0时会怎样被传入“杭州余杭区”这种带区县的地址会怎样被传入不存在的省份会怎样这些情况在真实对话里几乎必然发生只有提前在测试里验证过线上遇到时才有底气判断到底是技能的问题还是Agent调度的问题。3.5 注册到技能目录做一次实站对话验证离线测试全部通过之后才把技能注册到Agent运行时中。注册时我会把技能的名称和描述一起注册并立即做一组实站对话验证。每组对话验证固定覆盖三个场景直接触发、间接触发、不触发。直接触发是从用户的明确需求开始看Agent能否快速选中技能。间接触发是用户用同义表达描述需求看Agent能否透过语义识别意图。不触发是给一个无关请求看Agent会不会误调用技能。这一轮往往能暴露出接口描述里的歧义语言描述不精准的问题只有在这种验证里才看得清。3.6 纳入版本管理让技能演进可追溯最后一步是把技能纳入git管理每次修改如果涉及契约变更必须更新版本号并在变更日志里记录原因。有些团队会跳过这一步觉得一个小技能不值得管版本。但一旦技能数量超过十几个、多个Agent共享同一套技能库时没有版本管理就是灾难。你根本说不清“上次那个错误运费结果”到底是哪个版本的技能跑出来的。我的做法是给每个技能目录加上简单的VERSION文件配合git tag记录发布历史。这个习惯看起来土但关键时刻非常救命。4. 技能编排实战让Agent在正确时机选中正确技能技能库从0到1的过程中最令人兴奋但也最容易翻车的就是编排环节。技能注册好之后Agent需要理解什么时候调用哪一个。这里的核心不是技术栈多先进而是信息呈现和组织方式是否足够清晰。4.1 方案一全量技能清单检索排序最朴素的编排方式是把所有技能描述拼接后一起放进上下文让LLM自行选择。这种做法在小规模技能集少于10个时表现不错但技能一旦增多描述文本会变得很长LLM的注意力被稀释选错技能的频率明显上升。我当时的实测数据显示技能集从8个扩到20个之后选择准确率掉了将近8个百分点。问题不在LLM能力下降而是信息太多了长文本里的关键信息容易被淹没。这就像让一个人记住20个工具的位置去完成一个任务难度显然高于记住8个。4.2 方案二分组路由组内精拣提升准确率最有效的方式是先按领域将技能分组再叠加一层轻量路由。举个例子我当时的技能集分成两组订单域和内容域。一个订单相关的请求到来时路由层先判定“这是订单域”随后只在订单域内的技能里做精拣候选集从20个缩到8个选择准确率一下回升到和原来持平。路由层实现也无需多复杂。可以用一个快速分类提示词让LLM先输出领域标签也可以用关键词规则做初步过滤。路由层和第4层之间是顺序依赖的路由失败了后续就不会选对所以我会在路由层给LLM一个兜底选项“如果无法判断归属域请返回UNKNOWN”。一旦返回UNKNOWNAgent走通用处理逻辑不强行调用技能。4.3 冲突消解当多个技能都看起来“合适”时技能描述写得再清楚也避免不了边界模糊的情况。比如用户说“我要查上次订单的物流”这既可能命中“查询订单状态”技能也可能命中“查询物流轨迹”技能。两个技能描述里的trigger恰好都有重叠部分。我的解决办法是在技能描述里增加“不适用场景”字段主动圈掉一部分歧义。所有技能的yaml里都允许配置excluded_scenarios逼迫技能描述比触发描述更精细。上面这个例子里“查询订单状态”技能会加上一句“不适用当用户明确询问物流轨迹或快递位置时”。LLM看到这种显式排除项选错的概率大幅下降。如果两个技能的适用描述仍然高度重叠那说明它们应该合并成一个技能或者从职责上做进一步切分。技能拆分不是一个一次性的动作而是一个动态持续的过程。4.4 参数动态注入会话上下文里的变量技能调用不能只顾着选对技能参数的正确传递同样重要。很多Agent会在这一层翻车技能选对了但参数是从哪里来的完全没着落。我习惯在处理调度时建立一个“上下文变量池”把对话里已经出现的路面信息全部抽取并缓存。比如用户说“帮我查一下订单20250301的物流”这时候order_id和日期都已经在上下文里调度器在调用物流技能之前会先从变量池中尝试填充参数缺失的再向用户追问。参数填充顺序也有讲究。显式用户输入优先级最高其次是历史会话中已确认的实体再其次才是技能默认值。这个优先级如果不定义好很容易出现“用户后来更正了地址但Agent仍然用旧地址下单”的事故。4.5 失败回退链路选对了技能也得接得住失败技能执行失败并不可怕可怕的是Agent不知道失败之后怎么办。我从工程实践里总结出三层回退策略每一层都有清晰定义。第一层是参数修正重试。技能返回的错误码是INVALID_PARAM时Agent检查自己传的参数是否确实有问题修正后重试一次。第二层是降级处理。技能返回SERVICE_UNAVAILABLE时比如外部API挂了Agent改走逻辑降级用缓存数据或静态近似值代替并向用户说明数据时效性。第三层是转人工或明示失败。上述两层都走不通时Agent如实告知用户当前无法完成给出替代建议而不是强行编造结果。这个回退链路我会写进Agent的主循环逻辑里而不是依赖某个技能的内部处理。只要链路完整线上再乱的情况也有章法可循。5. 五个高频踩坑现场技能漂移、重复、参数污染、重试风暴和安全边界技能库能跑通只是第一步真正耐得住考验需要过五关。这些坑我每个都踩过有些甚至是同一问题上踩了两三遍才彻底想明白。把它们单列一节的目的是想提醒你这些坑不是偶然的而是技能化路线天然伴生的越早意识到越好。5.1 坑一技能漂移——同一个技能越改越偏技能漂移是我见过最隐蔽的问题没有之一。它的产生路径通常是这样某个技能接到了一个它“本来不该负责”的请求结果因为接口描述不够精确它硬着头皮处理了还误打误撞处理出了个像样的结果。于是这个场景逐渐被并入技能的范围日积月累技能内部塞满了各种边缘分支主路径反而被稀释。整改措施也是在实践中找到的每季度做一次技能契约审计凡是发现技能名不副实、描述和实现逐渐脱节的地方直接拆技能或重新立项不能放任其膨胀。审计的方式很土跑一遍所有技能的测试用例再人工阅读一遍技能描述感受一下“如果我是LLM我会怎么理解这个技能”。觉得别扭的地方就是漂移预警信号。5.2 坑二技能重复——两个技能抢同一个活儿当团队多人并行开发技能时技能重复几乎是必然出现的。比如有人做了一个parse_date技能另一个人做了一个normalize_time技能实际功能高度重叠。技能重复带来的直接恶果是LLM选择时困惑到底该用哪个两个技能都描述得对但行为可能有细微差别线上结果就不稳定。我最后定的规矩是任何人要新增技能必须先检索技能目录里是否存在同领域技能。确保没有重复才允许新建。同时技能列表导入LLM前做一次去重摘要把相似技能合并或标记。这个流程看起来繁琐但长期坚持下来给LLM省下了宝贵的上下文空间。5.3 坑三参数污染——历史会话里的脏数据渗透到技能调用参数污染是我在某次运费计算翻车后才彻底重视起来的。事故经过很简单用户先问了A地区的运费随后改成问B地区但Agent在第二次调用运费技能时误把第一次的A地区当作origin传了过去导致计算结果完全错误。问题出在我当时没有做“参数生命周期管理”。会话变量一旦被设置就默认永久有效但实际上很多参数是粘稠的、临时的、上下文敏感的。后来的修复方式是给上下文变量打标签单轮临时变量、多轮会话变量、用户显式确认变量。技能调用时只从对应标签的变量池取参用户明确变更信息后自动覆盖不再保留旧值。5.4 坑四重试风暴——失败后的无脑重试把系统打瘫接入外部API的技能如果遇到超时最糟糕的应对方式就是让LLM不断重试。LLM的调度循环加上技能内部的重试逻辑叠加起来可能形成双重重试Agent层失败重试一次技能层又重试一次外部服务还没有恢复结果就是雪上加霜的系统压力。现在我的策略是技能内部最多重试一次且必须是有阈值的指数退避在联调主循环层面只允许在特定错误码下重试其他错误码一律走降级或失败。同时在整个Agent入口做一个总重试次数熔断超过阈值就直接问用户“要不要现在再试一次”把决策权交还给人而不是让机器闭眼冲。5.5 坑五安全边界——技能权限越过“最小可用”红线最后一个坑最危险。技能在执行时需要访问外部资源如果技能内部把所有权限都捏在一起一旦某个技能被意外调用或参数被恶意构造外部资源的风险会被无限放大。现在我做Agent技能时会坚持两条规定每个技能只能申请自己执行任务所需的最小权限涉及高风险的技能发邮件、删数据、改配置、付钱必须增加独立确认环节由用户明确点头后技能才真正执行。这两条规定一开始觉得麻烦但有一次意外触发邮件技能后我更确信它们存在的必要了。6. 进阶方向技能评估、语义向量化和跨Agent共享技能库稳定运行一段时间后我的重心逐渐从“做功能”转向“做治理”。三个比较让我受益的方向在这里也分享出来。6.1 用自动化测试养一套技能评估集技能集维护最大的成本不是写代码而是判断“改了没改好”。于是我基于前面的测试用例又往前多走一步把技能绑定到一个自动化评估集上。每次技能改版或新增跑一遍全量评估记录成功率和耗时。这个评估集里既有单元测试级别的确定性校验也包含用LLM对技能输出做语义打分的环节比如“技能返回的运费是否合理匹配距离权重”。有了评估集之后优化技能就不靠感觉了而是看数字。当时我优化物流类技能的相关性问题连续迭代三轮每一轮都靠评估集确认提升幅度没有再出现改A坏B的烦躁。6.2 给技能描述上灰度检索的语义支持技能选择准确率如果还想再往上走光靠描述文本是不够的。我看到另一个做法把技能描述和参数说明做向量化让Agent在路由前先用语义检索召回候选技能。这种召回不是硬规则而是基于语义相关度来计算能覆盖用户更多变着花样的表达方式。我后来在这个方向尝试过一版把技能清单文本预先向量化存库用户请求进来自动算出TOP5相关技能再把这5个候选塞进LLM做精拣。效果是技能从20个就算塞到50个选择准确率也基本不掉。如果你Agent的技能库即将跨过30个这个方案可以重点参考。6.3 跨Agent共享技能一套技能服务所有入口公司内部可能不止一个Agent客服一个、运营一个、数据分析一个。给每个Agent各配一套技能库维护成本是好几倍。现在我把技能库抽成了独立服务所有Agent统一通过API注册和查询技能。想看客服Agent内有没有日志分析能力查询技能目录就一目了然。共享带来的额外好处是技能质量被“横向对比”倒逼提升了。一套技能同时在多个Agent里经受考验任何一环的问题都会更早暴露。跨Agent共享的技能需要更强的契约稳定性和更完善的过程机制这些都是正向压力。把技能当独立资产对待之后“Agent能做什么”就不再被某一个Prompt限制而是由整个技能库决定。这也是我在接手任何一个新的Agent项目时第一件会做的事——先盘点能用的技能再谈业务实现。