Claude Skills 最佳实践

遵循行业最佳实践构建可靠、可维护的 Claude Skills。

1. 清晰命名

✅ 好: pdf-invoice-extractor ❌ 差: skill1, my_cool_skill

使用描述性的、URL 友好的名称来指示用途。

2. 详细指令


markdown
1## 指令
2提取发票数据时:
31. 验证 PDF 格式（如果损坏则拒绝）
42. 仅从前 3 页提取文本
53. 解析字段: invoice_number, date, amount, vendor
64. 如果字段缺失，返回 null（不要猜测）
75. 验证金额是数字
86. 返回 JSON 对象
1## 指令
2提取发票数据时:
31. 验证 PDF 格式（如果损坏则拒绝）
42. 仅从前 3 页提取文本
53. 解析字段: invoice_number, date, amount, vendor
64. 如果字段缺失，返回 null（不要猜测）
75. 验证金额是数字
86. 返回 JSON 对象

明确每个步骤、边缘情况和验证。

3. 全面示例

提供多种场景：


markdown
1### 示例 1: 标准发票
2**输入**: standard_invoice.pdf
3**输出**: {"invoice_number": "INV-001", ...}
4
5### 示例 2: 多页发票
6**输入**: long_invoice.pdf
7**输出**: {"invoice_number": "INV-002", ...}
8
9### 示例 3: 损坏文件
10**输入**: broken.pdf
11**输出**: {"error": "Invalid PDF format"}
1### 示例 1: 标准发票
2**输入**: standard_invoice.pdf
3**输出**: {"invoice_number": "INV-001", ...}
4
5### 示例 2: 多页发票
6**输入**: long_invoice.pdf
7**输出**: {"invoice_number": "INV-002", ...}
8
9### 示例 3: 损坏文件
10**输入**: broken.pdf
11**输出**: {"error": "Invalid PDF format"}

4. 错误处理

定义所有失败模式：


markdown
## 错误处理
- 无效文件格式 → 返回 {"error": "Invalid format"}
- 缺少必填字段 → 返回包含 null 的部分数据
- 处理超时 → 返回 {"error": "Timeout"}
- 权限拒绝 → 返回 {"error": "Access denied"}
## 错误处理
- 无效文件格式 → 返回 {"error": "Invalid format"}
- 缺少必填字段 → 返回包含 null 的部分数据
- 处理超时 → 返回 {"error": "Timeout"}
- 权限拒绝 → 返回 {"error": "Access denied"}

5. 版本控制

使用语义化版本：

1.0.0 - 初始发布
1.1.0 - 新功能添加
1.1.1 - Bug 修复
2.0.0 - 重大变更

6. 安全性


markdown
## 安全性
- 输入验证: 始终验证文件类型
- 沙箱: 在隔离环境中运行脚本
- 秘密: 永不硬编码 API 密钥
- 权限: 请求最少必要访问权限
## 安全性
- 输入验证: 始终验证文件类型
- 沙箱: 在隔离环境中运行脚本
- 秘密: 永不硬编码 API 密钥
- 权限: 请求最少必要访问权限

7. 性能

缓存昂贵的操作
流式处理大文件，不要加载到内存
设置执行超时
优化依赖（使用轻量级库）

8. 测试

彻底测试你的技能：


python
1def test_pdf_extraction():
2    # 测试有效输入
3    result = extract_invoice("test.pdf")
4    assert result["invoice_number"] is not None
5
6    # 测试无效输入
7    result = extract_invoice("broken.pdf")
8    assert "error" in result
1def test_pdf_extraction():
2    # 测试有效输入
3    result = extract_invoice("test.pdf")
4    assert result["invoice_number"] is not None
5
6    # 测试无效输入
7    result = extract_invoice("broken.pdf")
8    assert "error" in result

9. 文档

包含全面的文档：


markdown
## 文档

### 安装
```bash
pip install -r requirements.txt
## 文档

### 安装
```bash
pip install -r requirements.txt

配置

设置环境变量:

API_KEY: 你的 API 密钥
MAX_PAGES: 要处理的最大页数（默认: 10）

故障排除

问题: 技能未加载 解决方案: 检查文件夹结构是否符合规范


## 10. 维护

- 定期更新依赖
- 监控技能性能
- 收集用户反馈
- 迭代边缘情况

## 真实案例

这是一个结构良好的技能：

```markdown
# 发票数据提取器

## 元数据
- 名称: invoice-extractor
- 描述: 从 PDF 发票中提取结构化数据
- 版本: 2.1.0
- 作者: 财务团队
- 标签: pdf, invoices, data-extraction
- 许可证: MIT

## 指令
[详细的 10 步流程]

## 使用示例
[5 种不同场景]

## 依赖
- Python >= 3.8
- pdfplumber >= 0.9.0
- python-dateutil >= 2.8.0

## 错误处理
[记录所有失败模式]

## 安全性
[列出安全考虑]

## 性能
- 平均执行: 2-3 秒
- 内存使用: < 100MB
- 并发执行: 安全

## 变更日志
### 2.1.0 (2025-01-15)
- 添加多货币支持
- 改进日期解析
### 2.0.0 (2025-01-01)
- 重大变更: 更改输出格式为 JSON

检查清单

[ ] 清晰、描述性的名称
[ ] 详细的逐步指令
[ ] 3+ 使用示例
[ ] 所有错误案例已记录
[ ] 安全考虑已注明
[ ] 带版本的依赖
[ ] 性能特征
[ ] 包含测试套件
[ ] 全面的文档
[ ] 维护版本历史

阅读时间：5分钟

作者: ClaudeSkills 团队

Claude Skills 最佳实践：构建可靠的自动化