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

想提升AI工作效率？这篇6700字指南帮你彻底搞懂Skills，告别低效提示词，让AI成为你的高效伙伴。核心内容：1. Skills与普通提示词的本质区别2. 标准Skill的目录结构与核心组件3. Skills在实际项目中的部署与应用技巧

01什么是Skills

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

代码怎么提交流程周报怎么写常见问题怎么处理

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

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

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

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

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

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

02Skill 的目录结构

以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 里的决策表进行路由。

以一个"腾讯 IMA 助手" Skill 为例：

腾讯ima/├── SKILL.md               ← 主入口，包含模块决策表├── ima_api.cjs            ← 共享的 API 调用脚本│├── notes/                 ← 子 Skill：笔记模块│   ├── SKILL.md│   └── references/│       └── api.md│└── knowledge-base/        ← 子 Skill：知识库模块    ├── SKILL.md    └── references/        └── api.md

主 SKILL.md 里的决策表长这样：

|用户意图|路由到|读取||---------|--------|------||搜索笔记、创建笔记|notes模块|`notes/SKILL.md`||上传文件、搜索知识库|knowledge-base模块|`knowledge-base/SKILL.md`|

用户说"帮我搜一下知识库里关于 AI 的文章"，AI读主 SKILL.md，命中决策表第二行，然后才去加载knowledge-base/SKILL.md。

用户说"新建一篇笔记"，AI只加载notes/SKILL.md，根本不会碰知识库模块的内容。

04渐进式披露和按需加载

这是 Skills 和提示词的本质区别，值得单独讲透。

假设你有一个很长的提示词，里面包含：

- 角色设定（200 字）

- 写作规范（500 字）

- 排版要求（300 字）

- API 调用说明（800 字）

- 3 种不同场景的处理流程（1200 字）

- 常见问题 FAQ（400 字）

总计 3400 字。每次跟 AI 对话，这 3400 字都会被塞进上下文，占用 token。

问题是：用户这次可能只是想让 AI搜一下笔记，根本用不上写作规范、排版要求、API 调用说明。但你还是全量加载了。

Skills就很好的解决了这个问题。Skills 把内容拆成多层，一层一层按需加载：

第 1 层（始终加载）：SKILL.md

  - 300 字：角色设定 + 决策表 + 路由规则

  - 包含指向第 2 层的引用路径

    │

    ├─→ 第 2 层（按需加载）：references/ 下的具体文档

    │   - 只有当前任务需要的才读

    │   - 比如"写文章"时才加载 references/writing-guide.md

    │

    ├─→ 第 2 层（按需调用）：scripts/ 下的脚本

    │   - 需要执行自动化时才调用

    │   - 比如"生成报告"时才运行 scripts/generate.py

    │

    └─→ 第 2 层（按需路由）：子 Skill

        - 根据用户意图只加载对应的子模块

        - 比如"搜知识库"时只加载 knowledge-base/SKILL.md

用一个实际案例来说，假设这是一个内容创作助手skill。

content-assistant/├── SKILL.md        ← 300 字，始终加载│   - 角色设定│   - 决策表：写文章→references/writing.md                做图→references/design.md                排版→references/format.md│├── references/│   ├── writing.md    ← 800 字，只在写文章时加载│   ├── design.md     ← 600 字，只在做图时加载│   ├── format.md     ← 400 字，只在排版时加载│   └── seo.md       ← 500 字，只在做 SEO 优化时加载│└── scripts/    └── publish.py     ← 只在发布时调用

用户不同的指令，对应的消耗如下：

| 用户说的 | AI 实际加载的内容 | 消耗的 token ||---------|------------------|-------------|| "帮我写一篇关于 AI 的文章" | SKILL.md + references/writing.md | ~1100 字 || "帮这张图加个标题" | SKILL.md + references/design.md | ~900 字 || "帮我排版一下这篇文章" | SKILL.md + references/format.md | ~700 字 || "帮我写文章并做 SEO 优化" | SKILL.md + references/writing.md + references/seo.md | ~1600 字 |

如果用提示词（全量加载），不管用户说什么都要消耗 3000+ 字。这就是渐进式披露的意义：只加载当前任务需要的那部分知识，剩下的留在磁盘上，不占 token。

05SKILL.md写作规范：从触发到执行

编写 SKILL.md 时，你需要把它当成两部分来对待：顶部的文件头（Frontmatter）负责告诉系统“什么时候唤醒我”，下方的正文结构负责告诉 AI“唤醒后具体怎么做”。

文件头Frontmatter

文件头位于文档最顶端，使用 YAML 格式（被 --- 包裹）。它不是用来写具体任务指令的，而是用来定义这个 Skill 的身份和触发条件。

---name:skill-name      ←必需，唯一标识符，建议用小写+连字符description:|  这是整个 Skill 的灵魂。  用一到两句话说明 Skill 的用途和触发条件。  AI 完全依赖这段话来判断当前任务是否要加载这个 Skill。homepage:https://example.com  ←可选，相关主页---

其中最重要的description怎么写？

记住一个原则：要有清晰的场景和触发词，避免假大空。 很多时候 Skill 不生效，就是因为 description 写得太模糊。

❌ description: "一个帮助处理视频内容的工具。"

✅ description: "短视频内容处理专家。当用户要求撰写短视频口播稿、拆解分镜脚本，或者提到 4-4-2 内容分发逻辑时使用。触发词：写脚本、改文案、短视频结构。"

✨ 进阶写法（划定边界，防止误触发）：description: | 专注于 B2B 短视频逻辑的内容企划工具。 当用户需要构建信任感、规划视频矩阵时触发。 注意：如果是普通的纯娱乐向搞笑视频，请勿触发此 skill。

正文结构

当系统通过文件头成功触发了该 Skill，接下来 AI 就会阅读正文。

正文不需要长篇大论，它应该像一个交通枢纽，把核心的规矩立好，然后把复杂的任务指派给对应的子文件。一个逻辑清晰、对 AI 极其友好的 SKILL.md 正文，通常包含以下四个标准模块：

# Skill 标题用一句话简单概括当前激活的这个角色或工具库是什么。## 1. 核心规则（Rules）**这是 AI 每次执行前必读的“铁律”。**- 规定语气和输出格式（例：必须输出严格的 JSON 结构，或采用特定的版式）。- 规定安全边界（例：绝对不要虚构数据，遇到缺失信息必须向用户提问）。## 2. 决策表（Routing Table）**这是整个渐进式披露的核心。让 AI 根据不同意图，去按需查阅资料。**| 用户意图 / 场景 | 执行动作 | 需要读取的外部参考 ||--------------|--------|----------------|| 需要写分镜脚本 | 提取核心卖点并分镜 | 读取 `references/script-template.md` || 需要进行画面重组 | 调用特定代码或工具 | 执行 `scripts/split-tool.js` || 仅需文案润色 | 套用特定的排版风格 | 查阅 `assets/style-guide.json` |## 3. 基础工作流（Workflow）**给出处理通用任务的简要宏观步骤，避免 AI 像无头苍蝇一样乱撞。**1. 步骤一：先理解用户提供的原始素材。2. 步骤二：根据决策表，读取对应的参考文件或模板。3. 步骤三：生成初稿，并自行核对核心规则。## 4. 详细参考资源（References）**将所有具体的细节剥离出去，只在这里留存路径。**- API 调用参数详见：`references/api.md`- 优秀的输出范例详见：`references/examples.md`

06写SKILL.md的常见错误

把所有内容塞进 SKILL.md，需要理解SKILL.md 应该是目录和索引，不是百科全书。详细内容放 references/。

# 坏例子：SKILL.md 写了 8000 字---name: my-skill---（8000 字的详细文档，包含 API 说明、示例代码、FAQ...）

没有决策表，让 AI 自己判断读哪个文件AI 不知道 references/ 下有哪些文件、哪个文件对应什么场景。要么直接在 SKILL.md 里写清楚，要么用表格列出。

# 坏例子：没有路由指引详细说明请看 references/ 下的文件。

description 太短，导致误触发或不触发。AI 完全不知道什么时候该用这个 Skill。

# 坏例子description: "helpful tool"

#skills

登录查看剩余 70% 内容