Agent Skills 创建完全指南：从目录结构到 SKILL.md 的每个细节

如果你用过 Claude Code 或者类似的 AI 编程工具，大概率听说过 Skills 这个东西。但真正动手创建过的人不多，大多数人觉得这是"高级功能"，离自己很远。

其实 Skills 的本质特别简单：就是一个文件夹，里面放了一个叫 SKILL.md 的说明文件。AI 读到这个文件，就知道在什么场景下、按什么步骤、用什么资源来帮你干活。

这篇文章从零开始，把 Skills 的创建方法、目录结构、每个文件的含义全部讲清楚。看完你就能自己写了。

Skills 解决什么问题

先说为什么需要 Skills。

你每次用 AI 做同一类任务——比如代码审查、周报生成、数据清洗——都要重复交代背景、规则、输出格式。说一遍还行，说十遍就烦了。而且你每次说的可能还不一样，导致 AI 的输出不稳定。

Skills 就是把这些重复信息固化下来。写好一次，以后触发技能时 AI 自动加载，不用你再说。

更关键的是，Skills 可以附带脚本、参考文档、模板。AI 不只是读你的指令，还能直接运行你写好的脚本、查阅你准备好的参考资料。这比纯靠提示词强太多了。

两种创建方法

根据技能复杂度，有两种创建方式。

极简版适合 90% 的场景。两步就够了：第一步，创建一个技能文件夹，命名只用小写字母、数字和连字符，比如 code-review 或者 weekly-report。第二步，在文件夹里创建一个 SKILL.md 文件，写清楚元数据和指令。完事。

标准版适合需要脚本、模板、参考文档的复杂技能。六步：确定技能场景并创建根文件夹，编写 SKILL.md 核心文件，按需创建 scripts、references、assets 等目录并补充内容，在 SKILL.md 中关联这些资源，把技能文件夹放到 .claude/skills 目录下，测试触发并迭代优化。

注意，不管哪种方式，SKILL.md 是唯一必需的文件。其他目录都是可选的，根据实际需要加。

标准目录结构

极简版结构就一个文件：my-skill 文件夹里放一个 SKILL.md。

标准版结构是这样的。my-skill 是根文件夹，里面有 SKILL.md（必需），还有三个可选目录：scripts 放可执行脚本（Python、Shell 等），references 放详细参考文档（业务规则、API 说明），assets 放静态资源（模板、图片、数据文件）。

所有结构遵循 Anthropic 开源标准，Claude Code、Cursor 等工具都支持。

SKILL.md 逐字段解析

SKILL.md 分两部分：YAML 头部元数据（两个三横线之间）和 Markdown 正文指令。

YAML 头部是 AI 启动时加载的，决定技能是否触发。大约 100 个 token，不占太多上下文。

第一个字段 name，必填，技能唯一标识，与根文件夹名一致，64 字符以内，只用小写字母、数字和连字符。

第二个字段 description，必填，写清楚技能作用和触发条件，1024 字符以内。这是 AI 判断是否触发这个技能的依据，所以要写明白"用户说什么话时应该用这个技能"。

第三个字段 license，可选，技能的开源许可证。

第四个字段 compatibility，可选，运行环境要求，比如 Python 3.10 以上。

第五个字段 metadata，可选，扩展信息，比如作者、版本号。

Markdown 正文是 AI 触发技能时才加载的，建议控制在 5000 个 token 以内。正文没有强制格式，但有几个建议模块。

第一个模块"什么时候使用"，最关键，明确 AI 触发技能的场景，避免误判或漏判。比如"当用户让你审查代码、检查代码质量、review PR 时使用本技能"。

第二个模块"具体步骤"，一步一步的操作指南，用数字列表呈现。写得越小白越好，因为 AI 不会脑补你省略的步骤。

第三个模块"输出格式"，规范 AI 的输出样式。比如用分点、用符号标记通过项和建议改进项。

第四个模块"可用资源"，关联 scripts、references、assets 中的内容。比如"运行脚本：python scripts/check.py"。

第五个模块"注意事项"，边界情况、常见错误。比如"不允许空 catch 块"。

三个可选目录的含义

scripts 目录放可执行脚本。AI 可以在虚拟环境中直接运行，替代临时写代码，提升效率和准确性。要求是脚本需写清依赖、有清晰的参数说明和错误处理。比如一个数据清洗脚本，顶部标注依赖包列表。

references 目录放详细参考文档。AI 按需加载，不触发不加载，节省上下文。适合长文本内容，比如公司代码规范、API 文档。单个文件专注一个主题，超过 100 行的文件加目录。

assets 目录放静态资源。AI 可直接调用，适合技能所需的模板、图片、数据文件等。比如周报模板、品牌 Logo、CSV 查找表。

三级渐进加载逻辑

这是 Skills 设计里很聪明的地方。

第一级，AI 启动时只加载所有技能的 YAML 元数据（name 和 description），用来判断哪个技能该被触发。

第二级，触发技能后才加载 SKILL.md 的正文指令。没触发的技能，正文不加载，不占上下文。

第三级，执行过程中按需读取 scripts、references、assets 中的具体文件。用到哪个读哪个，不用不读。

这意味着你可以同时安装几十个技能，不会因为装得多就拖慢 AI 的速度。只有真正用到的才消耗资源。

一个核心原则

写 SKILL.md 记住一句话：只告诉 AI 它不知道的内容。

Python 语法不需要写，常见库的使用方法不需要写，通用的编程规范不需要写。AI 比你熟。

你需要写的是公司内部的代码规范、你的项目特有的目录结构、你个人的写作风格偏好、你团队的业务规则——这些是 AI 不可能自己知道的。

这个原则用熟了，Skills 的体积会很小，但效果会很好。

最后

Skills 不是什么高深的东西，就是一个结构化的"使用说明"。但正是这种结构化，让 AI 从"靠猜"变成了"按章办事"。

我自己的经验是，花 10 分钟创建一个 Skill，能省下以后几十次的重复交代。特别是代码审查、周报生成这类重复性高的任务，Skills 的投入产出比非常高。