想让 AI 干活时按你的规矩来、别总自作主张？给它写个 Skill 就行。这篇全程大白话：它是啥、怎么写、放哪儿、最容易踩哪些坑，看完照着做就能上手。
1. 什么是 Skill
一句话：Skill 就是给 AI 的一份“照着做”的说明书，装在一个文件夹里。
AI 再聪明，也有两件事它天生不知道：
你们公司的规矩、内部叫法、接口怎么调；
某一类活到底按什么顺序干。
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. 写之前记住三句话
能短则短。AI 的“脑子”（上下文窗口）是有限的，还一堆人抢着用。它已经很聪明了，你只补它不知道的。每句话写完问问自己：这句有用吗？
容易出错的事写死，可以发挥的事别管。比如处理文件格式这种错一步就完蛋的，直接给脚本、给死步骤；像写文案这种没标准答案的，给个方向就行，别写一堆死规矩。
分开放。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. 动手三步走
建文件夹：新建
image-optimizer/，把第 6 节的示例存成SKILL.md，改成你自己的任务；放对位置：放进第 8 节表格里对应的目录；
重启再测：多数工具不会自动认新 Skill，要重启工具或新开一个会话，然后扔个真实任务试试。没被触发，回去改 description。
另外：写了脚本就真跑一遍，别写完就当能用。
10. 新手最容易踩的坑
⭐（最高发）description 写得抽象，Skill 永远不被调用。“处理文档的技能”这种写法，AI 压根不知道什么时候该用它。
⭐（最高发）把“什么时候用”写进正文，没写进 description。正文它还没看呢，白写。
细节全堆 SKILL.md。几百行全塞正文，AI 光读就累死。该拆 references 就拆。
三个目录建了全留。没用的示例文件删掉，目录清爽。
命名不合规。大写、空格、中文，校验直接报错。
塞 README、CHANGELOG。多余，只添乱。
放好不重启就测。白测，新 Skill 不会自动生效。
