“agent-skills”这个词最近在 AI 工程圈里出现的频率高得有点离谱。我最早认真对待它是在给自己搭的一套自动化流程反复“翻车”之后——同一个文件整理任务换个对话窗口智能体就像失忆一样从头问一遍脚本写过的逻辑、踩过的格式坑全都要重新交代。那一刻我意识到问题不在于模型不够聪明而在于我们一直把“怎么做一件事”的完整知识零散地塞在临时的提示词里。agent-skills 想解决的正是这件事把可复用的能力从对话里抽出来沉淀成一个有结构、有触发条件、能被按需加载的独立单元。这篇文章适合三类人看——正在给智能体接工具但总被上下文撑爆的开发者、想把团队里的重复流程固化下来的业务同学以及刚接触 agent 概念、想知道“技能”和“工具”到底差在哪的新手。我会从它是什么、目录怎么长、第一个技能怎么写、怎么被触发一路讲到排错实录全部是我自己动手验证过或反复踩坑后总结的东西。1. Agent Skills 到底是什么从“能对话”到“会干活”的那一步很多人第一次听到 agent-skills会下意识把它和工具调用划等号觉得“不就是换个名字的 function calling 吗”。我一开始也这么想直到被上下文预算狠狠教育了一次才转过弯。工具调用给的是“手”技能给的是“会用手的那套方法”。这两者配合起来智能体才真正从“能聊”走到“能干活”。1.1 一个类比给新同事递的不是工具箱而是一本岗位手册设想你招了个能力很强但完全不了解你们业务的新同事。你当然可以扔给他一箱子工具——螺丝刀、扳手、电钻这就是工具调用的层次。但他依然不知道先拧哪个螺丝、哪种情况该用扭力扳手、遇到滑丝又该怎么补救。agent-skills 相当于给他递一本岗位手册这本手册告诉他什么情况下启动这个流程、第一步做什么、遇到异常怎么处理手册的附录里还夹着配套的脚本和模板。关键在于手册不是一次性全塞给他而是他遇到对应任务时才翻开对应章节。这个类比能解释为什么它比“多写点提示词”强。提示词是无结构的文字塞得越多越容易互相干扰模型注意力也被稀释。而技能是有边界的封装一个技能只管一类任务触发条件写在元数据里具体步骤放在正文重型脚本单独存放需要时才读取。边界清晰带来的直接好处是可维护——某个流程变了你只改那一个技能文件不用去几十个提示词模板里做全局替换。1.2 它和 Function Calling、MCP 的边界到底在哪这三个东西经常被混在一起讲我用一张表把它们的分工理清楚这也是我自己理解时最有用的框架。维度Function CallingMCPAgent Skills核心职责让模型调用一个具体函数统一模型与外部数据/工具的连接协议封装“完成一类任务的完整方法与知识”内容形态函数签名与参数描述服务端暴露的资源与工具接口元数据 指令正文 脚本/资源文件加载方式随请求一次性给出连接后动态发现按需渐进式加载用到才读典型问题参数太多、上下文膨胀连接与鉴权配置触发不准、指令写得含糊谁更“懂业务”不懂只懂接口不懂只懂通道懂因为它写的是流程与经验我的用法是底层连接和数据获取交给 MCP 与工具调用上层“这件事该怎么一步步做、有什么禁忌”的知识交给技能。技能正文里可以指示智能体去调用某个工具、执行某个脚本但它们职责不重叠。把业务逻辑硬塞进函数描述里是我早期最常犯的错结果是函数签名越来越长模型反而更容易选错。1.3 什么场景才值得单独写成一个 Skill不是所有东西都值得封装。我踩过的坑是——兴冲冲把每个小操作都做成技能结果目录里堆了三十多个维护成本比收益还高。后来我给自己定了几条判断标准符合两条以上才动手写高频重复同一类任务一周里出现三次以上且有稳定的处理套路。有隐性经验光靠模型常识做不好需要踩过坑才知道的细节比如某种文件必须先转码再解析。步骤可固化流程相对稳定不会每次都要临场重新决策。依赖重资产需要挂载脚本、模板、参考文档光靠一段文字说不清楚。容易出错手工做时经常遗漏某一步希望用技能来兜底。反过来一次性的、纯粹靠模型推理就能搞定的任务写成技能反而是负担。技能的价值在复用没有复用就没有价值。这也是我建议新手从“自己最烦的那件事”入手的原因——它天然满足高频和易错两条。2. 目录结构与文件约定一个 Skill 的骨架长什么样搞清楚概念之后真正动手时第一个问题就是“文件该放哪、叫什么名、元数据写几行”。这块如果一开始就定好规矩后面能省掉大量返工。我现在的习惯是任何技能在动手写正文之前先把目录骨架搭出来再往里面填内容。2.1 SKILL.md 的分工元数据管“什么时候用”正文管“怎么用”绝大多数技能体系里入口文件都是一份 Markdown开头用一段结构化的元数据通常是 YAML 前置信息声明这个技能是谁、干什么用、什么时候该被调用紧接着的正文才是具体指令。这个分工背后有个很实用的逻辑——元数据是常驻的“索引”模型在决定要不要用某个技能时只需要扫一眼索引不必读完整个正文。正文是“按需加载”的重内容只有命中之后才展开。元数据里我必写的字段一般就两个核心name技能标识用小写加连字符别用空格和大写和description一句话说清“做什么”和“什么时候用”。很多人把 description 写成一句产品介绍比如“本技能用于处理文档”这种写法几乎必然导致触发不准。正确的方向是把它写成触发条件的集合把用户可能的表述、任务类型、适用边界都塞进去因为模型判断要不要调用主要就看这几十个字。注意description 不是给你看的文档是给模型看的“决策依据”。宁可写得“啰嗦”也不要写得“优雅”。我见过太多技能不触发根因都在这里。2.2 脚本、参考文档、资源文件各归各位正文之外技能通常会带上几类附属文件。我的整理习惯是按用途分目录避免全部堆在根目录scripts/可执行的脚本比如数据清洗、格式转换、批量处理。这类文件体积可能不小写成正文会让上下文爆炸所以单独放正文里只写“执行 scripts/xxx.py 完成转换”。references/参考文档比如字段字典、接口约定、行业规范。它是给模型“查”的不是给模型“背”的需要时再读。assets/静态资源模板文件、配置样例、图标之类。这些通常不需要被读进上下文只是被脚本引用。这个分法的核心思想是“把重的东西移出常驻上下文”。我早期把所有逻辑都写进正文一个技能文件撑到两千行结果每次触发都占用大量上下文还没干正事就已经把预算烧掉一半。拆出去之后正文通常能压到一两百行以内触发又快又准。2.3 渐进式披露为什么不能把所有内容塞进一个文件渐进式披露是这类技能体系最有价值的设计没有之一。它把信息分成三层第一层是元数据永远在场体积极小第二层是正文指令命中后加载第三层是附属文件只有在正文明确引用、且确实需要时才读取。这三层像漏斗一样越往下读的东西越少、越具体。这样设计的好处用一句话概括让智能体在“知道有这项能力”和“掌握这项能力的全部细节”之间留出缓冲。它能知道有一百个技能可用但同一时刻只需真正展开其中一两个的细节。如果没有这层机制一百个技能全量塞进去上下文早就爆了模型注意力也废了。理解这一点你在组织技能内容时就会有意识地把“索引信息”和“执行细节”分开而不是一股脑往下堆。3. 手把手写第一个 Skill从模糊需求到跑通闭环光讲结构没意思我拿一个真实需求走一遍全流程。需求是这样的每周我都要把一批结构不统一的文本记录整理成规范表格字段顺序老是记混还经常漏掉校验。这个任务高频、易错、有明确的处理套路完全符合上一节说的封装标准。3.1 需求拆解把“整理记录”翻译成可执行步骤动手写之前我先在纸上把流程拆成不可再分的动作这一步偷懒后面必翻车。拆完是这样确认输入文件位置与格式判断是纯文本还是带分隔符的结构化文本。按行解析识别每条记录的字段边界。把字段映射到目标表格的列注意字段名可能有多种写法。逐条做合法性校验日期格式、必填项、数值范围。把校验失败的记录单独挑出来附上失败原因。输出规范表格同时输出一份校验报告。拆到这一步我才发现真正的难点在第三步和第四步——字段别名映射和校验规则。这两块正是“隐性经验”也是技能该固化的部分。至于读写文件本身交给脚本就行。3.2 元数据字段的取舍少即是多但描述要够“贪”拆完流程先写元数据。name 我定为record-normalizer全小写加连字符避免任何大小写和特殊符号带来跨平台问题。description 我写了这么一段意思把不规范的文本记录整理成标准表格适用于字段顺序混乱、名称不统一的记录整理场景当用户提到“整理记录”“统一格式”“批量转表格”“字段对不上”等需求时使用。这里有个取舍原则要分享name求稳定一旦发布就别乱改因为其它技能或流程可能引用它description求覆盖要主动把用户各种可能的说法都纳进去哪怕显得同义反复。我一开始 description 只写了一句“整理文本记录”测试时十个用例里只命中三个补全同义表述后命中率立刻上去了。这就是前面说的它是决策依据不是文档标题。3.3 正文指令的写法触发条件、执行流程、边界与异常正文我按四段式来写这也是我自己总结下来最好用的模板。第一段重申触发场景让模型再次确认该不该用第二段是分步骤的执行流程每一步都写清楚输入、动作、输出第三段是边界条件明确哪些情况不该用它处理避免技能被滥用第四段是异常处理列出常见失败场景和应对方式。举个正文里校验环节的写法示例我会写成类似下面这种结构这里是示意不是可运行代码第 4 步字段校验 - 日期字段必须是 YYYY-MM-DD 格式遇到 2024/1/5 这类写法先尝试归一化无法归一化则标记失败。 - 金额字段只允许数字与小数点去掉千分位逗号后再校验。 - 必填字段姓名、日期、金额缺一不可缺失即判失败。 - 校验失败的记录不丢弃统一追加到报告文件附上失败行号和原因。注意我把“怎么补救”写进去了比如日期归一化、去掉千分位。这些就是纯靠模型常识不会主动做的细节也正是技能存在的意义。正文写得好不好差别全在这些地方。3.4 挂载脚本并验证闭环正文写完处理脚本单独放进 scripts 目录正文里只写一行“调用 scripts/normalize.py 完成解析与输出”。脚本里我只负责机械活读文件、按规则解析、调校验函数、写输出。所有“要不要做、遇到问题怎么办”的判断都留在正文由模型决策脚本只做确定性的执行。这个分工非常重要把决策和执行分开脚本才能稳定、可测试。验证环节我固定跑三类用例正常输入、边界输入缺字段、格式怪异、异常输入空文件、编码错误。跑完我会回到正文把用例暴露出来的新情况补进异常处理段。技能不是写完就结束它是“用一次、改一次”的活文件。我现在的习惯是第一次跑通不算数连续三天在真实任务里用不出问题才算基本稳定。4. 触发与编排Skill 在真实流程里怎么被调用技能写好了不代表会被用上。我遇到过最尴尬的情况是——技能明明存在智能体却视而不见自己用通用方法硬做结果做得一塌糊涂。问题几乎全部出在“触发”环节。这一节讲我怎么调命中率以及多个技能一起工作时怎么不打架。4.1 触发命中率八成取决于描述写得好不好触发本质上是模型拿当前任务去匹配技能的元数据描述。匹配不准无非两种原因描述太窄覆盖不到用户的真实说法描述太泛什么都沾一点导致该用别的技能时也来抢。我调命中的第一步永远是看“用户会怎么说”而不是看“我怎么说”。我会把真实任务里出现过的原话记下来整理成同义词列表再合并进 description。举例同样是日期处理类需求用户可能说“时间对不上”“日期格式乱”“统一一下时间”如果你描述里只写“日期格式化”那前两种说法就命不中。我的做法是保留核心动作词再加上两三个高频口语说法。但也别过头我见过描述写了一大段把五六个不相关的场景都列进去结果到处被误触发反而更糟。拿不准的时候宁可窄一点误触发比漏触发更烦人因为它会悄悄污染结果。4.2 多个技能协作时的冲突与优先级真实任务很少只靠一个技能完成。比如“整理记录”这个技能内部可能还要调用一个“编码检测”和一个“表格导出”的小技能。技能一多冲突就来了同一个任务两个技能都说自己能处理模型该听谁的我的处理原则有三条。第一职责单一一个技能只干一类事宁可拆细也不要写一个“什么都能干”的巨型技能那种技能往往是误触发的重灾区。第二描述互斥写新技能时回看一下已有技能的描述确保关键词不重叠。第三显式编排当一个任务确实需要多步我会写一个“上层技能”它的正文里明确写出调用顺序把并列关系变成串行流程模型就不必自己猜该先做哪个了。这三条里显式编排最有效也最容易被忽略。很多人指望模型自动编排实测下来不稳定把顺序写死反而省心。4.3 上下文预算管理别让技能吃掉半个对话前面提过渐进式披露这里从预算角度再展开讲。技能系统如果放任不管很容易出现一个隐形问题技能越写越多某个技能正文也越来越长虽然只在触发时加载但一个超长正文照样能把上下文吃掉大半。我给自己定的红线是——单个技能正文控制在两百行以内超过就拆。附属文件严格按需读取正文里写出“何时读、读哪个”不要让模型自己决定要不要全读一遍。还有个实用技巧把“不变的部分”和“常变的部分”分开。参考资料、字段字典这类很少变的内容放外部文件流程和判断这类会随经验更新的内容放正文。这样每次迭代只动正文附属文件基本不用碰。预算管理看似是技术问题其实是写作纪律问题——克制是写好技能最重要的品质。5. 常见问题与排查技巧实录这部分是我踩坑最多的地方也是最值得单独记下来的经验。我把它们整理成可对照的排查表遇到问题时从上往下过一遍基本能定位到原因。5.1 技能不触发或误触发按这个顺序查现象可能原因排查动作技能总不触发description 用词太窄没覆盖用户说法收集真实任务原话补充同义词技能总不触发元数据格式有误解析失败检查字段名拼写、缩进、冒号后是否有空格技能被误触发描述太泛关键词与其它技能重叠收窄描述去重关键词明确边界段时好时坏触发词依赖模糊语境在正文首段再次强调适用与不适用场景技能被跳过已有更强的一般性处理路径在描述里突出“专有经验”拉开与通用方法的差异这张表里我特别想强调格式问题。YAML 前置信息对缩进和标点极其敏感一个冒号后面少个空格、或者用了中文标点整个元数据就可能解析失败技能直接“隐身”。我因为一个全角冒号排查了整整一个下午从那以后每次改元数据都会先跑一遍解析验证。5.2 脚本执行失败八成是环境而不是逻辑脚本报错时新手容易一头扎进代码里找逻辑 bug但我的经验是——先查环境再查逻辑。环境问题包括脚本依赖的解释器版本不对、相对路径写死了导致换目录就找不到文件、文件编码不一致、临时目录没权限。这些问题占了报错的一大半。我的排查顺序是先确认脚本能不能手动独立跑通能跑通说明环境没问题再怀疑正文里的调用方式手动跑不通就直接看报错栈。有个小技巧脚本里所有路径都用相对于技能目录的方式处理绝对不要硬编码用户的绝对路径否则换台机器必挂。另外脚本最好把关键中间结果打印出来出问题时一眼能看出卡在哪一步比事后加日志高效得多。5.3 版本管理与团队协作的那些坑技能一旦多人共用问题就从技术变成协作了。我遇到过两次比较难受的情况一次是两个人同时改了同一个技能的正文覆盖掉了对方的改动一次是某个技能的依赖脚本被更新了但正文里描述的行为没同步导致结果对不上。后来我们定了几条规矩。第一技能目录整体纳入版本管理每个技能独立成目录改动记录跟着走。第二元数据里加一个版本字段正文有实质变更就升版本。第三改共享技能前先在本地跑那三类用例正常、边界、异常通过了再合并。第四正文里的脚本引用写相对路径脚本更新时检查正文是否还准确。这几条看着繁琐但比起线上结果出错再回头重建成本低太多了。5.4 几个我反复强调的实操心得第一先手动做三遍再写技能。你以为自己很懂流程其实只有真正动手做几遍才能发现那些藏在细节里的判断点这些才是技能最有价值的部分。第二技能不是越大越好。一个能覆盖三种任务的大技能维护起来比三个小技能的痛苦程度高一个量级出问题时也更难定位。第三描述和正文要分开维护思路描述面向“被选中”正文面向“被执行”两者的优化方向完全不同混在一起想就会两头不讨好。第四给每个技能配一个最简用例放在目录里作为回归测试改完就跑一遍能挡住大部分低级退化。5.5 技能成熟度的自查清单最后给一个我自己在用的自查清单一个新技能写完后我会逐条过一遍全过了才敢放进共享目录元数据能正常解析name 稳定、description 覆盖了主要说法。正文在两百行以内触发条件、流程、边界、异常四段齐全。附属文件按 scripts / references / assets 分好正文里明确了何时读取。三类用例正常、边界、异常都跑通结果符合预期。与已有技能的描述不重叠必要时写了显式的编排流程。版本字段已填写改动记录清晰。说到底agent-skills 这套东西没有多玄乎它更像是把“老师傅带徒弟”的那套经验沉淀成文件。工具会过时接口会变但“一件事该怎么做、哪里容易出错、遇到问题怎么兜底”这种知识永远有价值。我现在的做法是每次在真实任务里被某个流程坑到就顺手把它整理成一个技能用得越多沉淀越厚后面接手类似任务时就越轻松。这个循环一旦转起来你会发现自己花在重复解释上的时间越来越少能把精力放到真正需要判断的地方去。