6700字Skills完全指南,看完你也能写出优秀的Skills

01
什么是Skills

想象你刚入职一家公司。人很聪明,但对业务逻辑、代码规范、文档模板完全陌生。如果有人递给你一本《新员工手册》,里面写着:

  • 代码怎么提交流程

  • 周报怎么写

  • 常见问题怎么处理

你很快就能上手,对吧?Skills 就是 AI 的"员工手册"。

但更准确地说,它不是一张纸,而是一整个文件夹。里面有操作手册,有模板文件,有脚本工具,有参考资料。AI 不需要一次性读完所有内容,而是根据当前任务,按需翻开对应的章节。

这就是 Skills 和普通提示词最大的区别。Skills 不是"加强版提示词"

很多人第一次接触 Skills 时会想:"这不就是把提示词存成文件吗?"

还真不是。这里给大家列了一个对比表格。

总结下来,你可以这么直观的理解:提示词是一张写满规矩的纸,AI 每次都要从头读到尾;Skill 是一个按需查阅的工具箱,AI 只打开当前用得上的那个抽屉。相比提示词的,


02
Skill 的目录结构

以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/

每个部分的作用:



AI助力金融产品创新设计

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. 详细参考只放路径,不放内容。这就是渐进式披露的关键:需要的时候再读。




references/: 详细参考文件

SKILL.md 负责概述和路由,references/ 负责展开细节。

什么时候需要 references/?

- API 接口有很多字段和参数需要说明

- 工作流太长,放在 SKILL.md 里会让入口文件太臃肿

- 有多种变体或分支情况需要分别文档化

在 SKILL.md 里引用 references 的方式很随意,一句详见 references/api.md 就够了。AI 会自动去读取这个文件。




scripts/: 可执行脚本

这是提示词做不到的事情。

如果你需要 AI 执行一些自动化操作(调用外部 API、处理数据、生成文件),光靠自然语言描述是不够的。把逻辑写成脚本放到 scripts/ 目录下,SKILL.md 里告诉 AI 怎么调用就行。

## 使用方式### 自动处理(推荐)```bashnode scripts/process.js --input data.json --output result.json




assets/: 模板和资源

如果你有一些设计规范、比如说logo、vi标准等都可以放在这里,这个就是放一些AI可以复制使用的模板文件、示例输出、配置文件而已。

比如一个"写周报"的 Skill,assets/ 里可以放:

assets/├── weekly-template.md   ← 周报模板,AI 读取后按格式填充├── example-report.md    ← 一份写得好的周报示例└── team-conventions.md  ← 团队的写周报规范


03
子Skill:模块化组合

当一个 Skill 覆盖的范围太大时,可以拆分成多个子 Skill,通过 SKILL.md 里的决策表进行路由。

以一…

— 以上为试看内容(约 40%),开通会员后阅读全文 —