Agent Skills全解析：从原理到实战，打造高效技能包

这两年“Agent”这个词都快被聊烂了，但真正把 Agent 从玩具变成生产力的，不是某个大模型又聪明了多少，而是那些藏在一个个目录里的skills。如果你正在做 agent 开发、前端开发 skills，或者只是好奇 Codex、Claude 那些 Agent 为什么突然变得这么能干，那这一篇就是给你准备的——我会把 agent-skills 是什么、原理是什么、怎么亲手写一个靠谱的 skill、踩过哪些坑，一次性讲明白。

先说一句真心话：Agent 的能力上限，一半在模型，一半在 skills。模型决定它多聪明，skills 决定它多专业。没有 skills 的 Agent 就像一个高学历但零经验的新人，什么都懂一点，什么都做不精。而一份打磨过的 skill，等于给 Agent 配备了某个领域十年老师傅的手感。这东西值得你花时间。

1. Agent Skills 到底是个什么东西

1.1 从一次教到会，到“装上就会”

先说概念。Agent Skills 本质上是一套结构化的能力包，由一份指令文档（通常是 Markdown）加上可选的脚本、模板、参考文件组成，用来教 Agent 如何完成一类特定任务。它不是代码插件，也不是微调模型，而是一种“施工图纸”——模型负责执行，skill 负责告诉它按什么流程、用什么工具、按什么标准去执行。

我最早接触这个思路其实是在 2023 年底，那时候很多项目开始尝试用零样本提示词让大模型干杂活，效果起起伏伏，用户怨声载道。为什么？因为提示词写得再详细，在大模型眼里也只是“建议”，根本没有约束力。模型判断错了，没有代码去兜底；流程漏了，也没有机制去补全。而 skills 的发明，本质上就是把这些“建议”升级成了一套有步骤、有标准、有产出物约束的迷你工作流。

举一个最直观的例子：你让 Agent 帮你画流程图，它可能画得乱七八糟，线条乱飞，节点名都是英文缩写。但如果你给它装一个“分镜 skills”或者“流程绘制 skills”，它会先确认目标，再列出分镜节点，最后按固定模板生成结构化的输出。连命名规范都会遵守。这不是大模型变强了，是 skill 替你把流程锁死了。

1.2 为什么 2025 年 skills 突然爆火

一个技术能火，必须踩中痛点。Agent Skills 在近期集中爆发，三个原因缺一不可：

1. 大模型太通用，生产环境太具体。ChatGPT 级别的对话能力已经过剩了，但生产环境要求的是“按我们公司的代码规范写 PR 描述”“按我们的配置文件格式生成部署脚本”，这种场景化知识没法靠模型预训练解决，只能靠 skill 注入。

2. Agent 框架的成熟让 skills 成为标准件。现在 Claude Agent Skills、Codex skills、HERMES agent、各种 agent 框架都开始支持 skills 标准化，这意味着你写一份高质量的 skill，可以在多个 Agent 环境之间复用，生态一下子打开了。

3. 社区驱动的技能市场行为逐渐成形。如今像 GitHub skills、skills 下载平台、官方技能市场都已经出现，大量开发者开始互相分享和复用技能。一个技能写得好的作者，就相当于当年 GitHub 上 star 过万的开源作者，影响力非常大。任何技术生态，只要开始有“交易”和“复用”，就会指数级增长。

1.3 skills 能解决什么问题

如果你现在还在纠结“要不要学 skills”，先看这三个问题是不是也困扰你：

• 同一个任务，每次都要从头教一遍 Agent。今天让它写周报，明天让它生成 SQL，后天又要它写测试用例。每次都要重新写一大段提示词，烦不烦？skill 就是把这些固定套路打包，一次安装终身受用。
• Agent 输出的质量不稳定。同样的需求，十个字和一千字描述出来的结果天差地别。skill 把关键约束写死在文档里，Agent 每次执行都按照同一套质量标准来，偏差大幅缩小。
• 团队协作时知识无法沉淀。公司里某个大神写了一段极其好用的 prompt，他怎么写的？不知道。但如果是 skill，整个目录提交到代码库，所有人 clone 下来就能用。经验，第一次变成了可积累、可审计的数字资产。

注意：skills 不是银弹。它解决的是“流程标准化”和“知识复用”问题，解决不了模型本身能力不足的问题。如果模型连基础推理都做不对，再精细的 skill 也救不回来。

2. Skills、Tools、MCP 和 Prompt：一张图理清边界

这四者的关系可能是近期 Agent 开发领域被问得最多的问题。很多人把 skills 和 tools 混为一谈，还有人觉得 MCP 就是 skills 的替代品。我在这里用一整章讲透，因为这个问题不搞清楚，后面开发时你连选型都会纠结。

2.1 一句话版本

• Prompt（提示词）：一次性口头交代，说完就忘，灵活但无约束。
• Skills（技能包）：长期记忆+操作手册，装在 Agent 脑子里，固定流程+质量标准。
• Tools（工具）：Agent 的手和脚，让它能执行具体动作，比如执行代码、查文件、调 API。
• MCP（模型上下文协议）：统一插座标准，让 Agent 能即插即用地连接外面的数据源和工具服务，解决的是“接入”问题，不是“怎么用”的问题。

2.2 它们怎么配合

我打个比方帮助理解。假设你要开一家奶茶店：

• Prompt 就是店长早上跟你说的“今天生意做得好一点”，方向有，怎么落地全看悟性。
• Skills 是你的《门店操作手册》，从泡茶步骤、糖浆配比到出杯时长全部写明白，店员照着做就不会太差。
• Tools 是你店里的设备：封口机、收银机、制冰机，没有这些，手册写得再好也没办法落地。
• MCP 是统一的电源和水管接口标准，让任何品牌的设备都能插上就用，不用每家店重新铺水电。

这下清楚了吧？Skills 是大脑里的方法论，Tools 是手上的工具，MCP 是基础设施标准。

2.3 为什么 skills 和 tools 的边界最容易被混淆

因为很多 skill 内部也会调用 tools。比如一个“前端开发 skills”，它会引导 Agent 去读目录结构、执行 npm 命令、检查 lint 输出，这时候 skill 和 tool 就一起出现了。我的判断标准很简单：tools 回答“能做什么”，skills 回答“该怎么做”。如果你的 Agent 只是挂了一堆 tools 但没有 skills，它就像一个进了工具间的新手，什么都会用，但完全不知道先干什么后干什么。真实项目中，90% 的 Agent 效果不佳，问题就出在只挂了 tools，没装 skills。

3. 动手开发一个自己的 Skill：从 0 到 1 全流程

前面讲了这么多概念，现在该上硬货了。我会带你从零开始写一个真正能用的 skill，并且把每一步的设计思路都讲清楚。为什么讲得细？因为我见过太多人看了一堆 skill 教程，结果自己上手写的时候，连 frontmatter 该写几行都拿不准。

3.1 第一步：选一个合适的任务场景

选择任务是 skill 开发中最关键的一步，也是最容易被忽视的一步。判断一个任务适不适合做成 skill，我会用三把尺子：

1. 重复性够不够高？如果这个事情你就干一次，不要写 skill，直接写 prompt。
2. 流程够不够稳定？如果任务每次的需求变化极大，skill 难以覆盖住那些不确定部分，反而不如 prompt 灵活。
3. 质量标准能否描述？你得能找到“好结果”和“坏结果”之间的分界线，比如“输出必须包含数据表头”“代码必须有错误处理”，否则 Agent 学不会。

我的第一个实操 skill 选了“生成 SQL 查询语句”。为什么选它？因为团队里每天都有分析同事来问“这个数据怎么查”，需求高度重复，SQL 的写法有章可循，而且质量标准极其明确——能跑、性能好、字段对得上表结构。

3.2 第二步：搭好 SKILL.md 的标准骨架

一个 skill 的灵魂是它的SKILL.md文件。这个文件决定了 Agent 看到什么、按什么顺序思考、按什么标准交付。我推荐的骨架分成四块：

--- name: sql_query_generator description: 生成符合 MySQL 8.0 规范的高性能查询语句。仅当用户需要从数据库提取数据时使用。 version: 1.0.0 ---

四个字段我逐个解释：

• name：技能的名字，短横线分隔，小写。它会被 Agent 用于索引路径，不要用中文，也不要有空格。
• description：这个字段极其重要。Agent 判断什么时候该调用这个 skill，靠的就是这段描述。写得太泛（“生成 SQL”），它会在不该用的时候也调用；写得太窄（“从订单表查询销售额”），它会在该用的时候错过。
• version：版本号，一定要写。后续 skill 迭代时，版本号能帮你回溯问题。
• 正文：frontmatter 下面就是主体内容。写法和写操作手册完全一样，关键步骤用数字编号，关键约束用加粗强调，产出物要求单独成节。

3.3 第三步：把流程写细，但不是写死

写 SKILL.md 正文最容易犯的两个错误，一个是太粗——只有几句泛泛的原则，Agent 看完还是不知道怎么下手；另一个是太死——要求每个字段都按固定模板填，一点灵活性都不留，结果任务一变，Agent 直接宕机。

我的经验是分三层来写：

第一层：任务分析。让 Agent 先判断输入是什么、要什么结果、有没有隐性的约束（比如时间范围、数据量级）。

第二层：执行步骤。给出一套流程，但每个步骤之间留出判断空间。比如“先检查表结构，再生成查询，最后确认索引利用情况”。这只是顺序，不是模板。

第三层：质量红线。这是和 prompt 最不一样的地方。我会明确写“禁止 SELECT *，必须显式列出字段”“涉及多表 join 时必须确认关联字段有索引”。这些话是给 Agent 的“工作纪律”，也是产出质量的基本保障。

3.4 实操案例：完整写一个“JSON Schema 生成器”skill

为了让你能直接参考，我把一个实际跑通过的 skill 完整写出来。这个 skill 的作用是：根据用户的一段 JSON 示例数据，自动生成符合 JSON Schema Draft 2020-12 规范的 schema 文件。

--- name: json_schema_generator description: 根据 JSON 示例数据自动生成 JSON Schema（Draft 2020-12）。当用户提供 JSON 并要求生成校验规则、接口文档或表单配置时使用。 version: 1.2.0 --- # JSON Schema 生成器 ## 任务目标 根据用户提供的 JSON 示例，生成结构完整、类型严格、可扩展的 JSON Schema 文件。 ## 执行步骤 1. 分析示例 JSON 的数据结构，列出所有字段及嵌套层级。 2. 为每个字段确定类型（string/number/boolean/array/object/null）。 3. 根据字段值特征补充约束规则： - 字符串字段：若疑似枚举值，补充 enum - 数字字段：根据业务场景判断是否需要 minimum/maximum - 数组字段：明确 items 类型，若元素为对象则递归生成 4. 对可选字段使用 required 数组显式列出必填项。 5. 输出完整 JSON Schema，并以 JSON 代码块返回。 ## 质量红线 - 所有类型必须显式声明，禁止依赖默认类型推断。 - required 数组里只放业务上必填的字段，宁少勿多。 - 数组嵌套超过三层时，必须拆分引用（$ref），禁止直接展开。 - 输出文件必须通过 JSON 语法校验。

你写完这个文件之后，把它放在skills/json_schema_generator/SKILL.md路径下，你的 Agent 框架只要能识别 skills 目录，就能自动索引到这个能力。等下一次你丢给它一段宠物商店数据，它就会转换成一份规整的 schema，连$ref都安排得明明白白。

3.5 命名规范与目录结构

skill 的目录结构我建议固定为：

skills/ └── json_schema_generator/ ├── SKILL.md ├── templates/ │ └── schema_template.json └── examples/ └── sample_input_output.md

分两个子目录是有讲究的。templates放可复用的模板文件，比如输出格式的骨架；examples放 few-shot 示例，让 Agent 在执行时有范例可以参照。实际测试下来，有 examples 的 skill 比没有的，首轮成功率能高出 30% 以上，因为大模型看一遍示例比读十条规则有效得多。

提示：templates 里的文件不要放太多，两三个足够。放多了反而会干扰 Agent 的判断，它不知道该参考哪个。

4. 从 Claude Skills 到 Codex Skills：多平台迁移实战

写 skill 只是一半工作，让它跑起来、在不同 Agent 平台上复用，才是价值兑现的时候。目前我实际用过的有三类环境，分别是 Claude Agent Skills、Codex skills，以及 HERMES agent 这类第三方工作台。我直接把兼容细节讲清楚。

4.1 Claude Skills 的运行机制

Claude 的 skills 机制是目前做得最完整的。它的实现逻辑是：Agent 启动时会扫描 skills 目录，读取每个子目录下的 SKILL.md，把文件名和 description 注入上下文索引。当用户提问命中描述时，Agent 才会加载对应 skill 的完整正文，开始执行。

这个“按需加载”的设计非常关键，它保证哪怕你装了五十个 skills，上下文窗口也不会被一次性塞爆。只有需要时才会读取具体内容，代价是响应时多一轮内部检索，但换来的是极高的扩展性。这一点为我们在前端开发 skills、测试技能这类细分场景自由安装大量技能集提供了很好的前提。

4.2 Codex 环境的适配

Codex 的 skills 命名和 Claude 略有差异，但结构基本一致。迁移时最容易踩的坑有两个：

1. frontmatter 字段名差异。Codex 某些版本对description的敏感程度不同，迁移前先跑一次skills list确认识别情况。
2. 命令类 skill 的权限设置不同。Codex 更强调沙箱执行，涉及 shell 命令的 skill 需要显式声明权限级别。我通常会在文档里加一段“执行环境要求”，用注释形式标出哪些步骤需要管理员权限。

迁移前一天内能搞定两个平台，得益于 skill 本身的纯文本属性。它是跨平台的，这是提示词复用永远做不到的。

4.3 第三方工作台和自建 Agent 框架

除了官方那几家，像 HERMES agent 这类第三方工作台也在做 skills 标准化。说句实在的，这类平台的 skill 兼容性参差不齐，有的支持完整 frontmatter，有的只读正文第一段。我在开发时会在 SKILL.md 里加一个metadata.json作为辅助，把技能名、版本、依赖信息各写一份，这样就算主文档某个字段解析失败了，也能靠它兜底识别。

针对自建 Agent 框架（比如基于 Rust 的 agent 项目，或者自己搭的多 agent 架构），我的建议是封装一个skill loader 组件：启动时统一扫描 skills 目录、解析 frontmatter、建立索引，并让 Agent 在每轮对话前查询该索引。这套方案我实测过，非常稳定，而且把 skills 的加载机制彻底从框架中解耦了出来。后面不管是接入官方能力还是第三方能力，都只改 loader 这一层就行。

注意：无论你用的是哪家的 Agent，都别同时加载太多技能。我之前一次性装了三十多个 skills，结果 Agent 每次都要花时间在索引里大海捞针，响应速度肉眼可见地变慢。一般控制在 10 个以内体验最佳。

5. 避坑实录：我踩过的那些 skills 开发深坑

再好的教程，也比不上真实的坑够味。这一章整理的都来自我和身边朋友实战中的血泪教训，部分已经凝成了团队的开发规范。你直接拿去看，能少走一大截弯路。

5.1 描述写得太“完美”，Agent 反而学不会

我早期写过一个“自动化测试生成”skill，description 写得很漂亮：“为任何前端项目自动生成完整测试套件”。听起来无所不能，实际用起来惨不忍睹——Agent 经常在只需要改一个测试文件的时候，兴奋地跑去生成整个项目的测试方案。

原因很简单：描述越宽泛，触发的机会就越频繁，误用的概率就越大。后来我改成“当用户要求为指定组件或页面编写/补充 Vitest 测试用例时使用”，触发准确率立刻从 60% 升到 95%，效果拔群。写 description 的时候，我的建议是把自己当成一个客服分流员：这句话得能让 Agent 精确判断，到底该不该接这单活儿。

5.2 步骤越多，失败率越高

这是个直觉反直觉的发现。六个步骤以内的 skill，执行成功率最高；超过十个步骤的，成功率呈现下跌，原因在于中间任何一步出错，后面全部白搭。

后期我把长 skill 拆成多个子技能，效果立竿见影。比如“数据库迁移”skill 拆成“schema 检查”“SQL 生成”“迁移后校验”三个子技能，每个技能只负责一段流程，加上相互依赖关系，整体成功率反而更高。这就是最近架构圈常说的“harness 和 agent 分离”思路在 skill 层面的体现——主流程负责编排，子技能负责执行，两边都不至于超载。

5.3 一个不知道从哪来的 agent 脚本技能，差点删光文件

这个坑我一定要单独讲，因为它涉及的是 agent 安全。有一次我从一个论坛下载了一个“自动化文件整理”skill，压缩包解压后是一个带脚本的技能，按照说明安装后，打算让它整理下载文件夹。结果执行到一半我隐约发现不对劲，它开始尝试执行rm相关命令，并且遍历范围远超出它该管的那几个目录。

我当时第一时间就中断了执行，然后把那个技能整个卸载并删了。原因是它里面伪装了一个post_install.sh脚本，里面写的命令完全不是整理文件该干的事。这次之后我给自己定了几条铁规矩：

• 只用官方渠道或可信来源的 skills，比如官方能力市场、GitHub 高星项目、或者同事审过代码的目录。
• 安装后先读源代码，再运行。skill 本质是明文的，花五分钟看一遍脚本，不亏。
• 在独立环境先做测试。用假的测试目录跑一遍，确认行为完全符合预期，再放到真实环境中。
• 定期检查 Agent 的执行日志，关注有没有越权操作。我熟悉的一些框架都支持限制技能使用范围，我会把高风险技能配置为“每次使用前都要二次确认”。

这些动作不复杂，但能挡住绝大多数风险。Agent 能力越强，越要管住它的权限边界。

5.4 版本管理与回滚

skills 是文本，但它更是代码。我见过太多人改了一个 skill 就把原来的内容覆盖了，效果不对也找不到原因，只能凭记忆回退。我现在的做法是：每个 skill 目录都纳入 Git 管理，每一次修改都有 commit，SKILL.md 里的 version 字段配套递增。发现问题时先git log看历史，再决定是修复还是回滚。这种方式既省心又防呆。

6. 常用技能框架、搜索与发现效率技巧

写到这里基本已经把核心玩明白了，再把怎么找技能、怎么评估技能质量、怎么高效用起来这部分补上，你就真的算入门了。

6.1 去哪里找现成的高质量 skills

现在的生态比两年前好太多。重点推荐几个可靠来源：

• 官方市场与官方文档：比如 Claude Skill Marketplace、各类框架自带的 skills 仓库，来源可控，质量在线。
• GitHub 高星项目：搜索agent skills、skills collection之类的关键词，看 stars、看更新时间、看 issue 反馈。我下载前习惯先看 3 个 issue，能暴露大量问题。
• 社区整理的精选列表：有些作者会专门做技能评测，整理出“好用不坑”的推荐清单，参考价值很高。
• 自建私有技能库：公司内部积累的经验级技能，尤其是贴合甲方规范、业务术语的这些，是核心竞争力所在，值得沉淀。

6.2 三个维度快速评估一个 skill 的质量

下载前别急着安装，用这三条过一遍：

1. 看体量：SKILL.md 超过 300 行的不要直接用，大概率是又长又啰嗦的“百科全书”，装进去会挤占上下文。
2. 看描述：> 如果 description 用了“万能、全自动、零配置”这类话术，这个技能基本不可信，真正的技能反而会写清楚“什么时候用它”。
3. 看示例：好的技能一定有 examples，没有示例文档的技能，Agent 执行效率至少减半。

这三个条件都满足，才值得花五分钟仔细读一遍正文。

7. 写在最后：我的折与悟

折腾了这么久的 agent skills，我最大的感受就一句话：AI 时代，最值钱的不是写提示词的能力，而是把经验固化成可复用资产的能力。一个 skill 文档，本质上就是你把一双干了十年某领域的手，装进了一个新员工的脑子里。这件事的想象空间，比大多数人以为的大得多。

再分享一个我自己还在用的小技巧：我会把每周工作中重复做过两次以上的事情记录下来，攒一个月就翻出来看。如果某类事情重复超过五次，我就会考虑把它写成 skill。这个习惯坚持半年，我的技能库从 3 个涨到了 17 个。现在很多日常工作都进入了“Agent 主跑、我复核”的状态，效率的提升完全是另一个量级的。

这篇文章写到这儿，我没有打算用一个漂亮的排比句收尾。你可以现在就打开电脑，创建一个空目录，写一个最基础的 SKILL.md，哪怕它只解决“自动生成周报”这一件小事。装进你的 Agent，体验一次“装上就会”的感觉。然后你会明白，为什么我说，skills 是 Agent 真正从玩具变成工具的分水岭。