上个月我把团队里的客服Agent彻底重构了一版核心改动只有一件事给Agent装了一套 agent-skills。结果很直接以前每次对话都要从零推理该怎么干活现在90%的常规任务走固定技能流程输出质量稳定得让人意外。身边不少朋友也在聊这个概念但很多人把 Skills 理解成简单的提示词模板这就把它的价值看小了。这事真正解决的是Agent落地时最头疼的不可控问题。大模型本身的推理能力再强没有一套结构化的执行框架它就是有肌肉没记忆每次发挥全看心情。agent-skills 本质上是把模型需要知道的做事方法拆成可复用、可组合、可维护的独立单元让Agent在正确场景下自动调用正确流程而不是临时拼凑一段prompt硬上。这篇文章我不谈空概念直接把我设计、开发、踩坑、修坑的全过程写出来适合正在做Agent应用、提示词工程、自动化工作流的开发者参考。1. 为什么Agent必须有一套技能库先说个真实场景。之前我让Agent帮我汇总团队周报指令写得很清楚提取每个人的工作内容、进展、风险。跑出来的结果却五花八门有时候按人列有时候按项目列有时候直接丢了风险信息。问题不在模型在于我让一个没有任何做事经验的Agent直接面对开放任务。这就好比让一个实习生去组织几十份周报但不告诉他公司汇报的格式规范他每次交付的东西当然都不一样。1.1 没有技能的Agent有肌肉没记忆我们习惯把Agent的能力等同于大模型的推理能力这是错觉。模型参数里装着海量知识但知识不等于操作流程。一个Agent处理任务需要的是在什么条件下、按什么顺序、调用什么资源、输出什么格式的完整约束。没有这些约束模型就只能依赖通用常识去自由发挥。自由发挥在简单任务上没问题一旦任务链条拉长、数据变多、格式要求明确翻车概率指数级上升。我见过最典型的翻车Agent在处理一份包含敏感字段的表格时顺手把整表内容都写进了摘要没人告诉它哪些字段需要脱敏。这类问题不是换个更强模型就能解决的而是需要在技能层面把脱敏固化成执行步骤里的一个校验点。所以agent-skills的第一性原理是把不稳定的人类口头指令转化成稳定的、结构化的执行协议。你不需要在每次对话里重新教Agent怎么做事它自己会找到对应的技能包按里面的SOP走完整个流程。1.2 Skills不是Tools技能是怎么做工具是用什么这是很多人混淆最深的一点。Tools工具指的是Agent可以调用的外部函数比如搜索引擎API、数据库查询接口、文件读写器。Skills技能则是一层更高维度的封装它告诉Agent你要完成这个任务应该分几步每一步用哪个工具中间要做什么判断最后输出什么格式。打个比方。Tools是厨房里的锅碗瓢盆Skills是菜谱。只有锅碗瓢盆厨师模型得自己琢磨每道菜怎么做有了菜谱他按步骤执行就能稳定复现。真正的Agent系统其实两者都需要没有工具的技能是空谈没有技能的工具则是一堆积灰的零件。在设计agent-skills时我通常把工具调用清单直接写进技能文件里这样Agent读到技能就知道该用哪些工具、按什么顺序调用不用在每一步都做全局推理。1.3 一套技能体系解决三个核心问题实际落地下来技能体系至少在三个层面上起作用。第一一致性问题。同样的输入昨天和今天的结果应该基本一致。技能把执行路径固化后模型即使换了版本、换了温度参数核心输出框架也不会跑偏。第二维护成本问题。以前优化一条提示词要在长上下文里改来改去牵一发而动全身。技能化之后每个技能文件独立存在改一个技能的步骤描述其他技能完全不受影响测试范围小迭代速度快。第三能力复用问题。团队里A项目写好的表格数据清洗技能B项目直接就能用最多改一两处参数。我自己维护的agent-skills仓库里目前有20多个技能很多技能在不同项目间反复调用边际成本越来越低。2. 技能库的结构设计与核心机制很多人在GitHub上见过别人开源的各种Skills示例看起来就是一个文件夹加几个Markdown文件。但如果你只学会了表面形式没搞懂内部结构设计的逻辑写出来的技能大概率不好用。我折腾了将近一个月才总结出一套比较稳定的结构规范。下面把核心要点全部拆开讲。2.1 技能六要素名字、描述、触发条件、步骤、校验点、依赖一个合格的技能文件必然包含六个要素缺一不可。名字Name短、准、唯一。比如summarize_weekly_report一眼知道是干嘛的。描述Description这是给模型看的说明书越具体越好。包括任务目标、输入形式、输出形式、边界条件。描述直接决定了Agent能不能在合适的时候想起并调用这个技能属于召回环节写不好技能就是摆设。触发条件Trigger Conditions明确什么情况下调用。可以写当用户要求汇总多人的工作周报时也可以写当检测到输入文本中包含日期范围和多条人员记录时。执行步骤Steps这是技能的核心。把任务拆成不超过5-7步的清晰序列。我踩过的坑是步骤写得太多太细模型反而被束缚住遇到意外情况不知道怎么变通步骤太少又控制不住行为。最佳实践是大步骤固定小操作允许模型自主发挥。校验点Checkpoints在关键步骤后加质量标准比如输出必须包含风险字段、脱敏后才能写入文件。校验点是兜底机制能有效防止模型偷懒或跑偏。依赖Dependencies声明这个技能需要的工具、外部服务、数据源。比如需要调用database_query工具、需要读取./data/report_2025.xlsx文件。让Agent在执行前一次性准备好所有资源避免半路卡壳。2.2 命名与描述让召回率翻倍的优化技巧在多技能并存的Agent系统里技能召回靠的是模型对技能描述与用户当前意图的语义匹配。这意味着描述写得像说明书不一定有效必须站在模型视角写。我的经验有两条。第一描述里要多写触发场景的同义表达。比如summarize_weekly_report这个技能描述里我可以写适用于周报汇总、团队进展整理、工作内容合并等。因为用户表达意图的方式千变万化可能是帮我看看这周大家干啥了也可能是把各小组的周报合并成一份管理摘要。同义表达越丰富召回率越高。第二尽量在描述中说明不适用于什么。这叫负向约束。比如本技能不适用于单个人员的绩效评估能有效避免Agent在用户问某人这周做得怎么样时错误调用。实测下来优化描述前后的召回差异非常明显。没优化前十个测试样本只有六个能正确触发优化后九个以上都能触发效果立竿见影。2.3 一套完整的技能文件模板我的技能文件目前统一用Markdown存储结构固定方便Git管理。下面直接给出一个实际可用的模板骨架拿过去改一改就能用。--- name: summarize_weekly_report description: 汇总多人的工作周报按项目维度提取进展、风险和建议。 适用于周报汇总、团队进展整理、多文档合并摘要等场景。 不适用于单独评估个人绩效不适用于处理非周报类文档。 trigger: - 用户要求汇总周报 - 用户提供多份工作记录要求合并 - 用户需要提取团队进展和风险 steps: 1. 识别输入中的所有独立周报记录标记作者与日期 2. 按项目名归类合并相同项目的记录 3. 提取每个项目的进展、阻塞点、下步计划 4. 生成统一格式的摘要按项目分组 5. 输出前检查是否包含风险字段缺失需标注 checkpoints: - 输出必须包含项目名、进展、风险、下步计划 - 涉敏信息不得出现在摘要中 - 摘要结构必须为Markdown列表 dependencies: - none要不要用YAML front-matter做元数据我强烈建议用。它把描述、触发条件和步骤分离开解析起来方便后续做自动评估、自动索引的时候优势明显。纯Markdown混在一起写模型也许能理解但程序侧处理会很痛苦。2.4 技能存储与加载机制文件系统就是最好的数据库技能的存储思考了很久最后选了最接地气的方案本地文件夹版本控制。以项目根目录下的skills/文件夹作为技能根目录每个技能一个子文件夹里面放SKILL.md定义文件还可以放示例数据、参考文档、脚本模板。加载的时候Agent系统启动时扫描全部技能文件解析元数据进入索引库执行时根据用户输入做语义检索挑出最相关的1-3个技能注入上下文。这种方式比把技能存在数据库里更直观。Git天然支持版本回滚、分支管理和多人协作团队里每个人都可以提PR来完善技能一切变更都有迹可循。我甚至给这个目录单独建了一个仓库两边项目共用解耦得很干净。3. 从零做一个可落地技能周报汇总实战光讲结构还是虚我带你把一个真实技能完整走一遍流程。这个案例我用了很多次足够典型既能体现多文档处理又包含格式约束和数据提取做一遍基本能掌握agent-skills的核心方法论。3.1 第一步需求拆解与执行流程设计接到任务千万别急着写技能文件。先想清楚这个任务真正的难点在哪周报汇总这件事难点有三。一是多源输入格式不统一有人用表格有人用段落二是要按项目维度聚合而不是按人聚合三是输出必须面向管理层需要突出风险和阻塞。理清难点之后设计执行流程。我把流程定为分-合-提-校四步先把所有周报记录拆分成独立条目再按项目字段聚合然后提取每个项目的关键信息最后统一格式校验输出。在技能文件的步骤列表里我就把这四个阶段写进去模型执行时基本不会跑偏。3.2 第二步编写技能文件的具体描述描述的质量决定技能被调用的概率这里我写得很细。为了让模型理解项目维度和人员维度的区别我在描述里加了一句同一作者的不同项目任务应拆分到对应项目中而不是归并在作者名下。如果没有这句模型经常按人来分组输出完全不符合预期。触发条件我写了几类常见说法汇总本周工作、合并各团队周报、提取所有项目的进展。负向约束也写上了不适用于生成个人绩效报告、不适用于跨周时间段的分析。写完之后我自己测试了三五种问法确认能稳定触发才往下走。3.3 第三步参数设计与Token消耗估算有一个实操问题很容易被忽略技能文件本身要占上下文空间。如果你的任务每次要处理几十份文档上下文本来就很紧张技能定义再占一两千token压力会更大。所以我习惯在设计阶段就估算token预算。以这个周报汇总技能为例技能文件本身大概600-800 token待处理的周报假设有30份每份平均200 token共6000 token系统指令和工具定义约500 token输出预算1500 token。合计不到9000 token用主流大模型的上下文窗口完全没压力。如果输入文档量翻倍就不适合一股脑全塞进上下文了需要让技能先调用分段读取工具分批处理。这个判断逻辑可以写进技能步骤里若输入文档超过20份先按作者分桶处理再合并结果。这种动态调整的写法远比死板的固定流程更抗压。3.4 第四步效果评测与回归验证技能写出来不是结束要跑验证。我的做法是准备一个固定的测试集五份模拟周报包含不同格式、不同写作风格其中一份特意加了脱敏隐患字段。每次修改技能文件都用同一测试集跑一遍对比输出质量。我第一次测试时输出把所有人员信息都列了出来完全没脱敏。后来在技能步骤里增加了涉敏信息检查的校验点再跑就正常了。这个经验很关键技能的每一个步骤改动都必须用同一测试集回归否则你根本不知道改坏没改坏。4. 技能库落地常见问题与排查实录真实使用agent-skills的过程中我遇到了不少坑。每个坑都有背后的原因花点篇幅讲清楚能帮你少走至少一个月弯路。4.1 技能召回失败Agent压根找不到对应技能这是最常见的问题。表现是用户问了个任务Agent不去调用你写好的技能而是自己临场发挥。原因大多出在描述和触发条件上。排查思路分两步。首先检查描述里的触发语义够不够丰富用户最常见的问法是不是都覆盖了其次检查系统里的技能是不是太多索引检索时被其他技能干扰了。如果技能超过30个建议加一层类别标签机制在元数据里标记技能属于数据处理还是文本生成还是外部交互触发时先粗筛再精排召回率会稳很多。4.2 技能步骤过于刚性遇到边界情况直接卡死我在一个表格清洗技能里写了严格步骤删除包含空值的行。结果模型拿到一份关键列缺失但其他列有价值的数据直接整行删掉数据损失严重。这是步骤写太死的典型后果。修正方法是把步骤改成条件分支若某行核心字段为空则删除否则保留并标记。模型需要一点判断空间技能的价值恰恰在于提供框架和兜底而不是把每个像素都画死。4.3 Token消耗失控长上下文塞爆窗口技能文件写得越详细实力消耗越大。我曾放过一个技能说明文档进去里面带了三页示例和历史版本说明直接吃掉2000多token。对这个情况做了一轮瘦身示例只保留最短版本长内容挪到外部参考文件夹技能正文只留核心定义和步骤。遵循的规则简单技能正文不超过800 token更多说明放reference/目录在依赖项里注明需要时读取该文件。这样平时执行不浪费资源真到必要时还能加载深度内容两全其美。4.4 多技能间的权限边界与副作用问题某个数据分析技能执行时Agent顺手把源数据文件覆盖了。原因是我没在技能里声明写权限边界。后来我在每个技能里都加了side_effects字段明确该技能是否会产生副作用比如本技能会生成新文件不会修改源文件。执行引擎遇到有副作用的技能会加一道用户确认安全性立刻提升。这不是小事。Agent一旦具备了调用外部工具的能力技能就必须声明自己的影响范围。做不到这一层事故早晚发生。4.5 避坑清单速查问题根因解决法技能不被调用描述语义覆盖不足补充触发场景同义表达与负向约束输出格式乱校验点缺失步骤后增加明确格式校验执行过程跳步步骤粒度太粗拆细到3-5个可操作步骤Token超窗技能正文冗余长文本移入参考文件正文瘦身数据被误改副作用未声明增加side_effects字段并做确认技能间混淆索引冲突引入类别标签先粗筛再精排5. 从单技能到技能编排Agent的进阶用法当你手上的技能数量多起来之后真正的威力开始显现。单个技能解决单一任务多个技能组合起来就能处理复杂得多的工作流。这层进阶玩法很值得深入。5.1 技能链前一个技能的输出是后一个技能的输入以周报为例我做了两个技能summarize_weekly_report负责生成原始摘要format_board_report负责把摘要转成管理层汇报格式。实际运行时Agent会先调用第一个技能生成摘要再把摘要作为输入调用第二个技能完成格式化。技能链的设计要点是接口对齐。我在设计技能时都会在步骤末尾明确输出结构这样下游技能读到的数据是可预期的。如果你不做接口约定技能链里的数据传递就会充满不确定性程序完全没法稳定运行。5.2 动态路由让Agent自己决定组合路径更高级的玩法是让Agent根据任务特点动态选择技能组合。比如用户说把今天所有销售数据整理成简报并发邮件Agent会检索到三个技能数据清洗、简报生成、邮件发送然后自己拼出一条执行链。动态路由的前提是技能描述互相之间有足够的区分度。如果技能A和技能B描述高度重叠模型就会随机选一个链路稳定性立刻崩坏。所以每次新增技能我都会专门检查这个技能与现有技能的区别在哪里并把区别写进描述里。这是技能库管理中最容易被忽视却极其重要的一环。5.3 技能评估与质量回归技能不是写一次就万事大吉。模型版本更新、业务需求变化、用户提问方式演变都会让旧技能逐渐失效。我现在每月做一次技能质量评估拿当月的真实任务样本跑一遍全部技能看调用成功率、输出达标率、人工修正率三个指标。调用成功率低于80%的技能我会优化描述输出达标率低于70%的我会调整步骤人工修正率高的说明步骤和校验点设计有问题需要拆开重审。这套评估机制配合Git版本管理我是用脚踏实地的笨办法保证技能库的健康度。没有任何捷径靠的是持续的观察和迭代。我自己用了几个月agent-skills感受最深的一点是它并没有让Agent变得更聪明但让Agent变得更靠谱。聪明是模型的事靠谱是工程的事。每一次能力的沉淀、每一次经验的固化都被放进了那一个个小小的技能文件里。团队协作时我们不再在聊天记录里翻找上次那条好用的指令到底是什么一切都有据可查、有版本可依。如果你也在做Agent的落地应用我建议从一个小场景开始挑一个你每周都要重复做的任务把它写成一个技能文件然后跑一个月看看稳定性提升有多明显。那种感受会说服你继续走下去的。