想象你刚入职一家公司。人很聪明，但对业务逻辑、代码规范、文档模板完全陌生。如果有人递给你一本《新员工手册》，里面写着：
代码怎么提交流程
周报怎么写
常见问题怎么处理
你很快就能上手，对吧？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 里的决策表进行路由。
以一个"腾讯 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，根本不会碰知识库模块的内容。
这是 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。
编写 SKILL.md 时，你需要把它当成两部分来对待：顶部的文件头（Frontmatter）负责告诉系统“什么时候唤醒我”，下方的正文结构负责告诉 AI“唤醒后具体怎么做”。
文件头位于文档最顶端，使用 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`
把所有内容塞进 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
