Agent Skill 最佳实践：写给 AI 的「操作手册」该怎么写
Skill 是什么
Skill 最早由 Anthropic 在 Claude Skills 规范中提出，后来被 Qoder、Claude Code 等多个 AI Coding Agent 采纳，逐步成为社区通用的能力扩展模式。简单说，Skill 是你给 AI 写的一份「操作手册」。当用户的请求匹配到某个 Skill 时，Agent 会把这份手册注入到上下文中，让 AI 按照你定义的规范和流程来执行任务。
Skill 跟 Agent 不一样：Agent 是一个独立的执行体，有自己的目标和工具集；Skill 更像是「给 AI 加了一段专业记忆」，在合适的场景被自动唤起。Skill 跟 Hook 也不同：Hook 是事件驱动的自动化脚本，Skill 是知识驱动的行为引导。
为什么要自己写 Skill？通用模型不了解你团队的规范、你项目的约定、你踩过的坑。把这些写成 Skill，AI 就能按你的标准干活。
命名这件小事
这是写第一个 Skill 时最容易踩的坑。
很多人会自然地用下划线命名，比如 api_standard_check。但社区规范要求 Skill 名称必须是 kebab-case：
- 只能用小写字母、数字和连字符（
-）
- 不能有下划线、空格、大写字母
- 不能包含
claude 或 anthropic 这类保留词（不同 Agent 的保留词清单略有差异，但避免使用厂商名是通用做法）
更重要的一点：name 字段必须和文件夹名完全一致。如果文件夹叫 api-standard-check，那 SKILL.md 里的 name 也必须是 api-standard-check，一个字符都不能差。
# 正确
api-standard-check/
└── SKILL.md → name: api-standard-check
# 错误：下划线
api_standard_check/
└── SKILL.md → name: api_standard_check ← 加载失败
# 错误：名称不匹配
api-check/
└── SKILL.md → name: api-standard-check ← 加载失败
少数 Agent 平台支持以 zip 包形式上传 Skill（不是按目录路径加载），这种场景下文件夹名和 name 字段可以不一致。但 name 字段本身的字符规则没有差异——无论本地、社区还是云端，都是 kebab-case，不能有下划线。
目录结构极简版
一个 Skill 最少只需要一个文件：
my-skill/
└── SKILL.md ← 唯一必须的文件
需要的时候可以加：
my-skill/
├── SKILL.md # 主文件，入口
├── examples.md # 详细示例（避免主文件太长）
├── reference.md # 参考规范
└── scripts/ # 可执行脚本
└── validate.sh
建议是：先只写 SKILL.md，等内容多到影响阅读了再拆分。过早拆分反而增加维护成本。
SKILL.md 怎么写才好用
Frontmatter：两个字段就够
---
name: api-standard-check
description: |
检查 API 接口是否符合团队规范。当用户新增、修改 API 接口，
或提到 RESTful 规范、接口命名、请求响应格式时使用。
---
name 没什么好说的，跟文件夹同名。重点在 description。
Description 里埋触发词
Description 不是给人看的文档说明——它是 AI 用来判断「要不要激活这个 Skill」的依据。所以你要在里面埋入触发关键词。
# 不好：太笼统，AI 不知道什么时候该触发
description: API 相关的检查工具
# 好：列出了具体的触发场景和关键词
description: |
检查 API 接口是否符合团队规范。当用户新增、修改或删除 API 接口，
提到 RESTful 规范、接口命名、请求响应格式、HTTP 方法选择、
状态码使用时触发。
注意 description 有 1024 字符的上限（这是 Claude Skills 规范的限制，多数兼容平台沿用），超了会被截断。不需要面面俱到，抓住核心触发场景就行。
Body 推荐的章节组合
看了十几个写得好的 Skill 后，可以总结出一个比较通用的章节模板：
## 适用场景
（什么时候用，什么时候不用）
## 核心流程
（1-2-3 步骤，用 checkbox）
## 关键约束
（必须遵守的硬规则）
## 常见错误
（正反示例对比）
## 校验清单
（完成前的自检项）
不需要全写，根据 Skill 的复杂度取舍。简单的 Skill 可能只需要「流程 + 约束」就够了。
几个实用技巧
用 checkbox task list 让 AI 按步骤执行
这是最有用的技巧之一。AI 在执行多步任务时容易跳步或遗漏，给它一个 checkbox 列表效果非常好：
## 执行流程
- [ ] 检查接口 URL 是否符合 RESTful 命名
- [ ] 验证 HTTP 方法是否正确（GET 查询、POST 创建...）
- [ ] 确认请求/响应 Body 的 JSON 字段命名风格为 camelCase
- [ ] 检查错误码是否在团队错误码表中注册
- [ ] 生成检查报告
AI 会逐项完成，不会漏掉。
正反示例比文字描述有效 10 倍
与其写一段话解释规则，不如直接给正反示例：
## 接口命名规范
❌ 错误：
- `GET /getUserInfo` — 不要用动词
- `POST /api/v1/delete-user` — 方法和 URL 语义冲突
✅ 正确：
- `GET /users/{id}` — 资源名词 + 路径参数
- `DELETE /users/{id}` — HTTP 方法表达操作意图AI 对这种格式的理解和执行效果远好于纯文字规则。
内容太多就拆 companion files
当 SKILL.md 超过 5000 词，就该考虑拆分了。把详细的参考资料和扩展示例放到单独的文件：
<!-- 在 SKILL.md 中引用 -->
详细的 JSON Schema 定义见 [reference.md](./reference.md)。
更多示例见 [examples.md](./examples.md)。
主文件保持精炼，让 AI 快速抓住核心；需要细节时再加载 companion files。
踩过的坑
改了 Skill 必须重启 session
这个坑容易反复踩。修改了 SKILL.md 的内容后，当前会话通常不会自动重新加载（不同 Agent 的缓存策略略有差异，但稳妥起见都应当假设需要重启）。开一个新的 session 才能看到效果。调试的时候特别容易忘记这一点，然后以为自己的修改没生效。
Description 超长被静默截断
没有报错，没有警告，就是不触发。后来发现是 description 写太长被截断了，截断后的内容丢失了关键触发词。控制在 1024 字符以内，宁可精简也不要超。
触发词不精确导致误匹配
写过一个 Skill 的 description 里包含「代码检查」，结果用户随便提一句「帮我检查一下这段代码」就触发了，完全不是预期的场景。
解决办法：触发词要具体到业务场景，而不是泛泛的动作词。比如用「API 接口规范检查」而不是「代码检查」。
流程写得太抽象，AI 不知道怎么执行
早期写的流程类似「检查代码质量」「确保符合规范」，AI 每次执行的方式都不一样，结果不稳定。
后来改成具体的、可操作的步骤，效果好很多：
- 不好：「检查代码质量」
- 好：「运行 eslint --fix，确认无 error 级别告警」
最后
写 Skill 本质上是在给 AI 写 SOP（标准作业程序）。你的团队有什么重复性的规范检查、有什么容易出错的流程、有什么新人经常踩的坑——这些都是好的 Skill 素材。
写好一个 Skill 不需要很长，但需要够具体。与其写一个大而全的万能 Skill，不如写几个小而精的专项 Skill，各司其职。
Agent Skill 最佳实践：写给 AI 的「操作手册」该怎么写
Skill 是什么
Skill 最早由 Anthropic 在 Claude Skills 规范中提出，后来被 Qoder、Claude Code 等多个 AI Coding Agent 采纳，逐步成为社区通用的能力扩展模式。简单说，Skill 是你给 AI 写的一份「操作手册」。当用户的请求匹配到某个 Skill 时，Agent 会把这份手册注入到上下文中，让 AI 按照你定义的规范和流程来执行任务。
Skill 跟 Agent 不一样：Agent 是一个独立的执行体，有自己的目标和工具集；Skill 更像是「给 AI 加了一段专业记忆」，在合适的场景被自动唤起。Skill 跟 Hook 也不同：Hook 是事件驱动的自动化脚本，Skill 是知识驱动的行为引导。
为什么要自己写 Skill？通用模型不了解你团队的规范、你项目的约定、你踩过的坑。把这些写成 Skill，AI 就能按你的标准干活。
命名这件小事
这是写第一个 Skill 时最容易踩的坑。
很多人会自然地用下划线命名，比如
api_standard_check。但社区规范要求 Skill 名称必须是 kebab-case：-）claude或anthropic这类保留词（不同 Agent 的保留词清单略有差异，但避免使用厂商名是通用做法）更重要的一点：
name字段必须和文件夹名完全一致。如果文件夹叫api-standard-check，那 SKILL.md 里的 name 也必须是api-standard-check，一个字符都不能差。少数 Agent 平台支持以 zip 包形式上传 Skill（不是按目录路径加载），这种场景下文件夹名和 name 字段可以不一致。但
name字段本身的字符规则没有差异——无论本地、社区还是云端，都是 kebab-case，不能有下划线。目录结构极简版
一个 Skill 最少只需要一个文件：
需要的时候可以加：
建议是：先只写 SKILL.md，等内容多到影响阅读了再拆分。过早拆分反而增加维护成本。
SKILL.md 怎么写才好用
Frontmatter：两个字段就够
name没什么好说的，跟文件夹同名。重点在description。Description 里埋触发词
Description 不是给人看的文档说明——它是 AI 用来判断「要不要激活这个 Skill」的依据。所以你要在里面埋入触发关键词。
注意 description 有 1024 字符的上限（这是 Claude Skills 规范的限制，多数兼容平台沿用），超了会被截断。不需要面面俱到，抓住核心触发场景就行。
Body 推荐的章节组合
看了十几个写得好的 Skill 后，可以总结出一个比较通用的章节模板：
不需要全写，根据 Skill 的复杂度取舍。简单的 Skill 可能只需要「流程 + 约束」就够了。
几个实用技巧
用 checkbox task list 让 AI 按步骤执行
这是最有用的技巧之一。AI 在执行多步任务时容易跳步或遗漏，给它一个 checkbox 列表效果非常好：
AI 会逐项完成，不会漏掉。
正反示例比文字描述有效 10 倍
与其写一段话解释规则，不如直接给正反示例：
AI 对这种格式的理解和执行效果远好于纯文字规则。
内容太多就拆 companion files
当 SKILL.md 超过 5000 词，就该考虑拆分了。把详细的参考资料和扩展示例放到单独的文件：
主文件保持精炼，让 AI 快速抓住核心；需要细节时再加载 companion files。
踩过的坑
改了 Skill 必须重启 session
这个坑容易反复踩。修改了 SKILL.md 的内容后，当前会话通常不会自动重新加载（不同 Agent 的缓存策略略有差异，但稳妥起见都应当假设需要重启）。开一个新的 session 才能看到效果。调试的时候特别容易忘记这一点，然后以为自己的修改没生效。
Description 超长被静默截断
没有报错，没有警告，就是不触发。后来发现是 description 写太长被截断了，截断后的内容丢失了关键触发词。控制在 1024 字符以内，宁可精简也不要超。
触发词不精确导致误匹配
写过一个 Skill 的 description 里包含「代码检查」，结果用户随便提一句「帮我检查一下这段代码」就触发了，完全不是预期的场景。
解决办法：触发词要具体到业务场景，而不是泛泛的动作词。比如用「API 接口规范检查」而不是「代码检查」。
流程写得太抽象，AI 不知道怎么执行
早期写的流程类似「检查代码质量」「确保符合规范」，AI 每次执行的方式都不一样，结果不稳定。
后来改成具体的、可操作的步骤，效果好很多：
最后
写 Skill 本质上是在给 AI 写 SOP（标准作业程序）。你的团队有什么重复性的规范检查、有什么容易出错的流程、有什么新人经常踩的坑——这些都是好的 Skill 素材。
写好一个 Skill 不需要很长，但需要够具体。与其写一个大而全的万能 Skill，不如写几个小而精的专项 Skill，各司其职。