Cursor Skill 全面培训指南
一、Skill 是什么？
Skill 本质上是一个文件夹，里面放了一组文件，用来"教会" AI Agent 在特定领域执行特定任务。你可以把它理解为给 AI 写的一份岗位培训手册——告诉它"遇到这种情况该怎么做"。
没有 Skill 时，AI 是通用助手；有了 Skill，AI 变成某个领域的专家。
二、Skill文件结构全解析
1. 必要文件 vs 可选文件
skill-name/
├── SKILL.md # ★ 唯一必需文件
├── agents/ # 推荐（Codex 生态用）
│ └── openai.yaml # UI 元数据
├── reference.md # 可选 - 参考文档
├── examples.md # 可选 - 示例
├── scripts/ # 可选 - 可执行脚本
│ ├── validate.py
│ └── helper.sh
├── references/ # 可选 - 参考文档目录
│ ├── api_docs.md
│ └── schema.md
├── assets/ # 可选 - 资产文件
│ ├── logo.png
│ └── template.pptx
└── templates/ # 可选 - 模板（自定义）
2. 各文件/文件夹的作用
| 文件/目录 | 必要性 | 作用 |
|---|---|---|
| SKILL.md | 必需 | Skill 的灵魂文件。包含 YAML frontmatter（name + description）和 Markdown 指令正文 |
| agents/openai.yaml | 推荐 | UI 元数据，给 Codex 产品界面用的（显示名称、描述、图标等），不是给 AI Agent 看的 |
| scripts/ | 可选 | 存放可执行脚本（Python/Bash等），用于确定性操作，比生成代码更可靠 |
| references/ | 可选 | 存放详细参考文档，只在需要时加载，节省 token |
| assets/ | 可选 | 存放模板、图片、字体等不会被加载到上下文中的文件，用于 AI 产出的最终输出 |
| reference.md / examples.md | 可选 | 和 references/ 目录同理，只是用单文件而非目录组织 |
三、相关疑问解答
Q: config.yaml 的写法是规定还是自定义？
在 Cursor Skill 体系中没有 config.yaml 这个标准规定。你看到的可能是：
agents/openai.yaml—— 这是 Codex（OpenAI 的 Agent 产品）定义的规范，用于 UI 展示元数据（显示名称、图标、品牌色等），和 AI 如何执行任务无关。它长这样：
interface:
display_name: "Skill Creator"
short_description: "Create or update a skill"
icon_small: "./assets/small.svg"
icon_large: "./assets/large.png"
brand_color: "#3B82F6"
default_prompt: "Use $skill-name to do something"
- 如果在其他 Skill 框架（非 Cursor）中看到
config.yaml，那是那个框架自己的约定。Cursor Skill 体系中唯一必需的配置在SKILL.md的 YAML frontmatter 里，不需要单独的 config 文件。
Q: SKILL.md 是否可以写成 skill.md？
不可以。 必须是大写的 SKILL.md。系统按这个文件名去识别和加载，大小写敏感。这是硬性规定。
Q: tools/ 文件夹是什么？
tools/ 不是 Cursor Skill 标准目录。如果你在某些 Skill 中看到，那是作者自定义的，通常放的是 MCP 工具配置。标准目录只有 scripts/、references/、assets/，其余你可以自由创建但不会被系统自动识别。
Q: templates/ 文件夹是什么？
同样是自定义目录。有些 Skill 作者把输出模板单独放在 templates/ 里（比如 HTML 模板、代码模板），语义上等同于 assets/ 的子集。你可以用，但不是规定。
Q: .mjs 文件是什么？
.mjs 是 ES Module 格式的 JavaScript 文件（相对于 .cjs 是 CommonJS 格式）。在 Skill 中出现一般是因为：
- 作为可执行脚本放在
scripts/中，用 Node.js 运行 - 实现一些自动化任务（比如文件处理、API 调用）
- 和
.py（Python 脚本）是同等角色，只是语言不同
Q: references/ 文件夹具体放什么？
放需要被 AI 读取理解的文档，但不适合全部塞进 SKILL.md 的内容：
- API 文档
- 数据库 Schema
- 业务规则细则
- 公司政策
- 详细的工作流指南
你项目中的 enum-governance Skill 就是一个例子：reference.md 放了业务线映射规范，examples.md 放了典型输入输出示例。
Q: assets/ 文件夹大概是什么？
放不需要被 AI 读进上下文、但会在最终产出中使用的文件：
- 图标文件（
.png、.svg） - PPT/Word 模板
- 字体文件
- 前端项目脚手架
- 品牌素材
关键区别：references/ 的内容是给 AI "看" 的；assets/ 的内容是给 AI "用" 的（复制、引用到输出中）。
四、Skill 怎么触发？
触发机制
Skill 的触发分两级：
第一级：元数据匹配（始终在上下文中）
- 系统把所有 Skill 的
name+description（大约 100 词）注入到 system prompt - 当你发消息时，AI 根据 description 判断："这个问题和某个 Skill 相关吗？"
- 这就是为什么 description 写得好不好直接决定 Skill 能不能被正确触发
第二级：加载 Skill 正文
- 匹配成功后，AI 读取
SKILL.md的 body 部分 - 根据需要，再进一步读取
references/、scripts/等
触发示例
以你项目的 enum-governance Skill 为例：
description: 中文枚举治理技能。用于后端枚举接入、业务线归属判断、重复定义识别、
前后端完整性对比、硬编码替换建议。默认自动分层检索，只有关键节点确认；未获同意不改代码。
当你说"帮我接入这个后端枚举"或"看看这个枚举有没有重复定义"，AI 会匹配到关键词，触发这个 Skill。
怎样让触发更精准？
- description 中包含触发关键词：把用户可能说的话包含进去
- 明确 WHAT 和 WHEN：不光说做什么，还要说什么场景下用
- 第三人称撰写：description 是注入到 system prompt 中的，不是对话
五、Token 消耗分析
这是你最关心的问题之一。让我用实际数字说明：
Token 消耗层级
Level 1: Skill 元数据（name + description）
≈ 50-200 tokens × N 个 Skill
★ 始终在上下文中，每次对话都消耗
Level 2: SKILL.md body
≈ 1000-5000 tokens
★ 仅在 Skill 触发后加载
Level 3: references/、scripts/ 等
≈ 不定量
★ 仅在 AI 判断需要时按需加载
消耗举例
假设你有 10 个 Skill，每个 description 约 100 tokens：
- 每次对话基础消耗：1000 tokens（仅元数据）
- 触发一个 Skill：+2000-5000 tokens（SKILL.md body）
- 深入使用参考文档：+5000-20000 tokens（references 等）
对比之下，你的 enum-governance Skill 的 SKILL.md 约 375 行，大约 3000-4000 tokens。
六、优化策略——如何做 Balance
做 Skill 时的优化（创作端）
1. SKILL.md 瘦身原则（最重要）
❌ 错误做法：把所有内容都塞进 SKILL.md
✅ 正确做法：核心指令留在 SKILL.md，详细内容拆到 references/
500 行红线：SKILL.md 尽量控制在 500 行以内。超过就要拆分。
2. 渐进式披露（Progressive Disclosure）
这是最核心的优化模式：
# 我的 Skill
## 核心工作流（放在 SKILL.md，始终加载）
1. 做 A
2. 做 B
3. 做 C
## 详细参考（按需加载，不占基础 token）
- API 详情见 [api.md](references/api.md)
- 复杂案例见 [examples.md](examples.md)
AI 只在需要时才去读 references/api.md，不需要时完全不消耗 token。
3. 默认假设 AI 已经很聪明
❌ 冗余：
PDF（Portable Document Format）是一种常见的文件格式，
它包含文本、图片和其他内容。要提取文本，你需要使用一个库...
✅ 简洁：
用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
每个段落都问自己：AI 是否真的需要这个解释？这段话值它的 token 成本吗？
4. 用脚本替代上下文代码
❌ 在 SKILL.md 中写 50 行 Python 代码教 AI 怎么处理 PDF
✅ 把代码放到 scripts/process_pdf.py，SKILL.md 只写一行：
运行: `python scripts/process_pdf.py input.pdf`
脚本可以被执行而不需要加载到上下文中，token 消耗接近零。
5. description 要精准不要冗长
# ❌ 模糊（触发率低，浪费元数据 token）
description: 帮助处理文档
# ✅ 精准（触发率高，每个 token 都有用）
description: 提取PDF文本和表格、填写表单、合并文档。当用户提到PDF文件、
表单填写或文档提取时使用。
用 Skill 时的优化（消费端）
1. 提供足够上下文让 Skill 精准匹配
❌ "帮我处理这个枚举"（模糊，可能触发错误 Skill 或不触发）
✅ "帮我把这个后端枚举接入到 AfterLoan 业务线"（精准匹配 enum-governance）
2. 分层操作，不要一次要求太多
❌ "帮我接入枚举、查重复、对比完整性、替换硬编码、改所有文件"
✅ 分步来：
第1轮："帮我解析这个后端枚举并检查是否已存在"
第2轮："按建议方案执行改动"
3. 利用 Skill 的分层检索设计
以你的 enum-governance Skill 为例，它设计了 L1/L2/L3 三层检索：
- L1/L2 自动执行、低 token
- L3 全仓检索、高 token、需确认
这种设计就是在做 balance：大多数情况用 L1/L2 就够了，只有确实需要时才升级到 L3。
七、Skill vs Rule 的区别
这是很多人混淆的点：
| 对比项 | Skill | Rule |
|---|---|---|
| 文件格式 | SKILL.md（Markdown） | .mdc（Markdown） |
| 存放位置 | .cursor/skills/ 或 ~/.cursor/skills/ | .cursor/rules/ |
| 触发方式 | AI 根据 description 自动判断 | 基于 alwaysApply 或文件 glob 模式 |
| 适合场景 | 复杂工作流、多步骤任务、需要工具/脚本 | 编码规范、简单约定、文件级别模式 |
| 复杂度 | 可以包含脚本、参考文档、资产 | 通常 < 50 行的简单指令 |
| 加载时机 | 按需（先看 description，再加载 body） | 符合条件时始终加载 |
简单原则：
- 如果是"遵循 xxx 规范" → 用 Rule
- 如果是"执行 xxx 工作流" → 用 Skill
八、实战总结——创建 Skill 的最佳实践检查清单
创作阶段：
✅ SKILL.md 文件名大写
✅ YAML frontmatter 包含 name 和 description
✅ description 包含 WHAT（做什么）+ WHEN（何时触发）
✅ description 用第三人称
✅ SKILL.md body < 500 行
✅ 详细内容拆到 references/ 或单独 .md 文件
✅ 引用文件只做一级深度（不嵌套引用）
✅ 术语统一（不混用同义词）
✅ 每段内容都值得它的 token 成本
✅ 可复用逻辑放 scripts/（执行而非加载）
使用阶段：
✅ 提供明确的业务上下文
✅ 使用 Skill description 中的关键词
✅ 分步操作，不一次贪多
✅ 利用 Skill 设计的分层机制
