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 - バグ修正
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
- 作者: Finance Team
- タグ: 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 Team

Claude Skills ベストプラクティス：信頼性の高い自動化を構築