想让 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 里最要紧的descriptionSKILL.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 不会自动生效。