过去三个月我一直在跟agent-skills这四个字较劲。起因是自己维护的Agent项目越来越难维护Prompt里堆了十几个技能说明模型的调用准确率不升反降每次改一个技能都像拆地雷。后来我把所有零散能力抽成了一套独立的技能层走了不少弯路也踩了不少坑。这篇文章不铺垫概念直接把这套体系的拆分思路、落地细节和翻车经历完整过一遍。如果你正在做Agent相关应用或者正准备把一堆提示词和工具调用整理成可维护的结构这篇应该能给到不少参考。1. 先想清楚agent-skills 到底在治什么病1.1 从 Prompt 越堆越臃肿开始说起最早期我的Agent其实没有技能层的概念所有能力都写在System Prompt里你可以整理会议纪要你可以生成周报你可以调用日历API……当只有三五个能力时这个方案还能转但随着业务加码Prompt很快膨胀到接近两万字。这时候你会发现几个非常典型的症状模型开始出现指令失忆——你让它同时记住十几个技能的使用条件和输出规则它总是记了后面忘前面上下文窗口被大量静态描述占用真正跟用户对话相关的上下文反而被挤掉了每次修改一个技能描述都可能影响其他技能被识别的概率回归问题防不胜防。后来我在一个模型可观测性工具里看到了一组数据当System Prompt里技能说明超过十个之后技能召回率从92%掉到了76%误触发率还翻倍。那段时间团队正好在做基准测试我用同样的测试集反复跑了好几轮三个模型无一例外技能相关的指令一多整体表现就是往下掉。这个数据说服了我必须把能力说明从主对话上下文里剥离出去。这就是我最初想做agent-skills的动因。不是跟风是被问题逼出来的。1.2 Skill、Tool、Plugin、Workflow 的真实边界先给结论我不觉得Skill和Tool是按代码量划分的核心区别在于决策点的多少。一个Tool可以是一个简单的函数输入输出固定没有任何内部逻辑分支比如查询天气获取当前时间。而一个Skill通常包含多个步骤、多个工具调用路径甚至内置判断逻辑比如整理会议纪要可能要经过转写、摘要、待办提取、按模板排版四步中间还要判断会议里有没有出现待办事项。再比如规划出差行程这个Skill内部会去查天气、查交通、安排会议时间、生成行程单任何一个环节出了问题都要有对应的兜底逻辑这明显不是单个Tool能覆盖的。Workflow是确定性的流程编排定义好节点之后每次跑都一样Skill则可能内部有一个松散的流程但允许模型根据输入做一定程度的自主决策它向下可以复用多个Tool或子流程。Plugin更像是一种安装和分发形态Skill可以被打包进Plugin里。如果在做项目时遇到不知道用哪种形式的情况我的建议是把单个确定性动作定义成Tool把需要决策和编排的动作定义成Skill把固定顺序、不允许模型自由发挥的流程定义成Workflow。这套边界在实际协作里特别重要。边界不清晰会导致团队内部口径混乱——有人把生成周报写成Tool有人写成了Workflow等到系统里同类能力大量出现时维护成本会指数级上升。项目初期就把这些名词定义清楚后面能省下大量沟通成本。1.3 一套技能体系的核心组成定完边界再说agent-skills体系的组成。我理解中一个完整的Skill包含四部分技能声明、操作说明、执行资产、执行器。技能声明Manifest给模型看的入口包含技能名称、用途、触发条件、输入输出Schema。它决定模型什么时候调用这个技能是技能层的脸面。操作说明Instructions技能被触发后注入给模型的详细指令可以理解为一本使用手册只有在被调用时才加载。执行资产Assets技能依赖的脚本、模板、知识库切片、外部API配置等。执行器Runtime负责加载、校验、运行Skill的宿主代码通常对接Agent框架。这四部分相互独立又缺一不可。声明决定了触发面说明书决定了执行质量资产是能力基础执行器解决的是怎么被安全地跑起来。日常开发中我们团队对一份技能改动最多的往往是声明和说明书执行器和资产相对稳定因为前者是对外接口一点语义变化都会影响调用后者一旦稳定下来就尽量不做大改。下一章重点讲我具体怎么设计这四部分。2. Skill 的设计框架我在项目里沉淀的拆分方法2.1 触发面什么时候该被调用Skill声明里的description是整个技能系统里最重要的文本。很多项目的技能召回率低问题不在模型而在描述写得不讲人话。我见过大量类似帮助用户进行会议纪要整理这种描述——它太抽象了模型很难判断什么场景算帮助什么情况不用。后来我沉淀了一套三段式写法触发条件典型输入必做动作。举个例子这是我从项目里截取的一个技能声明描述触发条件当用户提供会议录音转写文本、会议笔记或者明确要求把这次讨论整理成纪要时触发 典型输入会议原始转写/笔记、参会人列表、可能的议题背景 必做动作提取关键决议、拆解待办事项、标注负责人和截止时间、按既定模板输出会议纪要描述里尤其要写清楚哪些情况不要触发。我会在每条description后面加一段不适用场景例如仅闲聊时不需要触发如果用户只是问如何做纪要请不要调用执行而是直接回答方法。加了负例之后误触发率往往立竿见影地下降。之前我把写周报技能的负例写成如果用户只是抱怨工作太累不要自动生成周报加上这句话之前这个技能经常在负面情绪场景中被误触发三个月里误触发日志占了一整页。还有一个小技巧把description写成一个可检索的短文本索引而不是完整说明书。这样动态加载时Router可以先通过向量检索或关键词匹配候选技能只有选中的技能才把完整说明书送入上下文。这个优化能把触发判断的token开销降一个数量级尤其适合技能数量多的中大型项目。2.2 执行面代码优先还是提示词优先每个Skill内部可以选择纯提示词执行、纯代码执行、或代码提示词混排。我建议按任务性质来选而不是按团队技术栈来选。执行类型适用场景优点缺点纯提示词型内容理解、文本重写、结构化摘要、创意生成实现快、迭代快、适合读懂语义的任务输出不稳定对格式和精度要求高的场景容易翻车纯代码型调用API、文件解析、数据清洗、规则计算完全可控、可测试、结果稳定需要写大量代码改动成本高混合型大多数真实业务技能先用代码处理结构化部分再用模型处理语义部分链路更长需要定义清晰的代码处理完交给模型什么数据我自己的默认策略是能用代码解决的永远不要丢给模型。比如解析日期、合并列表、转换格式这些交给模型不仅贵而且不可靠。模型只负责理解和生成的部分。有一次我优化一个报表生成技能把日期标准化从提示词挪到了Python里成功率从82%提到了98%单次执行成本降了差不多一半。这就是代码优先的直观收益。但纯提示词型也并非一无是处。在快速验证阶段先用提示词把流程跑通确认业务逻辑没有硬伤后再逐步替换成代码是一种很高效的演进路径。别一上来就追求完美工程化先让业务跑起来再谈稳定性。2.3 契约面输入输出 Schema 的严谨程度决定稳定性Skill本质上是模型与世界交互的中间层。中间层最怕的就是接口不清晰。模型传参经常丢字段、给错类型如果你不做校验后面的代码就要处理各种脏数据如果你校验太死模型一旦传错就直接报错用户体感很差。我的策略是八个字宽松入参严格出参。所谓宽松入参是指当模型传入的参数不完整时不立刻失败而是允许Skill内部主动补全。比如生成周报时模型可能只传了这周做了API重构Skill可以通过上下文查询或模板默认值补全其他字段。严格出参则是指Skill返回给上层的数据必须符合Schema字段缺失要显式补空类型要严格转换不能让上层消费方去猜。下面是一个技能参数声明的JSON Schema示例{ name: weekly_report, description: 生成结构化周报供后续渠道分发, parameters: { type: object, properties: { accomplishments: { type: array, items: {type: string}, description: 本周完成的事项列表 }, blockers: { type: array, items: {type: string}, description: 遇到的问题没有则传空数组 }, plan: { type: array, items: {type: string}, description: 下周计划 } }, required: [accomplishments, blockers, plan] } }注意required字段。我见过不少项目把required设置为全部必填结果模型经常因为缺字段而报错也有项目完全不加required导致输出经常缺核心字段。正确姿势是只把没有就无法继续的字段设置为必填其他字段用默认值兜底。在实现时我会为每个Skill写一个独立的校验函数入参阶段做软化处理出参阶段则严格按照Schema序列化任何类型不一致都在这一步修正。2.4 记忆面Skill 的上下文隔离策略上下文隔离是agent-skills里最容易被忽略的一环。很多Agent框架默认会把每个步骤的中间结果都保留在全局上下文里导致执行一个技能后上下文里堆满了一大段临时内容。这些问题一开始不明显技能数量上来之后就会变成性能杀手。我的做法是三层隔离。第一层Skill内部产生的中间处理结果默认不写回全局上下文只有最终输出通过Schema校验后才返回给主Agent。第二层如果确实需要在多个Skill之间共享状态我会定义一个State通道显式声明哪些数据可共享不使用隐式传递。第三层每个Skill执行时都有独立的临时工作目录目录名带Skill ID避免文件覆盖。这套隔离策略直接改变了系统的可维护性。以前改一个技能可能意外影响另一个技能现在技能之间除非显式对接否则完全独立可以放心并行开发和测试。团队成员后来也习惯了每个技能自带状态、但状态默认私有的写法跨技能传参必须走接口而非改全局变量代码整洁度提升了一个档次。3. 从能用到好用演进过程中踩过的四个坑3.1 坑一Skill 描述里的隐含前提在换模型后全部失效第一次规模性翻车发生在我把主模型从Claude切到GPT-4o的时候。切完之后过去跑得好好的技能调用突然变得各种不听话该触发的技能不触发不该触发的反而触发。我最开始怀疑是温度参数问题调了半天没用。后来逐条用固定的测试集跑两个模型的对比才发现真正的问题在描述本身。我的Skill描述里充满了默认模型应该懂但模型未必懂的内容。比如我当时写当用户提到整理一下时可以默认调用会议纪要技能Claude能理解这是整理的宽泛语境但GPT-4o更倾向于字面匹配整理这个词。也就是说我把自己团队的常识当成了模型的常识。这类问题在单一模型上很难暴露因为长期调试下来描述已经被优化得和那个模型的脾气很匹配可一旦换模型所有隐性默契全部失效。修复方案很直接把所有隐含前提显式化。每个技能描述里增加触发边界字段明确写出该触发与不该触发的正反例。一共改了四十多处描述改完之后两个模型的触发准确率都稳定在了95%以上。这里也反映出一个原则技能描述不应该为任何一个具体模型定制应该尽量写成人类也能看明白的说明书——越客观、越具体跨模型的鲁棒性越强。3.2 坑二多个 Skill 同时响应导致的任务竞争第二个坑出现在技能数量超过十五个之后。用户说了一句把这次会议纪要按照模板发给项目经理结果系统同时命中了会议纪要整理和消息发送两个技能。两个技能各自执行完毕主流程却不知道该用哪个结果进程直接卡死。日志里看到的是两条技能链路同时在自己跑互不相让。排查时我还以为是Router有问题后来把触发日志拉出来发现两个技能的description都写了当用户需要生成并发送XXX时触发语义范围叠得很厉害。根因是每个技能只站在自己的角度描述适用范围没有顾及全局的职责划分。单独看哪个描述都没错放在一起就冲突了。解法分两步。第一步在Router层加消歧逻辑如果命中多个候选技能先做一次LLM判断输出应该由哪个技能主导、其他技能是否作为子步骤参与。第二步是给每个技能的描述增加协作边界主动声明如果任务同时涉及生成和发送本技能只负责生成发送交给messaging技能。这样等于把跨技能的冲突前置到了描述层从源头上减少竞争。实施之后类似的多技能冲突从每周七八次降到了几乎为零。3.3 坑三全局注入导致上下文被无关技能吃掉第三个坑是我自己设计失误不是模型的锅。当时为了让模型随时准备好调用任何技能我把所有Skill的完整说明书都注入到了系统提示里。二十个技能每个上千字加起来接近两万字。表面上看是模型什么都会实际上上下文预算被静态文本占掉了一大半用户对话稍长一点模型就开始忘事响应质量肉眼可见地下降。我用日志统计了一下token分布系统提示占每次请求token量的42%其中真正被激活的技能相关token不到10%。也就是说绝大多数技能说明只是躺在上下文中当摆设还白花钱。这个数据出来之后团队内部立刻达成共识不能再全量常驻了。修复思路就是动态加载。我在执行器里加了一层技能索引系统提示里只放每个技能的一句话摘要当模型决定调用某个技能时再把完整说明书放进上下文。这样上下文占用砍掉了将近七成单次请求的成本也降了。动态加载是个老思路但在Agent技能体系里它不是优化项而是必须项。不过动态加载也不是没有代价它要求Router本身足够准如果索引摘要写得不清楚模型可能在第一步就选错技能反而比全量注入更糟。所以我会在技能索引摘要上花与完整描述同样多的精力。3.4 坑四动态注册技能时的命名与路径冲突最后一个坑跟技能注册机制有关。为了支持团队多人并行开发技能包我设计了一个动态注册目录所有技能包按约定的目录结构上传后会自动加载。上线后没过多久就出了事故两个技能包都带了一个名为utils.py的工具文件后注册的包把先注册的覆盖了导致前一个技能运行时各种奇怪报错。排查过程其实不难难在定位心态。第一反应以为是文件系统权限问题查了很久没有头绪后来打开加载器的日志发现注册顺序与文件哈希变更完全对应才意识到是覆盖问题。根因是加载器做合并时没有做命名空间隔离两个目录里的同名文件被当成同一个模块处理了。修复方案有三点。一是每个技能一个独立命名空间相关工具函数和临时文件都放进以技能ID命名的目录不允许跨目录引用。二是所有注册到全局的工具函数名统一加技能前缀比如meeting_summary__generate_digest。三是注册阶段做冲突检测发现同名工具或同名关键文件立即报错而不是默默覆盖。经过这次教训我把宁可启动失败也不悄悄出错定为技能注册的原则这类隐性覆盖风险在协作开发中比想象中常见得多。4. 质量闭环我用什么方式持续衡量和打磨这套体系4.1 评估集的设计既要覆盖也要防过拟合技能系统做到后面最大的挑战不是实现而是回归。每次改一个描述或调整一个执行器都可能影响几十个技能的表现。我后来建了一套比较轻量的回归评估集核心思路是给每个技能准备正例和反例各十条左右用它们组合成一批测试会话每次改动后跑一遍对比各项指标变化。正例是这个技能应该被准确触发并成功执行的场景反例是看起来有点像但不该触发的场景。比如会议纪要技能的反例可以是用户说帮我把会议推迟到明天——会议相关但没有纪要整理需求所以不该触发。反例的价值比正例更大因为大部分系统的问题不在召回不足而在误触发太多。我见过很多团队把评估集做得特别复杂但反例占比极低结果线上误触发率始终压不下来。还要防过拟合。模型很聪明如果你的评估集长期固定不变它的表现会慢慢记住这些用例导致测试分数虚高。我每两周会从真实对话日志里捞10到20条新的用户消息作为盲测用例不提前告诉模型跑完再看命中情况。这种盲测数据比精心构造的测试集更能反映线上真实水平。目前这套评估通过定时任务每天凌晨自动跑早上起来看报告就行。4.2 三个运行指标调用准确率、执行成功率、上下文损耗率我用来衡量技能体系健康度的指标不多就三个监控面板上也只放这三条曲线。指标定义健康标准典型问题信号调用准确率该调用的技能是否被调用、不该调用的有没有误触发90%以上误触发增多时优先查描述边界执行成功率技能被调用后是否产出符合Schema的合法结果95%以上执行成功率低时优先查执行体和资产质量上下文损耗率单次技能调用中总token消耗与实际被模型有效使用部分的差距控制在合理预算内损耗率升高说明技能加载过于臃肿关于上下文损耗率我需要解释一下。这不是一个标准名词是我在项目里自己定的一个观测口径把每次技能调用涉及的系统提示、技能说明书、知识库内容、历史对话等都算进消耗再看最终输出对这个上下文的使用程度。比如一个技能加载了很长的知识库文档但模型只用了其中一段损耗率就偏高。关注这个指标能反过来帮助收敛技能设计——说明书能短则短知识库能精简就精简。这三个指标要放在一起看。单独看调用准确率没有意义因为一个系统如果什么都不调用触发准确率可能也高执行成功率高但调用准确率低说明技能没有在正确的场景使用上下文损耗率虽然重要但也不能为了降损耗牺牲执行质量。三者的平衡点需要根据具体业务反复调没有一套万能参数。4.3 迭代节奏我如何决定一个 Skill 是重构还是删除技能体系和代码一样需要持续维护不是上线就完了。我给自己定了一套比较简单的决策规则用数据而不是感觉来判断。第一看调用频次。过去三个月调用次数少于五次的技能基本上是一个伪需求技能我会先并入更高频技能如果三个月后还是没有调用直接删除。第二看成功率趋势。如果某个技能调用次数很多但执行成功率长期低于85%优先重构执行体尤其是把里面提示词负责的部分逐步替换成代码。第三看误触发情况。如果某个技能经常被错误触发问题一般不在执行体而在触发描述优先改description而不是改代码。第四看技能间关联度。如果两个技能在日志里频繁同时触发我倾向于合并成一个技能或者显式定义它们的协作关系而不是放任它们各自为战。每个技能上线时我都会在它的Manifest里写清楚版本号和负责人。后续任何改动都走新增版本号而不是原地覆盖这样即使某个版本在线上出问题也能快速回滚到上一个稳定版本。技能系统的演进不可能一次成型它更像是搭积木——先把积木的种类和接口定清楚再一块块替换、删除、重组。到后期你会发现真正让你Agent能力上限变高的不一定是某个单点技能的惊艳表现而是这套技能集合能否稳定地、低成本地协作。最后再补充一个我做技能设计时的习惯每次新建一个技能我都会先写一份一页纸说明给一个完全不了解这个项目的人看如果对方看完能复述出什么情况该用、什么情况不该用、输出大概长什么样我才把它转写成技能描述。这个习惯帮我挡掉了不少设计漏洞。希望这套从设计到迭代的经验能让你在做类似方向时少踩几个坑。