1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题加上项目正文和关键词都是空的我其实是有点懵的。但结合热搜词里那一串——Agent Skills、Google Cloud、GKE、Genkit、claude agent skills、codex skills、skills开发、skills安装——基本可以锁定这里说的不是泛泛的技能概念而是围绕 AI Agent 的能力扩展机制也就是给智能体装技能这件事。打个比方。一个刚出厂的大模型就像一个刚毕业的高材生脑子好使但没上过班。你让它写代码它能写你让它查资料它能查可一旦涉及我们公司内部这套流程怎么走这个特定工具怎么调遇到这种报错该按什么顺序排查它就抓瞎了。Agent Skills 要解决的就是把这个高材生变成熟练工的问题——把特定领域的操作流程、工具调用方式、判断规则打包成一个个可复用的技能包让 Agent 按需加载。这套思路最近为什么火因为大家发现单纯堆参数、堆上下文效果是有天花板的。你把一万字的操作手册塞进 prompt模型可能只记住前两千字中间还容易串味。而 Skills 的思路是按需加载、模块化组织平时不占上下文用到哪个技能就调哪个用完就释放。这跟人脑的工作方式很像——你不需要时刻记住所有会的技能只在需要拧螺丝的时候才想起哦我会用螺丝刀。这篇文章我打算把skills这件事从头到尾拆一遍它背后的核心机制是什么、一个技能包到底长什么样、怎么从零开发一个能用的 skill、装完之后怎么测试、以及我在实际折腾过程中踩过的那些坑。不管你是刚听说这个词想入门还是已经写过几个 skill 但总觉得哪里不对应该都能捞到点东西。提示本文讨论的 skills 特指 AI Agent 的能力扩展单元不涉及任何其他含义。如果你搜到的是别的领域的内容那可能不是同一回事。2. 拆开一个 Skill 看内部它凭什么能让 Agent 变聪明2.1 Skill 的本质是一份给模型看的说明书很多人第一次接触 skills会以为它是什么高深的代码框架。其实剥开外壳一个 skill 的核心就是一份结构化的说明文档外加可选的辅助资源。它告诉模型三件事这个技能是干什么的、什么时候该用它、具体怎么操作。你可以把它理解成给新员工写的 SOP标准作业程序。一份好的 SOP 不会写你要认真工作这种废话而是写客户投诉时先记录工单号再查订单状态如果超过 48 小时未发货走加急流程。Skill 也是这个逻辑——它把模糊的你看着办变成明确的第一步做什么、第二步做什么、遇到什么情况走什么分支。那它和普通的 prompt 有什么区别区别在于组织方式和加载时机。普通 prompt 是你每次对话都得把全部指令塞进去又长又费 token。而 skill 是独立存放的模型在判断当前任务需要这个技能时才把它读进来。这就好比你不会每天上班都背一遍员工手册但需要报销的时候会去翻报销流程那一章。2.2 元数据、指令、资源三层结构各管什么一个规范的 skill 通常分三层我按重要性从外到内说。最外层是元数据metadata一般包含技能名称、一句话描述、适用场景标签。这一层的作用是让 Agent 快速判断这个技能跟我当前的任务搭不搭。描述写得越准模型选错技能的概率越低。我见过太多人这一层随便写结果模型该用的时候不用、不该用的时候乱用问题全出在这。中间层是指令主体instructions也就是真正的操作说明。这里要写清楚步骤、判断条件、输入输出格式、边界情况怎么处理。这一层是 skill 的灵魂写得好的指令能让模型表现得像干了十年的老手写得烂的就是一堆正确的废话。最内层是辅助资源resources比如参考文档、示例数据、脚本模板、工具定义。这些不是每次都要加载的而是模型在执行过程中按需读取。比如一个生成周报的 skill可能附带一个周报模板文件模型需要时才去读。层级作用常见错误元数据让 Agent 判断是否加载描述太泛导致误触发或漏触发指令主体定义具体操作流程步骤跳跃、缺少分支判断辅助资源提供模板、示例、工具资源过大拖慢加载2.3 为什么按需加载比全塞进去更聪明这里得讲一个关键原理模型的上下文窗口是有限资源而且不是免费的。你塞进去的内容越多模型处理每个 token 的成本越高而且长上下文里模型对中间部分的注意力会下降——这就是所谓的lost in the middle现象。Skills 的按需加载机制本质是在做上下文预算管理。假设你有 50 个技能每个技能平均 2000 字全塞进去就是 10 万字模型直接爆窗口。但按需加载的话每次只调 1 到 2 个相关技能上下文占用可能就几千字又省又准。这跟图书馆的逻辑一模一样。你不会把整个图书馆的书搬回家而是需要哪本借哪本。Skill 的元数据就是图书馆的检索目录指令主体就是书的内容辅助资源就是书里夹的附件。2.4 和传统函数调用、插件机制的区别在哪有人会问这不就是函数调用function calling或者插件吗还真不太一样。函数调用是模型决定调哪个 API、传什么参数它解决的是执行动作的问题。而 skill 解决的是知道该怎么做的问题。举个例子函数调用能让模型去查数据库但查数据库之前要先验证用户权限、查完之后要按什么格式整理结果这些流程性知识函数调用本身是不管的得靠 skill 来提供。插件机制通常和具体平台强绑定换个环境就不一定能用。而 skill 更像是一种跨平台的约定只要目标 Agent 支持读取这种结构化的技能描述就能复用。这也是为什么最近 skills 生态能起来——大家发现这套东西可移植、可组合、可分享。3. 从零开发一个能用的 Skill我的完整流程3.1 先想清楚这个技能解决什么具体问题开发 skill 最容易犯的错就是一上来就写指令结果写出来的东西又大又空。我的习惯是先用一句话把技能的目标钉死。比如帮我处理数据这种目标就是不合格的太泛了。合格的应该是把用户粘贴的 CSV 文本清洗成标准格式去掉空行、统一日期格式、把金额列转成数字。目标越具体后面写指令越顺模型用起来也越准。我一般会问自己三个问题这个技能输入是什么用户会给什么、输出是什么期望得到什么、中间有哪些判断分支什么情况下走什么路。这三个问题答清楚了skill 的骨架就有了。3.2 元数据怎么写才能让 Agent 精准命中元数据里的描述字段是模型决定要不要用这个技能的唯一依据。所以它必须同时满足两个条件够具体能区分够简洁不啰嗦。我踩过的坑是早期我把描述写得很宽泛比如用于处理各种文档任务。结果模型只要碰到跟文档沾边的任务不管三七二十一就加载这个技能然后发现技能里的指令根本不匹配当前任务白白浪费上下文。后来我改成当用户提供 Markdown 格式的会议记录需要提取待办事项并分配负责人时使用。这样模型一看就知道只有会议记录 提取待办这个组合才该触发。描述里最好包含触发条件的关键词比如输入格式、任务类型、期望输出。注意描述不要写成广告词。本技能功能强大、支持多种场景这种话对模型判断毫无帮助反而增加误触发概率。3.3 指令主体的写法把老手经验翻译成步骤这是最考验功力的部分。我的经验是把自己当成在教一个聪明但完全不懂行的新人。聪明意味着你不用解释基础概念不懂行意味着你不能跳过任何一步。具体写法上我推荐编号步骤 条件分支 示例的组合。先列主干步骤然后在需要判断的地方插入如果……则……否则……最后给一两个输入输出示例。示例特别重要因为模型对示例的模仿能力远强于对抽象规则的理解。举个我写过的日志分析skill 的片段1. 读取用户提供的日志文本 2. 按行扫描识别包含 ERROR 或 WARN 的行 3. 对每个错误行 - 如果包含 timeout归类为网络问题 - 如果包含 null pointer归类为代码缺陷 - 其他情况归入待人工确认 4. 按类别汇总输出每类的数量和典型样例你看这里没有一句废话每一步都是可执行的。模型照着做基本不会跑偏。3.4 辅助资源怎么放才不拖后腿辅助资源的原则是能少则少能小则小。因为资源文件在加载时会占用上下文放太多大文件反而把技能本身的价值稀释了。我通常只放三类东西模板文件比如输出格式的样板、少量示例数据帮模型理解输入长什么样、工具定义如果技能需要调用外部工具。除此之外的东西能不放就不放。还有个技巧把大资源拆成多个小文件让模型按需读取。比如一个技能需要参考三种不同的规范文档那就拆成三个文件指令里写如果需要处理 A 类情况读取规范A.md。这样模型只在真正需要时才加载对应文件而不是一次性全读进来。3.5 一个完整 Skill 的目录长什么样说了这么多给个实际的目录结构参考my-skill/ ├── skill.md # 元数据 指令主体 ├── resources/ │ ├── template.md # 输出模板 │ └── examples.md # 示例数据 └── tools/ └── tool-def.json # 工具定义可选skill.md是入口模型先读它判断要不要用。如果用就按里面的指令执行需要资源时再去resources/里拿。这个结构简单清晰也方便分享和复用。4. 装完不等于能用Skill 的测试与调优4.1 为什么能跑通和跑得准是两回事很多人装完 skill随便试一个例子发现模型确实按步骤走了就以为大功告成。但实际用起来才发现换个输入就翻车。能跑通只说明语法没错跑得准才说明逻辑对。我一般会准备一组测试用例覆盖三类情况标准输入最典型的场景、边界输入空值、超长、格式不规范、干扰输入看起来像但不该触发这个技能的任务。三类都过了我才认为这个 skill 基本可用。4.2 我常用的三类测试用例设计标准输入不用多说就是正常用。边界输入是重点比如用户给了一个空表格、给了一段乱码、给了一个超长的文本。这时候 skill 应该优雅处理而不是直接崩掉或者输出一堆垃圾。干扰输入最容易被忽略。比如我有个代码审查的 skill结果模型碰到代码解释的任务也去加载它然后按审查的逻辑输出一堆改进建议用户其实只想知道这段代码在干嘛。这就是元数据描述不够精准导致的误触发。测试类型目的典型用例标准输入验证主流程格式规范的正常数据边界输入验证健壮性空值、超长、乱码干扰输入验证精准度相似但不该触发的任务4.3 命中率低、误触发、输出跑偏的排查顺序当 skill 表现不对时我按这个顺序排查第一步看是不是根本没触发。如果模型压根没用这个技能问题在元数据描述——要么描述太窄要么关键词没覆盖到。解决办法是把描述改得更贴近实际输入的表达。第二步看是不是误触发。如果模型在不该用的时候用了问题还是元数据——描述太宽泛或者和其他技能的描述有重叠。解决办法是加限定词把适用场景收窄。第三步看是不是触发了但输出不对。这时候问题在指令主体。常见原因是步骤有歧义、缺少分支判断、或者示例和实际输入差距太大。解决办法是补分支、加示例、把模糊表述改成明确判断。这个排查顺序很重要因为不同层的问题要用不同的方法修。很多人一上来就改指令结果发现根本是元数据没写对白忙活。4.4 迭代调优从能用到好用的几轮打磨一个 skill 从初版到稳定我一般要迭代三到五轮。第一轮修明显的逻辑漏洞第二轮补边界处理第三轮优化描述精准度第四轮精简冗余内容第五轮根据实际使用反馈微调。每轮迭代我都会记录改了什么、为什么改、改完效果如何。这个记录看起来麻烦但当你同时维护十几个 skill 的时候没有记录根本记不住哪个版本改了什么。而且这些记录本身就是宝贵的经验下次写新 skill 能少走很多弯路。5. 生态与工具链skills 在不同平台上的落地差异5.1 Google Cloud、GKE、Genkit 这条线怎么串热搜词里出现了 Google Cloud、GKE、Genkit这其实指向一条完整的落地链路。Genkit 是构建 AI 应用的框架GKE 是跑容器的平台Google Cloud 是底层基础设施。Skills 在这条链路上的角色是让部署在云端的 Agent 具备可扩展的能力模块。具体来说你可以把 skill 打包成容器镜像部署到 GKE 上然后通过 Genkit 定义的接口让 Agent 调用。这样做的好处是技能可以独立更新、独立扩缩容不用动主应用。比如你更新了一个数据清洗技能只需要重新部署这个技能的容器主 Agent 不受影响。5.2 不同 Agent 平台的 skill 格式差异目前 skills 还没有一个完全统一的标准不同平台各有各的约定。有的用 Markdown 加 frontmatter有的用 JSON 描述有的直接在代码里注册。这就导致一个现实问题为一个平台写的 skill换到另一个平台可能要改格式。我的应对策略是把技能的核心逻辑和平台格式分离。核心逻辑用纯文本写清楚平台相关的部分比如元数据的字段名、资源的引用方式单独处理。这样迁移的时候只需要改外壳不用重写内容。5.3 从社区找现成 skill 时怎么判断质量社区里现在有不少分享出来的 skill但质量参差不齐。我判断一个 skill 值不值得用主要看三点描述是否具体泛泛而谈的直接跳过、指令是否有分支判断只有线性步骤的通常不够健壮、是否附带测试用例有测试的说明作者认真调过。另外还要看更新时间和反馈。一个半年没更新、也没人讨论的 skill大概率是有坑没人填。反过来如果一个 skill 有持续的 issue 讨论和版本迭代那通常比较靠谱。6. 那些没人告诉你的坑我的踩坑实录6.1 描述写太宽模型到处乱用这是我最早踩的坑。我写了一个文本总结的 skill描述写的是用于总结各种文本。结果模型只要碰到跟文本沾边的任务不管是要翻译、要改写、还是要提取信息都先加载这个总结技能然后按总结的逻辑去处理输出完全不对路。后来我把描述改成当用户提供一篇超过 500 字的文章明确要求生成简短摘要时使用。触发范围一下子收窄了误触发率大幅下降。教训是描述里的每个词都在划定边界边界越清晰模型判断越准。6.2 指令里藏了隐含假设有次我写了个生成 SQL 查询的 skill指令里默认用户给的表名是英文的。结果遇到中文表名的场景模型生成的 SQL 直接报错。问题就出在我没把表名可能是中文这个假设写出来。隐含假设是 skill 开发里最隐蔽的坑因为你自己知道就以为模型也知道。解决办法是写完指令后找个完全不懂这个领域的人读一遍看他能不能挑出这里默认了什么。挑出来的每一条都要在指令里显式说明。6.3 资源文件太大导致加载变慢我曾经在一个 skill 里放了一个 5000 行的参考文档想着资料越全越好。结果每次加载这个技能上下文直接被占掉一大半模型处理速度明显变慢而且因为内容太多模型反而抓不住重点。后来我把那个文档拆成了五个小文件按主题分开指令里写清楚处理 X 类问题时读 A 文件处理 Y 类问题时读 B 文件。加载速度回来了输出质量也上去了。资源不是越多越好而是越精准越好。6.4 版本更新后旧 skill 突然失效这个坑比较隐蔽。有次平台更新了 skill 的加载机制我原来写的元数据字段名变了结果所有旧 skill 全部失效。因为平时用得好好的根本没注意到平台发了更新公告。从那以后我养成了习惯定期检查 skill 的运行日志看有没有加载失败的记录。另外重要的 skill 我会在本地留一份可运行的备份万一平台出问题能快速切换。6.5 多个 skill 互相干扰怎么办当你装的 skill 多了会出现一种情况两个 skill 的描述有重叠模型不知道该用哪个或者两个都用输出混在一起。我遇到过代码优化和代码审查两个 skill 打架模型一会儿给优化建议一会儿给审查意见输出很乱。解决办法有两个一是在描述里明确区分适用场景比如代码优化写当用户要求提升代码性能时使用代码审查写当用户要求检查代码规范时使用二是在指令开头加一句排他说明比如本技能只处理性能问题不涉及代码风格。这样模型判断起来就清晰了。7. 我对 skills 这件事的真实看法折腾了这么久 skills我最大的感受是它不是一个技术问题而是一个表达问题。你能不能把一个领域的知识拆解成模型能理解、能执行的步骤这才是核心难点。技术框架、平台工具都是次要的真正决定 skill 好不好用的是你对那个领域的理解够不够深、表达够不够准。另一个感受是skills 的生态还在早期标准不统一、工具不完善、坑也不少。但这恰恰是机会——现在投入去写、去试、去踩坑积累下来的经验等生态成熟了就是壁垒。我见过太多人等着标准出来再动手结果标准出来的时候早动手的人已经攒了一堆可复用的技能库了。如果你刚开始接触我的建议是从一个小而具体的技能入手别一上来就搞大而全的。写一个把日期格式统一成 YYYY-MM-DD这种小技能跑通整个流程理解每一层的作用然后再逐步扩大。小技能踩的坑和大技能是一样的但修复成本低得多。最后分享一个我自己的小技巧每次写完一个 skill先别急着用放一天再回来看。隔一天再看你会发现很多当时觉得写得很清楚的地方其实有歧义。这个隔夜检查的习惯帮我省下了大量后期调试的时间。