6700字Skills完全指南,看完你也能写出优秀的Skills
想象你刚入职一家公司。人很聪明,但对业务逻辑、代码规范、文档模板完全陌生。如果有人递给你一本《新员工手册》,里面写着:
代码怎么提交流程
周报怎么写
常见问题怎么处理
你很快就能上手,对吧?Skills 就是 AI 的"员工手册"。
但更准确地说,它不是一张纸,而是一整个文件夹。里面有操作手册,有模板文件,有脚本工具,有参考资料。AI 不需要一次性读完所有内容,而是根据当前任务,按需翻开对应的章节。
这就是 Skills 和普通提示词最大的区别。Skills 不是"加强版提示词"
很多人第一次接触 Skills 时会想:"这不就是把提示词存成文件吗?"
还真不是。这里给大家列了一个对比表格。
总结下来,你可以这么直观的理解:提示词是一张写满规矩的纸,AI 每次都要从头读到尾;Skill 是一个按需查阅的工具箱,AI 只打开当前用得上的那个抽屉。相比提示词的,
以workbuddy为例子(其他的Claude Code等大差不差)一个完整的Skill是一个文件夹,存放在~/.workbuddy/skills/下(用户级)或项目的.workbuddy/skills/下(项目级)。
这是标准的 Skill 目录结构:
my-skill/ ← Skill 根目录(名称用小写+连字符)├── SKILL.md ← ★ 必需,入口文件│├── references/ ← 可选,详细参考文档│ ├── api.md ← API 接口说明│ ├── examples.md ← 示例和用法│ └── faq.md ← 常见问题│├── scripts/ ← 可选,可执行脚本│ ├── setup.sh ← 初始化脚本│ ├── process.py ← 数据处理脚本│ └── generate.js ← 生成工具│├── assets/ ← 可选,模板和静态资源│ ├── template.md ← 输出模板│ ├── config.json ← 配置文件│ └── example-output.html ← 示例产物│├── hooks/ ← 可选,生命周期钩子│ └── HOOK.md│└── sub-module/ ← 可选,子 Skill ├── SKILL.md ├── references/ └── scripts/
每个部分的作用:
SKILL.md:入口文件(必须有)
这是整个 Skill 的"门面"。AI 第一时间只读这个文件。
它要解决的问题只有一个:告诉 AI 这是什么、什么时候用、基本流程是什么、去哪里找更详细的信息。
SKILL.md 应该尽量精简。为什么?因为它每次都会被加载,占用 token。详细内容应该放到 references/ 里,等需要的时候再读。
一个典型的 SKILL.md 长这样:
---name:my-skilldescription:| 简短描述这个 Skill 做什么。 说明触发条件,让 AI 知道什么时候该用它。---# My Skill一句话说明这个Skill解决什么问题。## 核心规则-必须遵守的规则(AI每次执行前都要看)-安全边界和限制条件## 决策表|用户意图|操作|读取||---------|------|------||做事情A|流程A|references/guide-a.md||做事情B|流程B|references/guide-b.md|## 快速参考|场景|处理方式||------|---------||场景1|做某事||场景2|做某事|## 详细参考-完整API说明见`references/api.md`-更多示例见`references/examples.md`
注意这几个要点:
1. description是重中之重。AI 完全靠这段话判断要不要加载这个 Skill。写清楚触发条件比什么都重要。
2. 决策表是路由器。告诉 AI 不同的用户意图应该走哪条路、读哪个文件。
3. 详细参考只放路径,不放内容。这就是渐进式披露的关键:需要的时候再读。
SKILL.md 负责概述和路由,references/ 负责展开细节。
什么时候需要 references/?
- API 接口有很多字段和参数需要说明
- 工作流太长,放在 SKILL.md 里会让入口文件太臃肿
- 有多种变体或分支情况需要分别文档化
在 SKILL.md 里引用 references 的方式很随意,一句详见 references/api.md 就够了。AI 会自动去读取这个文件。
这是提示词做不到的事情。
如果你需要 AI 执行一些自动化操作(调用外部 API、处理数据、生成文件),光靠自然语言描述是不够的。把逻辑写成脚本放到 scripts/ 目录下,SKILL.md 里告诉 AI 怎么调用就行。
## 使用方式### 自动处理(推荐)```bashnode scripts/process.js --input data.json --output result.json
如果你有一些设计规范、比如说logo、vi标准等都可以放在这里,这个就是放一些AI可以复制使用的模板文件、示例输出、配置文件而已。
比如一个"写周报"的 Skill,assets/ 里可以放:
assets/├── weekly-template.md ← 周报模板,AI 读取后按格式填充├── example-report.md ← 一份写得好的周报示例└── team-conventions.md ← 团队的写周报规范
当一个 Skill 覆盖的范围太大时,可以拆分成多个子 Skill,通过 SKILL.md 里的决策表进行路由。
以一…