格式规范
了解 SKILL.md 的格式规范，有助于编写更高质量、更易触发的 Skills。本页面介绍 Skills 的工作原理和编写技巧。
Skills 工作原理
渐进式披露
Skills 采用三级加载系统来高效管理上下文，确保 Claude 既能快速响应，又能在需要时获取深度知识。
┌─────────────────────────────────────────────────────────┐
│ 第一级: 元数据 (始终在上下文中) │
│ ├── name + description (~100 词) │
│ └── 用于判断是否触发 Skill │
├─────────────────────────────────────────────────────────┤
│ 第二级: SKILL.md 正文 (当 Skill 被触发时) │
│ ├── 核心指令 (5k 词以内) │
│ └── 程序化知识和工作流 │
├─────────────────────────────────────────────────────────┤
│ 第三级: 打包资源 (按需加载) │
│ ├── scripts/ - 可执行代码 │
│ ├── references/ - 详细文档 │
│ └── assets/ - 模板、图片等 │
└─────────────────────────────────────────────────────────┘这个设计的优势：
| 层级 | 加载时机 | 上下文消耗 | 内容类型 |
|---|---|---|---|
| 元数据 | 始终加载 | ~100 词 | 名称、触发描述 |
| SKILL.md 正文 | 触发时加载 | 5k 词以内 | 核心指令 |
| 打包资源 | 按需加载 | 无限制 | 详细文档、脚本 |
触发机制
Claude 会根据 description 字段判断是否触发 Skill：
- 用户发送消息
- Claude 分析消息内容，与所有启用 Skill 的 description 匹配
- 匹配成功则加载 SKILL.md 正文
- 执行任务时按需加载 references/scripts/assets
Skill 目录结构
每个 Skill 由一个必需的 SKILL.md 文件和可选的资源目录组成：
skill-name/
├── SKILL.md # 必需：核心指令文件
├── references/ # 可选：详细参考文档
│ ├── patterns.md
│ └── api-docs.md
├── scripts/ # 可选：可执行脚本
│ ├── validate.py
│ └── generate.sh
└── assets/ # 可选：模板和资产
├── template.html
└── logo.png各目录用途
| 目录 | 用途 | 何时使用 |
|---|---|---|
references/ | 详细文档，按需加载到上下文 | 需要大量参考资料时 |
scripts/ | 可执行代码，可直接运行 | 需要确定性操作时 |
assets/ | 模板和资产，用于输出 | 需要复用模板时 |
SKILL.md 格式
SKILL.md 文件使用 YAML frontmatter 定义元数据，Markdown 编写正文。
基本结构
---
name: my-skill
description: This skill should be used when the user asks to
"specific phrase 1", "specific phrase 2", or needs help with
specific task type.
---
# Skill 标题
简要描述这个 Skill 的功能和使用场景。
## 核心指南
详细的操作指南和知识...
## 使用方法
具体的使用步骤...
## 资源引用
如果有 references/scripts/assets，在这里说明如何使用。必填字段
| 字段 | 说明 | 限制 |
|---|---|---|
name | Skill 标识符，用于显示和引用 | 最多 64 字符 |
description | 功能描述和触发条件 | 最多 200 字符 |
编写技巧
编写有效的 description
description 决定了 Skill 何时被触发，是最关键的字段。
✅ 好的示例：
description: This skill should be used when the user asks to
"create a dashboard", "build a landing page", "design a form",
or needs help with frontend development using React or Vue.关键要素：
- 使用第三人称: "This skill should be used when..."
- 包含具体的触发短语（用引号括起）
- 描述越具体，触发越准确
❌ 不好的示例：
description: Helps with frontend stuff.问题：
- 太模糊，难以准确触发
- 没有具体的触发短语
- 不是第三人称
编写 SKILL.md 正文
正文是 Skill 的核心内容，提供给 Claude 的具体指令和知识。
写作风格：
- 使用祈使句形式（动词开头）
- 直接、清晰、可操作
- 避免使用 "you should..."，改用 "Do X" 或 "X should be done"
✅ 正确：
Parse the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.❌ 错误：
You should parse the configuration file.
You need to validate the input.
Claude can use the grep tool.内容组织：
- 保持精简，理想 1,500-2,000 词
- 核心内容放在 SKILL.md
- 详细内容移至
references/目录
使用资源文件
何时使用 references/：
- 详细的 API 文档
- 完整的模式参考
- 高级技术指南
- 边缘情况处理
在 SKILL.md 中引用：
## 详细参考
完整的 API 文档请查看 `references/api-docs.md`。何时使用 scripts/：
- 需要确定性执行的操作
- 重复性任务的自动化
- 验证和检查脚本
何时使用 assets/：
- 项目模板
- 配置文件模板
- 图片、图标资源
示例结构
简单 Skill
只包含核心指令，适合编码规范、写作风格等。
coding-style/
└── SKILL.mdSKILL.md 内容示例：
---
name: coding-style
description: This skill should be used when the user asks about
"code style", "naming conventions", "best practices" for
TypeScript or JavaScript development.
---
# 代码风格指南
## 命名规范
- 变量使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 类名使用 PascalCase
## 文件组织
- 每个文件只导出一个主要内容
- 相关工具函数放在同一目录
...标准 Skill
包含参考文档，适合需要详细知识的场景。
api-integration/
├── SKILL.md
└── references/
├── endpoints.md
└── error-codes.md完整 Skill
包含所有类型的资源，适合复杂领域。
project-generator/
├── SKILL.md
├── references/
│ ├── architecture.md
│ └── best-practices.md
├── scripts/
│ └── validate-structure.py
└── assets/
├── template/
│ ├── src/
│ └── package.json
└── config-templates/验证清单
创建 Skill 后，检查以下要点：
Skill 验证清单
-
SKILL.md有有效的 YAML frontmatter -
name和description字段存在且有效 - description 使用第三人称并包含触发短语
- 正文使用祈使句形式
- SKILL.md 少于 3,000 词
- 所有引用的文件都存在
- references/scripts/assets 组织合理