如果你亲手搭过几个AI Agent大概率会遇到这样一个现象模型单看很能打可真让它连续完成好几件事不是长上下文失忆就是在一个任务上反复打转。我后来把项目里所有给Agent用的能力描述、工具说明、角色约束、示例对话统一收进一套“agent-skills”体系之后才真正把这种漂移控制住。这篇文章不是概念科普而是一份我在生产环境折腾了大半年的实践总结重点讲清楚技能怎么定义、怎么组织、怎么调试、怎么迭代适合正在做Agent编排、自研工作流或者接各种Agent框架的朋友。下面写的是我从多个项目里沉淀出来的通用做法不是某个框架的官方规范但换到不同平台上基本都能落。1. agent-skills到底是什么从“会聊”到“会干活”的那层胶水先说一个容易被忽略的事实大模型本身不具备“稳定完成一个任务闭环”的能力它只具备“根据上下文生成下一个合理片段”的能力。你让它聊天、写文案很轻松但让它连续做“查数据、做判断、输出结构化结果”这种带确定流程的活儿它就会暴露问题不知道什么时候该用什么工具做到哪一步算完成出错之后该怎么办。agent-skills补的正是这一层。我给它下了一个比较朴素的定义技能是Agent完成某个任务时需要的一组结构化指令、判定规则、工具调用序列和输出约束的集合。它把一次任务从“让模型自由发挥”变成“按流程办事”。对比一下就清楚了工具是单个动作比如调用一个API、执行一段SQL技能是多个动作的组合可能还包含分支、重试和失败处理。提示词只是“说话方式”技能则是“做事的完整章法”。1.1 技能不是插件也不是提示词不少团队一开始会把Agent能力拆成工具清单和提示词两块但这两块都回答不了几个关键问题模型知道“有哪些工具可用”但它不知道“当前这个用户请求到底该匹配哪套流程”提示词能约束语气却约束不了判断顺序。插件更多是一个载体强调的是代码包如何被加载和注册而不是任务逻辑如何被组织。所以在我的项目里工具、插件、技能是三个不同层。工具永远是最小的执行单元负责“把某件事做掉”技能负责“围绕某个业务目标把步骤排好”插件则承担“把一批工具和技能打包分发”的职责。用大白话打比方技能是岗位上的SOP工具是SOP里用到的螺丝刀提示词是贴在工位上的沟通礼貌须知。螺丝刀再好SOP混乱活儿照样干不利索。这个区分直接影响了代码结构。如果你发现自己某个技能文件里塞了大量工具实现那说明你把工具和技能混在一起了。真正的技能应该只有“流程编排逻辑”和“对工具的描述与调用约定”工具本身还是独立封装这样技能才能在不同项目之间搬运。1.2 一个技能该包含哪些东西我习惯用一套五段式结构来写技能不管业务复杂度如何都先按这个框架起底概述描述、触发条件、参数协议、执行流程、输出规范。概述描述是给模型看的说明书说明这个技能解决什么问题、适用边界在哪里。触发条件用来判断当前请求是否命中技能这里不只写“什么情况该触发”还要写“什么情况不该触发”。参数协议定义了调用技能需要哪些输入字段、类型、是否必填、默认值。执行流程是核心必须拆成模型能理解的具体步骤步骤之间要有明确的输入输出衔接。输出规范则包括格式、篇幅、引用要求防止模型自由发挥。实际写的时候最常见的错误是只给“你要做什么”的清单没有给“什么情况算失败、失败后怎么处理”。我现在每个技能的执行流程里一定包含失败分支比如查数据接口没返回时是直接结束还是换一个口径重试。没有这个分支模型遇到异常就容易开始编。技能文件本身建议用YAML或JSON承载因为结构化格式可以被编排器解析自动化注册和校验也能进版本库做diff。纯自然语言写的技能看起来友好但没法做自动化检测项目一大人就麻了。2. 技能库的顶层设计粒度、分层与复用边界单点技能好写真正麻烦的是当技能数量多起来之后整个“技能库”怎么组织。如果只是把几十个技能文件丢到一个文件夹里路由和选择很快就会变成灾难。这里我更愿意先讲顶层设计因为它决定了后面所有工作的复杂度边界。2.1 原子技能与复合技能怎么切我在多个项目里反复调整后最后稳定在两级拆法原子技能 工作流技能。原子技能只做一件不可再分的事比如“提取订单号”“查询订单状态”“格式化金额”工作流技能负责把多个原子技能串起来比如“订单售后处理”先提取单号、查状态、判断是否在售后期、再生成回复话术。拆得好不好一个很实用的判断标准是能不能用一句话说清这个技能的目标。一句话说不清说明粒度太大如果拆完发现好多技能之间频繁互相调用、边界重叠说明原子层拆过头了需要合并。我还会拿真实历史对话做场景化检验找十个典型输入去跑技能匹配如果同一个输入经常同时命中多个技能而且模型需要用户二次选择就说明技能揉得不够如果某个技能内部步骤超过五个就往下拆一层。净凭感觉设计粒度上线后一定会被真实的用户表达打脸。2.2 技能库的分层管理公共层、业务层、个人层技能库不能做成一个大平层至少分三层公共技能、业务技能、个性化技能。公共技能跟具体业务无关比如“信息检索”“文本润色”“代码格式整理”业务技能绑定到特定场景比如“电商售后处理”“医疗报告解读”里面会带行业术语和业务规则个性化技能则只服务特定用户或角色比如“按小明的习惯把周报改成表格加批注”。分层的主要目的是控制权限和影响范围。公共技能一改所有Agent都会受影响所以必须走严格的回归测试业务技能影响范围收窄到单个子系统个性化技能只对特定会话生效可以快速试错。我踩过一个很典型的坑把业务技能里的专有名词写进了公共层结果另一个无关项目触发了一个预期外的调用排查了很久才发现是技能内容互相污染。用Git管理技能库时我按目录分层每个技能一个文件命名里带版本号。这样用diff就能清楚看到这个技能的判定逻辑在哪个版本变了、为什么变出了问题也能快速回滚。团队协作时公共层由核心维护者合入业务层由各业务owner维护个人层完全自治权责清晰。3. 从零实现一个可落地的技能模块讲完设计进入实操。我会用一个非常常见的“查快递进度”场景做例子带你把一个技能从定义文件写到被Agent调用。这里的关键不是业务本身而是那种“既能被模型看懂、又能被编排程序解析”的写法。3.1 技能清单格式给模型和编排器都看一眼我的技能定义文件用YAML一个技能一个文件结构大概长下面这样。你可以直接抄这个框架后续再根据业务调整字段id: express_query_v1 name: 快递进度查询 description: 查询快递物流轨迹并生成简洁的进度摘要。只处理国内快递单号不处理国际件。适合用户询问包裹到哪了、预计几天到。 trigger: - 包含快递单号且命中物流相关意图 - 用户直接说“查一下物流” exclude: - 用户同时询问多个包裹的运费对比 params: tracking_no: type: string required: true description: 快递单号 carrier: type: string required: false description: 快递公司简称可为空空则自动识别 steps: - name: 校验参数 action: validate rule: 单号长度在8-32位且由字母和数字组成 - name: 识别承运商 action: tool_call tool: carrier_detect input: {tracking_no} - name: 查询轨迹 action: tool_call tool: express_query input: {tracking_no}, {carrier} - name: 生成摘要 action: llm_response prompt: | 基于轨迹数据用不超过3句话说明当前状态、最新动态和预计到达时间。 如果数据异常明确提示暂无法确认不要编造。 output: format: text max_length: 120 require_source: false fallback: - condition: 查询失败且原因不是参数错误 action: 换一种承运商口径重试一次 - condition: 重试仍失败 action: 告知用户稍后再试并让用户核对单号这里有两个读者模型会按steps里的步骤执行编排器会读取trigger、params、fallback做技能路由和参数填充。值得强调的一点是description里不要堆太多内容。过长的描述反而会稀释模型的注意力它只需要知道“解决什么问题、边界在哪、遇到什么情况别碰”就够了。3.2 执行逻辑从触发条件到反馈闭环技能被触发后的第一件事不是执行步骤而是做参数对齐。用户说“帮我看看快递”但没给单号这时不应该让技能内部暴露出“缺参”的错误而是把会话状态切到技能的“待填参数”阶段继续追问。所有必填参数齐了之后才真正执行steps。步骤之间我用明确的参数名做衔接比如第3步的input写成{tracking_no}, {carrier}这样无论是人看还是程序解析都知道上一步产生了什么、下一步消费什么。反馈闭环也容易被忽略。技能执行完除了给用户最终答案还要返回一段执行痕迹记录调了哪些工具、哪些步骤走了fallback、耗时多久。这段痕迹的价值在可观测性和诚实回答。比如当结果来自备用接口时Agent能主动说“这个结果不完全确定因为我用的是兜底渠道”比硬撑着给一个错误答案要靠谱得多。3.3 注册与调度让agent在正确时机拿起正确技能有了技能定义文件接下来要解决的问题是Agent怎么在对话中知道该用哪个技能。做法分两个极端一种是把所有技能定义全部塞进系统提示词让模型自己按文本执行另一种是走专门的技能调度器做向量检索加规则路由再由技能内部的steps驱动模型。前者简单但不可扩展技能一多上下文就爆后者工程重但能承受生产负载。我的生产项目用中间路线轻量调度器先基于embedding相似度加trigger规则做初筛把候选技能压到两三个然后让模型在few-shot示例引导下做最终选择。初筛的核心价值是把决策范围缩小而不是把几十个技能全塞给模型。注册机制上我维护一份技能清单索引包含id、名称、描述、参数模式、版本号。每次服务启动时扫描技能目录自动生成索引并打印注册数量。新增技能时只需放一个文件不用改编排代码这对后续扩展非常重要。4. 踩过的坑技能冲突、幻觉和上下文爆炸这部分是生产环境里最值钱的记录。很多问题在demo阶段根本看不出来只有用户量起来、对话变长之后才暴露。我按实际踩坑频率排一下希望对你有帮助。4.1 两个技能都想接管同一个请求怎么办最早遇到的痛点是技能互相打架。用户说“帮我总结一下这几个文件”结果“文档摘要”技能和“文件内容对比”技能同时命中模型随机挑了一个输出完全不符合预期。解法有两个层次。第一层在技能定义里加“排除条件”明确不适合处理的情况。比如在“文档摘要”技能的exclude里写“不处理两个及以上文件的对比对比请走文件对比技能”。这看起来是语法边缘的补充却对意图识别非常有效因为模型做技能匹配时往往更依赖显式的边界信号。第二层在调度器里做重叠检测。每次新增技能时我会跑一遍已有技能描述和trigger的相似度如果重叠度过高就主动合并技能或调整边界。这样做之后技能之间打架的概率至少降了一个数量级。4.2 中间结果出了问题根因经常在工具层最隐蔽的错误是工具返回的数据本身是脏的但模型不知道直接把原始数据当成正确结果用了。比如快递查询接口返回“异常签收”字段模型可能直接理解为“已签收”但业务规则里“异常签收”意味着用户拒收或地址错误。现在我会在每个工具返回值外面加一层schema校验和规则映射把接口返回的status_code映射成技能内部统一的枚举值比如success、retryable、failed。模型只接收映射后的值不再直接看原始字段。这样技能执行逻辑和上游接口实现天然解耦上游改字段名也不会让技能全线崩溃。排查这类问题必须依赖执行痕迹。我会把每个步骤的工具入参、输出摘要、耗时、状态码写进结构化日志出现问题先在痕迹里定位是第几步挂的再决定是修技能逻辑还是修工具适配层。反复调提示词而不看数据是在错误方向上努力。4.3 上下文窗口不够用把技能当压缩器长任务场景下上下文爆炸几乎躲不掉。让模型边调接口边累积全文它会很快忘记最早的业务前提。我的办法是把技能中间过程设计成“状态摘要”而不是“原始记录”。例如一个多轮数据清洗任务每个步骤结束时不是把完整中间表追加进上下文而是让技能生成一段紧凑的状态摘要包含当前行数、已处理字段、异常计数。下一轮执行只基于摘要继续原始过程放到外部存储。这种方法等于把上下文折叠成状态机。代价是摘要可能丢细节所以我在摘要模板里强制要求“可能影响后续决策的关键字段必须保留”。如果某个技能设计时没有想清楚后续依赖什么那么这个技能就是不合格的上线后迟早出问题。4.4 常见问题速查表故障现象可能原因排查步骤该触发技能时没触发描述里缺少正向触发词或意图被exclude误伤检查exclude条件是否过宽用真实用户query跑一遍embedding命中不该触发时误触发描述边界太宽缺少“不能做什么”为技能补充exclude或“不处理”条件技能内部步骤中途跳出steps逻辑太模糊模型不知道该按什么顺序走把模糊表达改成明确规则减少单个技能步骤数量结果不稳定时好时坏tool入参或返回没有统一schema加参数校验和状态码映射模型只消费固定枚举值上下文在长任务中溢出中间过程原始数据全部停留上下文中改为步骤级状态摘要原始数据外部存储两个技能同时命中技能边界重叠加exclude调度器做重叠检测必要时合并技能5. 技能库的维护、评估与进化技能库一旦跑起来就需要当产品来维护而不是写完就完。这一节讲我怎么评估、发版和排优先级都是比较朴素但可靠的做法。5.1 评估一个技能好不好不能只看成功率很多人评估技能只看“任务完成率”但完成率会掩盖很多问题。我现在增加三个指标触发准确率、步骤稳定性、异常接管率。触发准确率看的是该触发时有没有触发、不该触发时有没有误触发步骤稳定性是同输入跑十次脚本路径是否一致异常接管率是真正需要fallback时兜底逻辑有没有生效。每两周我会挑一批真实会话日志把一个技能的所有命中记录拿出来人工标注算这四个指标。这个工作确实耗时但比离线评测集更贴近生产环境因为真实用户说法跟测试集经常完全不同。触发准确率低于80%我会先怀疑描述里有没有误导内容触发正常但步骤不稳定重点查步骤顺序是否写得太模糊。像“适当处理”“根据情况判断”这类词能不用就不用。5.2 技能版本更新的正确姿势技能受提示词、参数、工具逻辑共同影响我已经把它纳入版本管理同时遵守几条硬约定不修改已发布技能的id要改就新增v2描述或trigger变化时同步升级版本号发版前跑一次快速回归至少五条代表性输入。背后原因是Agent Skills和普通代码不一样它的“逻辑”一部分是模型行为会跟旧会话交互形成惯性。直接原地改线上技能旧缓存和新行为混在一起非常难查。新增版本号虽然会让技能库多出一些重复文件但换来了可回滚、可对比、可观测。我还会在技能文件里写一行changelog注释例如“v2: 增加承运商自动识别规则修复首条轨迹显示异常”。半年后再回来至少不用考古。5.3 我自己的落地顺序建议如果你是从零开始建技能库我的建议是“先窄后宽”。先挑一个高频、边界清晰的任务做成第一个技能跑两到四周把格式、调度、监控整条链路跑通再逐步扩展相邻业务。不要一开始就搭大而全的技能市场。技能库里每多一个技能路由决策负担就多一分。我看到过一些项目热情地建了七八十个技能结果模型选技能的时间比执行技能还长。先有稳定的深度再考虑宽度是最务实的路径。最后想说技能设计不能只交给开发。一定让业务人员参与定义“什么叫执行成功”。我现在的项目里每个技能立项都有一页“验收定义”里面包含三个真实用户案例、一个负面案例、一个边界案例。这一页纸是后面所有技能配置的地基花的时间完全值得。