想让 AI 干活时按你的规矩来、别总自作主张？给它写个 Skill 就行。这篇全程大白话：它是啥、怎么写、放哪儿、最容易踩哪些坑，看完照着做就能上手。

1. 什么是 Skill

一句话：Skill 就是给 AI 的一份“照着做”的说明书，装在一个文件夹里。

AI 再聪明，也有两件事它天生不知道：

1. 你们公司的规矩、内部叫法、接口怎么调；

2. 某一类活到底按什么顺序干。

Skill 就是把这两类“怎么做”写下来。AI 遇到对应的活儿，自己会翻这份说明书照着做。

打个比方：AI 是刚入职的新人，Skill 就是给他的岗位手册。没手册，他只能瞎猜。

---

2. 一个 Skill 长啥样

就是一个普通文件夹：

skill-name/
├── SKILL.md          # 唯一的必需品，说明书本体
├── scripts/          # 脚本（可选）
├── references/       # 参考资料（可选）
└── assets/           # 素材模板（可选）

记一点就行：只有 SKILL.md 必须有

---

3. SKILL.md 里最要紧的：description

SKILL.md 开头被 --- 包住的两行，叫 frontmatter：

---
name: my-skill
description: 处理某某事的技能。当用户需要……时使用。
---
​
# My Skill
​
正文从这里开始……

name 和 description 两个字段必填。

description 是整份 Skill 的命根子。 AI 平时只读它这一句，觉得“这活我能干”，才会去翻正文。所以：

• 写清楚“干什么”和“什么时候用”；

• “什么时候用”必须写在 description 里，别只写进正文——正文它还没看呢。

• 小写字母加连字符，比如 pdf-helper、csv-validator。别用大写、空格、中文；

• name 必须和文件夹名一模一样。两处不一致，部分平台直接识别不到。

Agent命中Skill示意图：

---

4. 正文怎么写

正文是 AI 被触发之后才看的。这时候它只想要一件事：接下来一步步怎么干。

最省事的写法，先给个流程总览，再一步步拆：

填写一份 PDF 表单，按这个顺序走：
​
1. 分析表单结构（运行 analyze_form.py）
2. 建立字段映射（编辑 fields.json）
3. 校验映射（运行 validate_fields.py）
4. 填表（运行 fill_form.py）
5. 检查输出（运行 verify_output.py）

要是任务会分岔，把判断条件写明：

1. 先判断：
   - 新建内容？→ 走下面的“新建流程”
   - 改旧内容？→ 走“编辑流程”
​
2. 新建流程：……
3. 编辑流程：……

核心就一条：别让 AI 猜该走哪条路。

---

5. scripts / references / assets 用不用？

一句话：用得上就留，用不上就删。

• scripts/：每次都得做、结果必须稳定的活，写成脚本。好处是省事——脚本不用读进“脑子”就能跑。

• references/：细节多、用的时候才需要看的资料，放这儿。SKILL.md 里留一句“用到某功能时去看某某文件”就行。

• assets/：干活要用的模板、图片、字体，直接拿。

---

6. 完整的例子

下面是一个完整的 SKILL.md，拿“批量压缩图片”举例——这个例子 scripts、references、assets 三个子目录全用上了，是一个完整 Skill 的标准长相：

---
name: image-optimizer
description: 批量压缩图片，控制大小和格式。当用户上传多张图片，或提到“图片太大”“压一下图”“批量压缩”时使用。
---
​
# 图片批量压缩
​
## 流程
​
1. 先看 assets/config.json 里的默认参数（目标格式、最大宽度、质量）
2. 批量压缩：python scripts/compress.py <图片目录> --config assets/config.json
3. 校验大小：python scripts/check_size.py <输出目录>，确认没有超限的
4. 汇总：输出对比表（文件名、原大小、新大小、省了多少）
​
## 规矩
​
- 不改原图，压缩结果输出到 <图片目录>/compressed/。
- 参数拿不准先看 references/params.md，别自己乱设。
- 单张超过 5MB，先提醒用户再动手。

对照着看：description 写了“干什么 + 什么时候用”；正文只有流程和规矩；能自动跑的都丢给 scripts，参数说明放 references，默认配置放 assets——三个子目录各有各的活儿，这才是完整 Skill 的标配（第 5 节那句“用不上就删”，这里就是“都用得上所以都留”）。

配套的目录长这样（正文里点到的文件，目录里都真有）：

image-optimizer/
├── SKILL.md                       # 上面这份
├── scripts/
│   ├── compress.py                # 批量压缩（第 2 步用）
│   └── check_size.py              # 校验大小（第 3 步用）
├── references/
│   └── params.md                  # 各参数怎么选、常见坑
└── assets/
    └── config.json                # 默认压缩参数

---

7. 写之前记住三句话

1. 能短则短。 AI 的“脑子”（上下文窗口）是有限的，还一堆人抢着用。它已经很聪明了，你只补它不知道的。每句话写完问问自己：这句有用吗？

2. 容易出错的事写死，可以发挥的事别管。 比如处理文件格式这种错一步就完蛋的，直接给脚本、给死步骤；像写文案这种没标准答案的，给个方向就行，别写一堆死规矩。

3. 分开放。 SKILL.md 只写主干。各平台对长度的硬限制不一样（有按字数算的、有按字节算的），别卡着上限写；经验值是正文几百行封顶，细节扔 references，用到才读。

---

8. 写好的 Skill 放哪儿？

写完放对地方才被识别。位置分两种：

• 个人级：放在你电脑的用户目录下，所有项目都能用；

• 项目级：放在某个项目/仓库里，只有这个项目能用，还能通过 git 跟队友共享。

各家主流智能体的默认目录（~ 指用户主目录，Windows 上一般是 C:\Users\你的用户名）：

智能体	个人级（全局）	项目级（仓库内）
Claude Code	~/.claude/skills/	.claude/skills/
OpenAI Codex	~/.codex/skills/（新版也读 ~/.agents/skills/）	.codex/skills/ 或 .agents/skills/
Gemini CLI	~/.gemini/skills/ 或 ~/.agents/skills/	.gemini/skills/ 或 .agents/skills/
GitHub Copilot / VS Code	~/.copilot/skills/ 或 ~/.agents/skills/	.github/skills/ 或 .agents/skills/
OpenCode	~/.config/opencode/skills/	.opencode/skills/ 或 .agents/skills/
Qwen Code（通义灵码 CLI）	~/.qwen/skills/	.qwen/skills/

豆包这类国内平台不走这套，Skill 放各自工作区目录（比如 workspace/.user_skills），以你平台文档为准。

拿不准放哪儿？优先选 .agents/skills/，多数工具都认它（Claude Code 是例外，只认自己的 .claude/skills/）。

---

9. 动手三步走

1. 建文件夹：新建 image-optimizer/，把第 6 节的示例存成 SKILL.md，改成你自己的任务；

2. 放对位置：放进第 8 节表格里对应的目录；

3. 重启再测：多数工具不会自动认新 Skill，要重启工具或新开一个会话，然后扔个真实任务试试。没被触发，回去改 description。

另外：写了脚本就真跑一遍，别写完就当能用。

---

10. 新手最容易踩的坑

1. ⭐（最高发） description 写得抽象，Skill 永远不被调用。 “处理文档的技能”这种写法，AI 压根不知道什么时候该用它。

2. ⭐（最高发） 把“什么时候用”写进正文，没写进 description。 正文它还没看呢，白写。

3. 细节全堆 SKILL.md。 几百行全塞正文，AI 光读就累死。该拆 references 就拆。

4. 三个目录建了全留。 没用的示例文件删掉，目录清爽。

5. 命名不合规。 大写、空格、中文，校验直接报错。

6. 塞 README、CHANGELOG。 多余，只添乱。

7. 放好不重启就测。 白测，新 Skill 不会自动生效。