Claude Skills 基础原理与编写指南
原始问题：Skills 是什么？如何在项目中使用？如何写一个适合自己项目的 Skill？
什么是 Skills？
Skills 是 Claude AI 的模块化扩展机制，用于为 Claude 提供专门的领域知识、工作流程和工具。可以理解为给 Claude 的"技能包"或"上岗指南"——让通用 AI 变成针对特定任务的专家。
Skills 的核心价值
| 能力 | 说明 |
|---|---|
| 专业工作流 | 定义多步骤的领域操作流程 |
| 工具集成 | 提供特定文件格式或 API 的操作指南 |
| 领域知识 | 公司特定的知识、schema、业务逻辑 |
| 资源捆绑 | 脚本、参考文档、模板等资源 |
核心原理
三层渐进加载机制
Skills 使用渐进式加载来高效管理上下文空间：
┌─────────────────────────────────────────────────────────────┐
│ 第1层: Frontmatter (name + description) │
│ ▸ 始终在上下文中 (~100 词) │
│ ▸ 决定是否触发该 Skill │
├─────────────────────────────────────────────────────────────┤
│ 第2层: SKILL.md 正文 │
│ ▸ 触发后才加载 (<5000 词) │
│ ▸ 核心工作流指令 │
├─────────────────────────────────────────────────────────────┤
│ 第3层: 捆绑资源 (scripts/ references/ assets/) │
│ ▸ 按需加载 (无限制) │
│ ▸ 脚本可直接执行，无需读入上下文 │
└─────────────────────────────────────────────────────────────┘
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
自由度匹配原则
根据任务的脆弱程度选择合适的指令形式：
| 自由度 | 形式 | 适用场景 |
|---|---|---|
| 高 | 文字指令 | 多种方案都可行、依赖上下文判断 |
| 中 | 伪代码/带参数脚本 | 有推荐模式、允许少量变化 |
| 低 | 具体脚本 | 操作脆弱易错、需要严格一致性 |
类比：窄桥配护栏（低自由度），开阔地允许多条路（高自由度）
Skill 文件结构
标准目录结构
skill-name/
├── SKILL.md # 必需：定义 + 指令
├── scripts/ # 可选：可执行脚本
│ └── do-something.mjs
├── references/ # 可选：参考文档（按需读取）
│ └── api-docs.md
└── assets/ # 可选：模板、图片（用于输出）
└── template.html
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
资源类型说明
| 目录 | 用途 | 加载时机 |
|---|---|---|
scripts/ | 可执行代码（Python/Bash/Node 等） | 直接执行，无需读入上下文 |
references/ | 参考文档、API 文档、Schema | 按需加载到上下文 |
assets/ | 模板、图片、字体等输出资源 | 用于输出，不加载到上下文 |
SKILL.md 编写指南
基本结构
---
name: my-skill
description: 简洁描述技能功能。当用户说 "xxx"、"yyy" 时触发。
---
# 技能标题
## 触发条件
- "xxx"
- "yyy"
## 工作流程
### 1. 第一步
...
### 2. 第二步
...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Frontmatter 是关键
---
name: my-skill
description: |
[做什么] + [什么时候触发]。
当用户说 "关键词1"、"关键词2"、"关键词3" 时使用此 Skill。
---
1
2
3
4
5
6
2
3
4
5
6
⚠️ description 是唯一的触发依据，必须写清楚所有触发条件！
正文编写原则
- 简洁为王：只写 Claude 不知道的内容
- 命令式语气：用 "执行..."、"创建..."，而非 "你可以..."
- 控制在 500 行以内：超出就拆分到
references/
实战示例
场景分析
假设要创建一个文档归档 Skill：
| 问题 | 回答 |
|---|---|
| 解决什么 | 对话整理成文档是重复劳动 |
| 触发词 | /ai-doc、"整理到知识库" |
| 步骤 | 分析对话 → 匹配分类 → 创建文档 → 更新配置 → git 提交 |
识别可复用资源
| 场景 | 可复用资源 |
|---|---|
| 每次都要更新配置 | scripts/ai-doc.mjs |
| 每次都要查分类定义 | references/knowledge-map.json |
| 每次都要写相同格式文档 | 模板定义在 SKILL.md 中 |
完整 Skill 示例
---
name: interview-manager
description: 管理面试准备知识单元。当用户说 "/interview"、"添加面试知识点"、"更新项目经验" 时触发。
---
# 面试知识管理
## Skill 资源
- `scripts/generate-interview-prep.mjs` - 生成/更新文档
- `references/templates.md` - 三种文档模板
## 触发条件
- `/interview`
- "添加面试知识点"
- "更新项目经验"
## 约束
- **扁平结构**：不允许子目录
- **命名规范**：`project__<slug>.md` / `tech__<slug>.md` / `matrix__<slug>.md`
## 工作流程
### 1. 确定文档类型
| 类型 | 前缀 | 用途 |
| -------- | ----------- | ------------------------ |
| 项目经验 | `project__` | 描述具体项目、职责、成果 |
| 技术深度 | `tech__` | 某技术栈的原理、最佳实践 |
| 对比矩阵 | `matrix__` | 多技术横向对比 |
### 2. 创建文档
根据类型使用对应模板
### 3. 运行验证
\`\`\`bash
node tools/generate-interview-prep.mjs --validate
\`\`\`
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
最佳实践速查
| 做 ✅ | 不做 ❌ |
|---|---|
| 在 description 写清楚所有触发词 | 在正文写 "When to use" |
把大段参考文档放 references/ | 全塞进 SKILL.md |
| 用脚本处理脆弱操作 | 让 AI 每次重写相同代码 |
| 测试脚本能正常运行 | 只写不验证 |
| 删除不需要的示例文件 | 保留空目录和占位文件 |
渐进式内容组织模式
模式 1：高层指南 + 引用
# PDF Processing
## Quick start
[代码示例]
## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
模式 2：按领域分文件
bigquery-skill/
├── SKILL.md (overview)
└── references/
├── finance.md
├── sales.md
└── product.md
1
2
3
4
5
6
2
3
4
5
6
模式 3：条件细节
## Creating documents
Use docx-js for new documents.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
1
2
3
4
5
2
3
4
5
参考
- Anthropic Claude Skills 官方文档open in new window
- 项目 Skills 目录：
.claude/skills/