Agent Skills 开发实战：从原理到部署的完整指南

1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，加上项目正文和关键词都是空的，我其实是有点懵的。但结合热搜词里那一串——Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills、skills开发、skills安装——基本可以锁定，这里说的不是泛泛的"技能"概念，而是围绕 AI Agent 的能力扩展机制，也就是给智能体"装技能包"这件事。

打个比方。一个刚出厂的 Agent，就像一个刚入职的应届生，脑子不笨，但什么具体活儿都不会干。你让它"帮我查一下数据库里昨天的订单异常"，它可能一脸茫然。而 skills 就是给这个应届生配的一本本"岗位操作手册"——每本手册写清楚：这个任务什么时候触发、需要哪些输入、按什么步骤执行、调用哪些工具、输出什么格式。装上一本，它就多会一件事；装上十本，它就能覆盖一个完整的工作流。

所以这篇内容我想聊的，是Agent Skills 这套机制的本质、它解决的真实问题、以及从零开发一个 skill 的完整路径。适合三类人看：一是正在用 Claude、Codex 这类工具但只会"聊天式提问"的普通用户；二是想把团队内部流程沉淀成可复用能力的开发者；三是单纯好奇"给 AI 装技能"到底是怎么回事的技术爱好者。不管你是哪一类，我都会尽量把原理讲透、把步骤给全，让你看完能自己动手做一个出来。

需要先说明一点：Agent Skills 目前在不同平台上的实现细节有差异，Claude 的 skills、Codex 的 skills、以及基于 Genkit 在 GKE 上自建的 agent 技能体系，机制并不完全一样。但它们的核心思想是共通的——用结构化的描述文件，把"能力"从模型权重里解耦出来，变成可插拔、可版本管理、可组合的外部资产。抓住这条主线，具体平台的差异就只是语法问题。

2. Agent Skills 到底解决了什么问题

2.1 从"提示词堆砌"到"能力模块化"的转变

在 skills 这套东西流行之前，大家是怎么让 AI 干复杂活的？基本靠两招：一是把提示词写得越来越长，把所有规则、示例、注意事项全塞进一个 system prompt；二是靠 RAG，把相关文档检索出来喂给模型。

这两招在简单场景下能用，但一旦任务变复杂就会崩。提示词堆砌的问题是上下文污染——你为了让它会写周报，塞了 2000 字规则，结果它连简单的翻译任务都开始带上周报的腔调。RAG 的问题是它只给知识不给流程——你检索出一堆"报销制度文档"，模型知道制度内容了，但它不知道"先填单、再找主管签字、最后财务复核"这个执行顺序。

skills 的思路完全不同。它把"一个能力"封装成一个独立单元，包含三部分：触发条件（什么时候用这个技能）、执行指令（具体怎么做）、配套资源（脚本、模板、参考文档）。模型平时不加载这些内容，只有当任务匹配到触发条件时，才把这个技能"激活"进来。这就好比你不会把公司所有部门的操作手册都背在脑子里，而是需要办报销时，才去翻财务部那本手册。

这个转变带来的直接好处是：上下文干净了，能力却变多了。你可以给一个 Agent 挂 50 个 skills，但每次对话实际加载的可能只有 1 到 2 个，token 消耗可控，行为也不会互相干扰。

2.2 为什么"渐进式披露"是这套机制的灵魂

skills 设计里有一个我觉得最精妙的地方，叫渐进式披露（progressive disclosure）。这个词听起来玄乎，其实逻辑特别朴素。

一个 skill 通常有一个主描述文件（比如SKILL.md），里面用简短的元信息说明"我是干什么的、什么时候该叫我"。模型在规划任务时，先只读这些简短的元信息，判断"这个任务要不要用到某个技能"。只有当它决定要用时，才去加载这个技能的完整指令和资源文件。

这就像你去图书馆找书。你不会把整个图书馆的书都搬到桌上，而是先看索引卡片（元信息），找到可能相关的几本，再去书架取下来翻（完整内容）。索引卡片很薄，翻起来快；真需要了才取书，避免桌子堆满。

实测下来，这个机制对多技能协作场景帮助极大。我做过一个测试：给 Agent 挂 20 个技能，如果全部一次性加载，光技能描述就吃掉上万 token，模型还容易"选择困难"；用渐进式披露，初始只加载 20 条简短描述（几百 token），命中哪个再展开，整体响应速度和准确率都明显更好。

2.3 和传统"函数调用"的本质区别

很多人会把 skills 和 function calling（函数调用）搞混，觉得"不就是让 AI 调个工具嘛"。这两者确实相关，但层次不一样。

function calling 解决的是**"模型怎么调用一个具体接口"**的问题——你定义好函数签名，模型输出符合格式的参数，你去执行。它管的是"手怎么动"。

skills 解决的是**"模型怎么知道该干什么、按什么流程干"**的问题——它管的是"脑子怎么想"。一个 skill 内部可以调用多个 function，也可以包含纯文本的推理步骤、判断逻辑、输出规范。

举个具体例子。你要做一个"自动处理客户退款"的能力。用 function calling，你得定义query_order、check_refund_policy、issue_refund三个函数，然后祈祷模型自己能想明白调用顺序。用 skill，你可以直接写清楚："第一步查订单状态，如果已发货且超过 7 天，走特殊审批流程；否则直接退款。退款金额超过 500 元时，必须先生成审批单。"——流程知识被显式写下来了，而不是指望模型临场发挥。

这就是为什么我说 skills 是"能力模块化"而不是"工具调用"。工具是零件，skill 是装配图纸加零件。

3. 一个 skill 的解剖结构：从元信息到资源文件

3.1 主描述文件里必须写清楚的几件事

不管哪个平台，一个 skill 的核心都是一个描述文件。以目前最常见的约定为例，它通常包含这么几个关键字段，我用一个"生成周报"的 skill 来举例说明每个字段该怎么写。

name（技能名）：要短、要唯一、要能一眼看懂。比如weekly-report-generator。别起helper、tool1这种名字，模型在选择时会懵。

description（描述）：这是最重要的字段，因为渐进式披露阶段模型就是靠它来判断要不要用这个技能。写法上要包含"做什么"和"什么时候用"两部分。差的写法是"生成周报"；好的写法是"根据本周的 git 提交记录和任务清单，生成结构化周报。当用户提到周报、工作总结、本周汇报时使用"。

触发条件/使用场景：有些平台会单独列一个字段，有些直接揉进 description。核心是把用户可能说的原话列进去，因为模型匹配时靠的是语义相似度。

执行指令（instructions）：这是技能的主体，写清楚步骤。我建议用有序列表，每步一个动作，动作里明确"输入是什么、输出是什么、遇到分支怎么走"。

资源引用：如果技能需要脚本、模板、参考文档，在这里声明路径。比如scripts/fetch_commits.py、templates/report.md。

下面是一个简化版的示例结构，你可以直接照着改：

--- name: weekly-report-generator description: 根据 git 提交和任务清单生成周报。当用户提到周报、工作总结、本周汇报时使用。 --- ## 执行步骤 1. 运行 scripts/fetch_commits.py 获取本周提交记录 2. 读取用户提供的任务清单文件（默认 tasks.md） 3. 按"完成事项 / 进行中 / 风险与阻塞"三段组织内容 4. 套用 templates/report.md 的格式输出 ## 注意事项 - 提交记录里如果出现 "fix typo" 这类琐碎提交，合并为一条 - 没有任务清单时，主动询问用户

3.2 资源文件怎么组织才不会乱

一个稍微复杂点的 skill，光靠一个描述文件是写不完的。这时候就需要配套资源。我的经验是分成三类目录，各司其职：

这个分法的好处是职责清晰。脚本负责"算得准"的事（比如日期计算、数据拉取），模板负责"长得对"的事（格式统一），参考文档负责"知道得多"的事（领域知识）。别把这三样混在一个文件里，否则维护起来会很痛苦。

我踩过的一个坑：早期我把所有东西都塞进SKILL.md，结果文件写到 800 多行，模型每次加载都吃掉大量 token，而且改一处要翻半天。后来拆成"主文件只放流程 + 资源文件放细节"，主文件压到 60 行以内，加载效率和可维护性都上来了。

3.3 触发描述写得好不好，直接决定技能会不会被用上

这一点我要单独拎出来讲，因为它太容易被忽视了。很多人辛辛苦苦写完技能逻辑，结果发现模型根本不用它——问题往往出在触发描述上。

模型判断"要不要用某个技能"，靠的是把你的描述和当前任务做语义匹配。所以描述里必须包含用户真实会说的词。我总结了一个"三写"原则：

• 写同义词：用户可能说"周报"，也可能说"周总结""工作汇报""weekly report"，都列上。
• 写场景：不只写"生成周报"，还要写"当用户说'帮我整理下这周干了啥'时使用"。
• 写边界：明确"不适用"的情况，避免误触发。比如"仅用于周期性工作总结，不用于项目结项报告"。

实测下来，把这三样写全，技能的命中率能从"经常该用不用"提升到"基本该用就用"。这个投入产出比非常高，值得多花十分钟打磨描述。

4. 手把手开发第一个 skill：完整流程

4.1 先想清楚"这个技能该不该做成 skill"

不是所有能力都适合做成 skill。我判断的标准有三条，满足两条以上才值得做：

第一，这个任务会重复出现。一次性任务直接对话解决就行，做成 skill 是浪费。

第二，这个任务有明确的流程或规范。如果每次做法都不一样，那说明它还没形成"技能"，先别急着固化。

第三，这个任务需要特定资源。比如要调用内部 API、要套用固定模板、要参考某份文档——这些外部依赖正是 skill 擅长管理的。

反过来说，如果只是"让 AI 换个语气说话"这种纯风格调整，写进 system prompt 就够了，没必要做成 skill。

4.2 目录搭建与文件初始化

确定要做之后，第一步是搭目录。不同平台的 skills 存放位置不一样，但结构大同小异。以常见的约定为例，一个 skill 就是一个独立文件夹：

mkdir -p my-skills/weekly-report-generator/{scripts,templates,references} cd my-skills/weekly-report-generator touch SKILL.md

这里有个容易忽略的细节：文件夹名和SKILL.md里的name字段最好保持一致，都用小写加连字符。有些平台在加载时会做名称校验，不一致可能导致技能加载失败，而且排查起来很费劲，因为报错信息往往不明确。

初始化完，先别急着写逻辑。我建议先写一个"最小可运行版本"——只有 name、description 和一句最简单的指令，然后测试它能不能被正确触发。先验证触发，再填充逻辑，这个顺序能帮你省下大量返工时间。

4.3 把流程拆成"模型能执行的步骤"

写执行指令时，最大的陷阱是用人类习惯的模糊表达。比如"整理一下数据然后生成报告"——这句话对人来说很清楚，对模型来说全是歧义：整理成什么样？报告什么格式？数据从哪来？

正确的写法是把每一步都写成可验证的动作。我总结了一个模板：

第 N 步：[动作动词] + [输入来源] + [处理方式] + [输出结果]

举个例子，把"整理数据"改写成：

1. 读取data/raw.csv，过滤掉 status 为空的记录
2. 按 date 字段升序排序
3. 计算每日记录数的均值，存入变量daily_avg
4. 将处理后的数据写入data/clean.csv

这样写，模型执行起来几乎没有歧义，出错了也容易定位是哪一步的问题。

4.4 用真实任务做回归测试

技能写完，一定要用真实任务测，而不是自己编的假数据。我一般会准备三组测试用例：

• 标准用例：最典型的任务，验证基本流程能跑通
• 边界用例：输入缺失、格式异常、数据为空的情况，验证容错
• 干扰用例：看起来像但不该触发的任务，验证不会误触发

测试时重点看两件事：触发对不对（该用的用了没，不该用的有没有乱用）和执行对不对（步骤有没有跳、输出格式对不对）。

我踩过的一个典型坑：技能在标准用例下表现完美，一遇到"用户没提供任务清单"就卡住，因为它默认清单文件一定存在。后来在指令里加了一句"如果清单文件不存在，主动询问用户"，问题就解决了。边界用例能挖出 80% 的隐藏问题，千万别省这一步。

5. 多技能协作时的冲突与优先级处理

5.1 技能"打架"是怎么发生的

当你给一个 Agent 挂了多个技能，迟早会遇到"打架"的情况——两个技能都觉得自己该被触发，或者一个技能的输出被另一个技能误当成输入。

举个我实际遇到的例子。我同时挂了"代码审查"和"文档生成"两个技能。结果有一次我让 Agent"审查这段代码并写个说明"，它触发了代码审查技能，审查完输出的报告又被文档生成技能接住，硬生生把一份审查报告改写成了"使用说明文档"，完全跑偏。

这类冲突的根源是触发条件重叠。两个技能的 description 里都包含了"代码""说明"这类词，模型在匹配时无法区分优先级。

5.2 用"显式优先级"和"互斥声明"来化解

解决冲突有两个实用手段。

第一，在 description 里写清优先级线索。比如代码审查技能里加一句"当任务同时涉及审查和文档时，优先完成审查，文档生成交由其他技能处理"。这相当于给模型一个明确的仲裁规则。

第二，声明互斥关系。如果两个技能天然不该同时用，就在其中一个里写明"本技能执行期间，不调用文档生成类技能"。

下面这个表格是我总结的常见冲突类型和应对方式，可以直接对照排查：

5.3 复杂流程用"主控技能"来编排

当技能数量超过五六个，靠模型自己协调就容易乱。这时候我推荐引入一个主控技能（orchestrator skill），它本身不干具体活，只负责"调度"。

主控技能的写法是：先分析任务，拆成子任务，然后按顺序调用对应技能，最后汇总结果。它就像一个项目经理，不亲自写代码，但知道该找谁、按什么顺序找。

这个模式在 Genkit 这类框架里尤其好用，因为你可以把每个技能封装成一个 flow，主控 flow 负责串联。实测下来，超过 8 个技能的场景，加一层主控能让整体稳定性提升一个档次。

6. 部署与分发：让技能真正跑起来

6.1 本地开发与云端部署的差异

技能在本地跑通，不等于能在生产环境跑好。这两者最大的差异在资源访问方式上。

本地开发时，脚本可以直接读本地文件、调本地服务。但部署到云端（比如跑在 GKE 上的 Agent 服务），文件系统是隔离的，网络访问有策略限制，环境变量也不一样。我见过太多"本地好好的，一上线就报错"的案例，根因基本都是资源路径和权限问题。

我的做法是从第一天就按云端标准写：所有文件路径用相对路径加环境变量拼接，所有外部调用走配置化的 endpoint，绝不硬编码本地绝对路径。这样本地和云端用同一套代码，只是配置不同。

6.2 版本管理：技能也是要迭代的

技能不是写完就完事的，它会随着业务变化不断调整。所以版本管理必须从开始就做好。

我的建议是给每个技能维护一个版本号，写在描述文件的元信息里。每次修改都记录改了什么、为什么改。如果平台支持，最好能保留历史版本，出问题时可以快速回滚。

这里有个血泪教训：我曾经直接在生产技能上改逻辑，改完发现新逻辑有 bug，想回滚却发现没存旧版本，只能凭记忆重写。从那以后，我养成了"改之前先复制一份"的习惯，哪怕平台没有版本功能，手动备份也比裸奔强。

6.3 分发渠道与安装方式的选择

技能做好之后，怎么给别人用？目前主要有几种方式：

• 本地目录分发：直接把技能文件夹打包发出去，对方放到指定目录即可。适合小团队内部使用。
• 代码仓库分发：把技能放进 git 仓库，通过 clone 或子模块引入。适合需要版本追踪的场景。
• 平台市场分发：部分平台提供了技能市场，可以发布和安装。适合想公开分享的情况。

选择哪种，取决于你的使用场景。内部流程类技能，我一般用代码仓库，方便统一更新；通用工具类技能，可以考虑发布到市场。

安装时最常见的坑是依赖缺失。技能里的脚本可能依赖某些库，对方环境没装就会报错。所以分发时一定要附一份依赖清单，或者干脆把依赖打包进去。我现在的习惯是每个技能都带一个requirements.txt或package.json，安装时先装依赖再放技能。

7. 几个高频踩坑与排查思路

7.1 技能不触发：从描述到加载逐层排查

技能不触发是最常见的问题。排查时按这个顺序走，基本能定位到原因：

第一层，检查描述文件格式。元信息字段有没有写错？YAML 语法有没有问题（比如冒号后面没空格）？格式错误会导致整个技能加载失败，但报错往往很隐晦。

第二层，检查触发描述。把用户的原话和你的 description 放一起对比，看语义是否匹配。如果用户说"帮我弄个总结"，你写的是"生成周报"，匹配度就低。这时候要把同义词补进去。

第三层，检查加载路径。技能文件夹放对位置了吗？平台配置里有没有把这个目录加进扫描范围？这一步最容易被忽略，因为技能"看起来"放对了，但平台根本没扫到。

第四层，检查技能数量。如果挂了太多技能，模型可能因为选择过载而漏掉某些。这时候要么精简技能，要么加主控技能来调度。

7.2 技能触发了但执行跑偏

执行跑偏通常有三个原因。

指令有歧义。回到 4.3 节说的，把模糊表达改成可验证动作。我一般会做个小测试：把指令念给一个不懂业务的同事听，如果他能准确复述出每一步该干什么，说明指令够清晰。

资源文件缺失或路径错误。技能引用了scripts/foo.py，但文件实际叫foo.py放在了别处。这种问题在本地可能因为路径宽松而不报错，一到严格环境就暴露。

模型"自作主张"。有时候模型会跳过某些步骤，或者自己加戏。这时候要在指令里加约束，比如"必须严格按以下步骤执行，不得跳过或合并步骤"。

7.3 输出格式不稳定的处理

输出格式飘忽是另一个高频问题。同样的技能，这次输出 Markdown 表格，下次输出纯文本列表。

根因通常是格式要求不够具体。光说"输出表格"不够，要说清楚"输出 Markdown 表格，包含三列：日期、事项、状态"。

更稳的做法是提供模板文件。在templates/里放一个样例，指令里写"严格套用 templates/report.md 的格式"。有了具体参照，模型输出的稳定性会大幅提升。

我还会在技能里加一段"输出前自检"：让模型在生成后，对照模板检查一遍格式。这个自检步骤看起来多余，实测能减少不少格式问题。

8. 我对 Agent Skills 这套机制的个人判断

用了大半年 skills，我最大的感受是：它把"提示词工程"从手工作坊推向了工程化。

以前调 AI，靠的是个人经验和反复试错，成果很难沉淀。现在有了 skills，你可以把一次次调好的流程固化成文件，版本管理、复用、协作都成了可能。这对团队来说意义重大——一个资深工程师调好的技能，新人直接装上就能用，不用从头摸索。

但也要泼盆冷水：skills 不是银弹。它擅长的是"有明确流程、需要外部资源"的任务。对于开放式创意、需要大量临场判断的场景，硬做成 skill 反而会限制模型发挥。我见过有人把"写文案"做成 skill，结果输出千篇一律，还不如直接对话。

所以我的建议是：先观察，再固化。一个任务你手动做了三五次，发现流程稳定了，再考虑做成 skill。别一上来就想着"什么都要技能化"，那样只会给自己增加维护负担。

最后分享一个我最近的小发现：技能之间其实可以"互相引用"。比如一个"数据分析"技能里，可以调用"图表生成"技能来出图。这种组合能力，才是 skills 真正有意思的地方——单个技能是积木，组合起来能搭出意想不到的东西。我最近就在尝试用这种方式，把几个零散技能串成一条完整的"周报自动化流水线"，跑通之后确实有种"打开新世界"的感觉。