SKILL.md 文件格式完整指南

SKILL.md 文件是每个 Claude Skill 的核心。掌握其格式以创建专业、可靠的技能。

文件结构

根据 Anthropic 官方 Skills 仓库，SKILL.md 文件使用 YAML frontmatter：


markdown
1---
2name: my-skill-name
3description: 清晰描述这个技能的功能和使用场景
4---
5
6# 我的技能名称
7
8[在此添加 Claude 在此技能激活时将遵循的指令]
9
10## 示例
11- 使用示例 1
12- 使用示例 2
13
14## 指南
15- 指南 1
16- 指南 2
1---
2name: my-skill-name
3description: 清晰描述这个技能的功能和使用场景
4---
5
6# 我的技能名称
7
8[在此添加 Claude 在此技能激活时将遵循的指令]
9
10## 示例
11- 使用示例 1
12- 使用示例 2
13
14## 指南
15- 指南 1
16- 指南 2

Frontmatter（必填）

顶部的 YAML frontmatter 仅需要两个字段：

name: 技能的唯一标识符（小写，空格用连字符）
description: 完整描述技能的功能和使用时机

示例:


yaml
---
name: pdf-extractor
description: 从 PDF 文档中提取文本、表格和表单数据以进行分析和处理
---
---
name: pdf-extractor
description: 从 PDF 文档中提取文本、表格和表单数据以进行分析和处理
---

指令部分

编写清晰、可操作的步骤：


markdown
1## 指令
2处理文档时:
31. 验证输入格式
42. 提取内容部分
53. 应用转换
64. 验证输出
75. 返回结构化数据
1## 指令
2处理文档时:
31. 验证输入格式
42. 提取内容部分
53. 应用转换
64. 验证输出
75. 返回结构化数据

最佳实践:

使用编号列表表示序列
包括决策点（"如果 X，则 Y"）
定义预期输入/输出
指定错误条件

使用示例

提供具体示例：


markdown
1## 使用示例
2
3### 示例 1: 基础处理
4**输入**: document.pdf
5**输出**: {"text": "...", "pages": 5}
6
7### 示例 2: 带选项
8**输入**: document.pdf, {"extract_images": true}
9**输出**: {"text": "...", "images": [...]}
1## 使用示例
2
3### 示例 1: 基础处理
4**输入**: document.pdf
5**输出**: {"text": "...", "pages": 5}
6
7### 示例 2: 带选项
8**输入**: document.pdf, {"extract_images": true}
9**输出**: {"text": "...", "images": [...]}

依赖

列出所有要求：


markdown
1## 依赖
2- Python: >= 3.8
3- PyPDF2: >= 3.0.0
4- pdfplumber: >= 0.9.0
5
6安装：
7```bash
8pip install PyPDF2 pdfplumber
1## 依赖
2- Python: >= 3.8
3- PyPDF2: >= 3.0.0
4- pdfplumber: >= 0.9.0
5
6安装：
7```bash
8pip install PyPDF2 pdfplumber


## 高级功能

### 条件逻辑

```markdown
如果文档加密:
1. 请求密码
2. 解密内容
3. 继续提取
否则:
- 直接处理

常见错误

❌ 模糊指令: "处理文件" ✅ 清晰指令: "从第 1-10 页提取文本"

❌ 缺少错误处理: 无失败案例 ✅ 完整错误处理: 指定所有错误场景

验证清单

[ ] 所有元数据字段存在
[ ] 指令编号且清晰
[ ] 至少提供 2 个使用示例
[ ] 列出依赖及版本
[ ] 记录错误处理
[ ] 注明安全考虑

阅读时间：4分钟

作者: ClaudeSkills 团队