Skill作成のベストプラクティス

Claudeが発見し、効果的に使用できるSkillの書き方を学びましょう。

優れたSkillは簡潔で、よく構造化されており、実際の使用でテストされています。このガイドでは、Claudeが発見し効果的に使用できるSkillを書くための実践的な判断基準を提供します。

Skillの仕組みについての概念的な背景は、Skills概要を参照してください。

基本原則

簡潔さが鍵

コンテキストウィンドウは公共財です。あなたのSkillは、Claudeが知る必要のある他のすべてとコンテキストウィンドウを共有します：

• システムプロンプト
• 会話履歴
• 他のSkillのメタデータ
• 実際のリクエスト

Skill内のすべてのトークンが即座にコストになるわけではありません。起動時には、すべてのSkillからメタデータ（名前と説明）のみがプリロードされます。ClaudeはSkillが関連するときのみSKILL.mdを読み、追加ファイルは必要に応じて読み込みます。ただし、SKILL.mdで簡潔にすることは依然として重要です：Claudeがそれを読み込むと、すべてのトークンが会話履歴や他のコンテキストと競合します。

デフォルトの前提：Claudeはすでに非常に賢い

Claudeがまだ持っていないコンテキストのみを追加してください。各情報を確認しましょう：

• 「Claudeは本当にこの説明が必要か？」
• 「Claudeはこれを知っていると仮定できるか？」
• 「この段落はトークンコストに見合うか？」

良い例：簡潔（約50トークン）：

## PDFテキスト抽出

pdfplumberを使用してテキストを抽出：

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

悪い例：冗長すぎる（約150トークン）：

## PDFテキスト抽出

PDF（Portable Document Format）ファイルは、テキスト、画像、その他のコンテンツを含む一般的なファイル形式です。PDFからテキストを抽出するには、ライブラリを使用する必要があります。PDF処理用のライブラリは多数ありますが、使いやすく、ほとんどのケースをうまく処理できるpdfplumberをお勧めします。まず、pipを使用してインストールする必要があります。次に、以下のコードを使用できます...

簡潔なバージョンは、ClaudeがPDFとは何か、ライブラリがどのように機能するかを知っていると仮定しています。

適切な自由度を設定する

タスクの脆弱性と変動性に応じて、具体性のレベルを合わせましょう。

高い自由度（テキストベースの指示）：

以下の場合に使用：

• 複数のアプローチが有効
• 決定がコンテキストに依存する
• ヒューリスティックがアプローチを導く

例：

## コードレビュープロセス

1. コードの構造と組織を分析する
2. 潜在的なバグやエッジケースをチェックする
3. 可読性と保守性の改善を提案する
4. プロジェクトの規約への準拠を確認する

中程度の自由度（疑似コードまたはパラメータ付きスクリプト）：

以下の場合に使用：

• 好ましいパターンが存在する
• ある程度の変動が許容される
• 設定が動作に影響する

例：

## レポート生成

このテンプレートを使用し、必要に応じてカスタマイズ：

```python
def generate_report(data, format="markdown", include_charts=True):
    # データを処理
    # 指定された形式で出力を生成
    # オプションで可視化を含める
```

低い自由度（特定のスクリプト、パラメータなしまたは少数）：

以下の場合に使用：

• 操作が脆弱でエラーが起きやすい
• 一貫性が重要
• 特定の順序に従う必要がある

例：

## データベースマイグレーション

正確にこのスクリプトを実行：

```bash
python scripts/migrate.py --verify --backup
```

コマンドを変更したり、追加のフラグを追加しないでください。

例え：Claudeを道を探索するロボットと考えてください：

• 両側に崖がある狭い橋：安全に進む方法は一つだけ。特定のガードレールと正確な指示を提供する（低い自由度）。例：正確な順序で実行する必要があるデータベースマイグレーション。
• 危険のない広い野原：多くの道が成功につながる。一般的な方向を与え、Claudeが最良のルートを見つけることを信頼する（高い自由度）。例：コンテキストが最良のアプローチを決定するコードレビュー。

使用予定のすべてのモデルでテストする

Skillはモデルへの追加として機能するため、効果は基盤となるモデルに依存します。使用予定のすべてのモデルでSkillをテストしてください。

モデル別のテスト考慮事項：

• Claude Haiku（高速、経済的）：Skillは十分なガイダンスを提供しているか？
• Claude Sonnet（バランス型）：Skillは明確で効率的か？
• Claude Opus（強力な推論）：Skillは過剰な説明を避けているか？

Opusで完璧に機能するものでも、Haikuではより詳細が必要かもしれません。複数のモデルでSkillを使用する予定がある場合は、すべてで適切に機能する指示を目指してください。

Skill構造

YAMLフロントマター：SKILL.mdのフロントマターには2つのフィールドが必要です：

name：

• 最大64文字
• 小文字、数字、ハイフンのみ使用可能
• XMLタグを含めることはできない
• 予約語を含めることはできない：「anthropic」、「claude」

description：

• 空でないこと
• 最大1024文字
• XMLタグを含めることはできない
• Skillが何をするか、いつ使用するかを説明すること

完全なSkill構造の詳細については、Skills概要を参照してください。

命名規則

参照や議論を容易にするために、一貫した命名パターンを使用してください。Skill名には動名詞形（動詞 + -ing）の使用をお勧めします。これはSkillが提供するアクティビティや機能を明確に説明します。

nameフィールドは小文字、数字、ハイフンのみを使用する必要があることを忘れないでください。

良い命名例（動名詞形）：

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

許容される代替案：

• 名詞句：pdf-processing、spreadsheet-analysis
• アクション指向：process-pdfs、analyze-spreadsheets

避けるべきもの：

• 曖昧な名前：helper、utils、tools
• 過度に一般的：documents、data、files
• 予約語：anthropic-helper、claude-tools
• スキルコレクション内での一貫性のないパターン

一貫した命名により以下が容易になります：

• ドキュメントや会話でSkillを参照する
• Skillが何をするか一目で理解する
• 複数のSkillを整理して検索する
• プロフェッショナルで統一感のあるスキルライブラリを維持する

効果的な説明を書く

descriptionフィールドはSkillの発見を可能にし、Skillが何をするかといつ使用するかの両方を含める必要があります。

常に三人称で書く。説明はシステムプロンプトに注入され、視点の不一致は発見の問題を引き起こす可能性があります。

• 良い： 「Excelファイルを処理し、レポートを生成する」
• 避ける： 「Excelファイルの処理をお手伝いできます」
• 避ける： 「これを使用してExcelファイルを処理できます」

具体的に、キーワードを含める。Skillが何をするかと、いつ使用するかの特定のトリガー/コンテキストの両方を含めてください。

各Skillには正確に1つの説明フィールドがあります。説明はスキル選択に重要です：Claudeはそれを使用して、100以上の利用可能なSkillから適切なSkillを選択します。説明は、ClaudeがこのSkillをいつ選択するかを知るのに十分な詳細を提供する必要があり、SKILL.mdの残りの部分は実装の詳細を提供します。

効果的な例：

PDF処理スキル：

description: PDFファイルからテキストとテーブルを抽出し、フォームに入力し、ドキュメントをマージする。PDFファイルを扱う場合や、ユーザーがPDF、フォーム、ドキュメント抽出について言及した場合に使用。

Excel分析スキル：

description: Excelスプレッドシートを分析し、ピボットテーブルを作成し、チャートを生成する。Excelファイル、スプレッドシート、表形式データ、または.xlsxファイルを分析する場合に使用。

Gitコミットヘルパースキル：

description: gitの差分を分析して説明的なコミットメッセージを生成する。ユーザーがコミットメッセージの作成やステージングされた変更のレビューについて助けを求めた場合に使用。

次のような曖昧な説明は避けてください：

description: ドキュメントを手伝う

description: データを処理する

description: ファイルに関する作業をする

プログレッシブディスクロージャーパターン

SKILL.mdは、オンボーディングガイドの目次のように、必要に応じてClaudeを詳細な資料に導く概要として機能します。プログレッシブディスクロージャーの仕組みについては、概要のSkillの仕組みを参照してください。

実践的なガイダンス：

• 最適なパフォーマンスのために、SKILL.mdの本文を500行未満に保つ
• この制限に近づいた場合は、コンテンツを別のファイルに分割する
• 以下のパターンを使用して、指示、コード、リソースを効果的に整理する

ビジュアル概要：シンプルから複雑へ

基本的なSkillは、メタデータと指示を含むSKILL.mdファイルから始まります：

Skillが成長するにつれて、Claudeが必要な場合のみロードする追加コンテンツをバンドルできます：

完全なSkillディレクトリ構造は次のようになります：

pdf/
├── SKILL.md              # メイン指示（トリガー時にロード）
├── FORMS.md              # フォーム入力ガイド（必要に応じてロード）
├── reference.md          # APIリファレンス（必要に応じてロード）
├── examples.md           # 使用例（必要に応じてロード）
└── scripts/
    ├── analyze_form.py   # ユーティリティスクリプト（ロードではなく実行）
    ├── fill_form.py      # フォーム入力スクリプト
    └── validate.py       # 検証スクリプト

パターン1：参照付きの高レベルガイド

---
name: pdf-processing
description: PDFファイルからテキストとテーブルを抽出し、フォームに入力し、ドキュメントをマージする。PDFファイルを扱う場合や、ユーザーがPDF、フォーム、ドキュメント抽出について言及した場合に使用。
---

# PDF処理

## クイックスタート

pdfplumberでテキストを抽出：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 高度な機能

**フォーム入力**：完全なガイドは[FORMS.md](FORMS.md)を参照
**APIリファレンス**：すべてのメソッドは[REFERENCE.md](REFERENCE.md)を参照
**例**：一般的なパターンは[EXAMPLES.md](EXAMPLES.md)を参照

ClaudeはFORMS.md、REFERENCE.md、またはEXAMPLES.mdを必要な場合のみロードします。

パターン2：ドメイン固有の整理

複数のドメインを持つSkillの場合、無関係なコンテキストのロードを避けるために、ドメインごとにコンテンツを整理します。ユーザーが売上メトリクスについて質問した場合、Claudeは財務やマーケティングのデータではなく、売上関連のスキーマのみを読む必要があります。これにより、トークン使用量が低く保たれ、コンテキストが集中します。

bigquery-skill/
├── SKILL.md（概要とナビゲーション）
└── reference/
    ├── finance.md（収益、請求メトリクス）
    ├── sales.md（商談、パイプライン）
    ├── product.md（API使用状況、機能）
    └── marketing.md（キャンペーン、アトリビューション）

# BigQueryデータ分析

## 利用可能なデータセット

**財務**：収益、ARR、請求 → [reference/finance.md](reference/finance.md)を参照
**営業**：商談、パイプライン、アカウント → [reference/sales.md](reference/sales.md)を参照
**プロダクト**：API使用状況、機能、採用 → [reference/product.md](reference/product.md)を参照
**マーケティング**：キャンペーン、アトリビューション、メール → [reference/marketing.md](reference/marketing.md)を参照

## クイック検索

grepを使用して特定のメトリクスを検索：

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

パターン3：条件付き詳細

基本的なコンテンツを表示し、高度なコンテンツにリンク：

# DOCX処理

## ドキュメントの作成

新しいドキュメントにはdocx-jsを使用。[DOCX-JS.md](DOCX-JS.md)を参照。

## ドキュメントの編集

簡単な編集の場合は、XMLを直接変更。

**変更追跡について**：[REDLINING.md](REDLINING.md)を参照
**OOXMLの詳細について**：[OOXML.md](OOXML.md)を参照

Claudeはユーザーがそれらの機能を必要とする場合のみ、REDLINING.mdまたはOOXML.mdを読み込みます。

深くネストされた参照を避ける

Claudeは、他の参照ファイルから参照されるファイルを部分的に読み取る可能性があります。ネストされた参照に遭遇した場合、Claudeはファイル全体を読み取る代わりにhead -100のようなコマンドを使用してコンテンツをプレビューし、情報が不完全になる可能性があります。

SKILL.mdから1レベルの深さで参照を維持する。すべての参照ファイルはSKILL.mdから直接リンクして、Claudeが必要なときに完全なファイルを読み取れるようにする必要があります。

悪い例：深すぎる：

# SKILL.md
[advanced.md](advanced.md)を参照...

# advanced.md
[details.md](details.md)を参照...

# details.md
ここに実際の情報があります...

良い例：1レベルの深さ：

# SKILL.md

**基本的な使用法**：[SKILL.md内の指示]
**高度な機能**：[advanced.md](advanced.md)を参照
**APIリファレンス**：[reference.md](reference.md)を参照
**例**：[examples.md](examples.md)を参照

長い参照ファイルには目次を含める

100行を超える参照ファイルの場合は、上部に目次を含めてください。これにより、部分的な読み取りでプレビューしている場合でも、Claudeが利用可能な情報の全範囲を確認できます。

例：

# APIリファレンス

## 目次
- 認証とセットアップ
- コアメソッド（作成、読み取り、更新、削除）
- 高度な機能（バッチ操作、Webhook）
- エラー処理パターン
- コード例

## 認証とセットアップ
...

## コアメソッド
...

Claudeは必要に応じて完全なファイルを読み取るか、特定のセクションにジャンプできます。

このファイルシステムベースのアーキテクチャがプログレッシブディスクロージャーをどのように可能にするかについては、以下の高度なセクションのランタイム環境セクションを参照してください。

ワークフローとフィードバックループ

複雑なタスクにはワークフローを使用する

複雑な操作を明確で順次的なステップに分割します。特に複雑なワークフローの場合は、Claudeがレスポンスにコピーして進行に応じてチェックできるチェックリストを提供してください。

例1：リサーチ統合ワークフロー（コードなしのSkill用）：

## リサーチ統合ワークフロー

このチェックリストをコピーして進捗を追跡：

```
リサーチ進捗：
- [ ] ステップ1：すべてのソースドキュメントを読む
- [ ] ステップ2：主要なテーマを特定する
- [ ] ステップ3：主張を相互参照する
- [ ] ステップ4：構造化されたサマリーを作成する
- [ ] ステップ5：引用を確認する
```

**ステップ1：すべてのソースドキュメントを読む**

`sources/`ディレクトリ内の各ドキュメントをレビューします。主な議論と裏付けとなる証拠をメモしてください。

**ステップ2：主要なテーマを特定する**

ソース間でパターンを探します。どのテーマが繰り返し現れるか？ソースはどこで一致または不一致しているか？

**ステップ3：主張を相互参照する**

各主要な主張について、ソース資料に記載されていることを確認します。各ポイントを裏付けるソースをメモしてください。

**ステップ4：構造化されたサマリーを作成する**

テーマごとに調査結果を整理します。含めるもの：
- 主な主張
- ソースからの裏付け証拠
- 対立する見解（ある場合）

**ステップ5：引用を確認する**

すべての主張が正しいソースドキュメントを参照していることを確認します。引用が不完全な場合は、ステップ3に戻ります。

この例は、コードを必要としない分析タスクにワークフローがどのように適用されるかを示しています。チェックリストパターンは、複雑な複数ステップのプロセスに対して機能します。

例2：PDFフォーム入力ワークフロー（コード付きのSkill用）：

## PDFフォーム入力ワークフロー

このチェックリストをコピーし、完了したらアイテムをチェック：

```
タスク進捗：
- [ ] ステップ1：フォームを分析する（analyze_form.pyを実行）
- [ ] ステップ2：フィールドマッピングを作成する（fields.jsonを編集）
- [ ] ステップ3：マッピングを検証する（validate_fields.pyを実行）
- [ ] ステップ4：フォームに入力する（fill_form.pyを実行）
- [ ] ステップ5：出力を確認する（verify_output.pyを実行）
```

**ステップ1：フォームを分析する**

実行：`python scripts/analyze_form.py input.pdf`

これによりフォームフィールドとその位置が抽出され、`fields.json`に保存されます。

**ステップ2：フィールドマッピングを作成する**

`fields.json`を編集して、各フィールドに値を追加します。

**ステップ3：マッピングを検証する**

実行：`python scripts/validate_fields.py fields.json`

続行する前に検証エラーを修正してください。

**ステップ4：フォームに入力する**

実行：`python scripts/fill_form.py input.pdf fields.json output.pdf`

**ステップ5：出力を確認する**

実行：`python scripts/verify_output.py output.pdf`

確認に失敗した場合は、ステップ2に戻ります。

明確なステップにより、Claudeが重要な検証をスキップすることを防ぎます。チェックリストは、Claudeとあなたの両方が複数ステップのワークフローの進捗を追跡するのに役立ちます。

フィードバックループを実装する

一般的なパターン：バリデータを実行 → エラーを修正 → 繰り返し

このパターンは出力品質を大幅に向上させます。

例1：スタイルガイド準拠（コードなしのSkill用）：

## コンテンツレビュープロセス

1. STYLE_GUIDE.mdのガイドラインに従ってコンテンツを作成
2. チェックリストに照らしてレビュー：
   - 用語の一貫性をチェック
   - 例が標準フォーマットに従っていることを確認
   - すべての必須セクションが存在することを確認
3. 問題が見つかった場合：
   - 各問題を特定のセクション参照とともにメモ
   - コンテンツを修正
   - チェックリストを再度レビュー
4. すべての要件が満たされた場合のみ続行
5. ドキュメントを最終化して保存

これは、スクリプトの代わりに参照ドキュメントを使用した検証ループパターンを示しています。「バリデータ」はSTYLE_GUIDE.mdであり、Claudeは読み取りと比較によってチェックを実行します。

例2：ドキュメント編集プロセス（コード付きのSkill用）：

## ドキュメント編集プロセス

1. `word/document.xml`を編集
2. **すぐに検証**：`python ooxml/scripts/validate.py unpacked_dir/`
3. 検証に失敗した場合：
   - エラーメッセージを注意深く確認
   - XML内の問題を修正
   - 検証を再度実行
4. **検証が通過した場合のみ続行**
5. 再構築：`python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 出力ドキュメントをテスト

検証ループは早期にエラーをキャッチします。

コンテンツガイドライン

時間に敏感な情報を避ける

古くなる情報を含めないでください：

悪い例：時間に敏感（間違いになる）：

2025年8月より前にこれを行う場合は、古いAPIを使用してください。
2025年8月以降は、新しいAPIを使用してください。

良い例（「古いパターン」セクションを使用）：

## 現在の方法

v2 APIエンドポイントを使用：`api.example.com/v2/messages`

## 古いパターン

<details>
<summary>レガシーv1 API（2025年8月に非推奨）</summary>

v1 APIは次を使用していました：`api.example.com/v1/messages`

このエンドポイントはサポートされなくなりました。
</details>

古いパターンセクションは、メインコンテンツを乱雑にすることなく、歴史的なコンテキストを提供します。

一貫した用語を使用する

1つの用語を選択し、Skill全体で使用してください：

良い - 一貫している：

• 常に「APIエンドポイント」
• 常に「フィールド」
• 常に「抽出」

悪い - 一貫していない：

• 「APIエンドポイント」「URL」「APIルート」「パス」を混在
• 「フィールド」「ボックス」「要素」「コントロール」を混在
• 「抽出」「プル」「取得」「リトリーブ」を混在

一貫性は、Claudeが指示を理解し従うのに役立ちます。

一般的なパターン

テンプレートパターン

出力形式のテンプレートを提供します。ニーズに合わせて厳格さのレベルを調整してください。

厳格な要件の場合（APIレスポンスやデータ形式など）：

## レポート構造

常にこの正確なテンプレート構造を使用：

```markdown
# [分析タイトル]

## エグゼクティブサマリー
[主要な発見の1段落の概要]

## 主要な発見
- 裏付けデータ付きの発見1
- 裏付けデータ付きの発見2
- 裏付けデータ付きの発見3

## 推奨事項
1. 具体的で実行可能な推奨事項
2. 具体的で実行可能な推奨事項
```

柔軟なガイダンスの場合（適応が有用な場合）：

## レポート構造

これは賢明なデフォルト形式ですが、分析に基づいて最良の判断を使用してください：

```markdown
# [分析タイトル]

## エグゼクティブサマリー
[概要]

## 主要な発見
[発見したことに基づいてセクションを適応]

## 推奨事項
[特定のコンテキストに合わせて調整]
```

特定の分析タイプに応じてセクションを調整してください。

例パターン

出力品質が例を見ることに依存するSkillの場合、通常のプロンプティングと同様に入力/出力のペアを提供します：

## コミットメッセージ形式

これらの例に従ってコミットメッセージを生成：

**例1：**
入力：JWTトークンによるユーザー認証を追加
出力：
```
feat(auth): JWTベースの認証を実装

ログインエンドポイントとトークン検証ミドルウェアを追加
```

**例2：**
入力：レポートで日付が正しく表示されないバグを修正
出力：
```
fix(reports): タイムゾーン変換での日付フォーマットを修正

レポート生成全体でUTCタイムスタンプを一貫して使用
```

**例3：**
入力：依存関係を更新し、エラー処理をリファクタリング
出力：
```
chore: 依存関係を更新し、エラー処理をリファクタリング

- lodashを4.17.21にアップグレード
- エンドポイント全体でエラーレスポンス形式を標準化
```

このスタイルに従う：type(scope): 簡潔な説明、次に詳細な説明。

例は、説明だけよりも、希望するスタイルと詳細レベルをClaudeが理解するのに役立ちます。

条件付きワークフローパターン

決定ポイントを通じてClaudeをガイドします：

## ドキュメント変更ワークフロー

1. 変更タイプを決定：

   **新しいコンテンツを作成？** → 以下の「作成ワークフロー」に従う
   **既存のコンテンツを編集？** → 以下の「編集ワークフロー」に従う

2. 作成ワークフロー：
   - docx-jsライブラリを使用
   - ゼロからドキュメントを構築
   - .docx形式でエクスポート

3. 編集ワークフロー：
   - 既存のドキュメントを展開
   - XMLを直接変更
   - 各変更後に検証
   - 完了したら再パック

ヒント：ワークフローが多くのステップで大きくなったり複雑になったりした場合は、それらを別のファイルにプッシュし、タスクに応じて適切なファイルを読むようにClaudeに指示することを検討してください。

評価と反復

最初に評価を構築する

広範なドキュメントを書く前に評価を作成してください。 これにより、Skillが想像上のものではなく、実際の問題を解決することが保証されます。

評価駆動開発：

1. ギャップを特定：Skillなしで代表的なタスクでClaudeを実行。特定の失敗または不足しているコンテキストを文書化
2. 評価を作成：これらのギャップをテストする3つのシナリオを構築
3. ベースラインを確立：Skillなしでのクロードのパフォーマンスを測定
4. 最小限の指示を書く：ギャップに対処し、評価に合格するのに十分なコンテンツのみを作成
5. 反復：評価を実行し、ベースラインと比較し、改良

このアプローチにより、実現しない可能性のある要件を予測するのではなく、実際の問題を解決していることが保証されます。

評価構造：

{
  "skills": ["pdf-processing"],
  "query": "このPDFファイルからすべてのテキストを抽出し、output.txtに保存してください",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "適切なPDF処理ライブラリまたはコマンドラインツールを使用してPDFファイルを正常に読み取る",
    "ページをスキップすることなく、ドキュメント内のすべてのページからテキストコンテンツを抽出する",
    "抽出されたテキストを明確で読みやすい形式でoutput.txtというファイルに保存する"
  ]
}

注：この例は、シンプルなテスト基準を持つデータ駆動型評価を示しています。現在、これらの評価を実行するための組み込みの方法は提供していません。ユーザーは独自の評価システムを作成できます。評価は、Skillの効果を測定するための真実の源です。

Claudeと反復的にSkillを開発する

最も効果的なSkill開発プロセスには、Claude自体が関与します。Claudeの1つのインスタンス（「Claude A」）と協力して、他のインスタンス（「Claude B」）が使用するSkillを作成します。Claude Aは設計と指示の改良を支援し、Claude Bは実際のタスクでテストします。これが機能するのは、Claudeモデルが効果的なエージェント指示の書き方と、エージェントが必要とする情報の両方を理解しているためです。

新しいSkillの作成：

1. Skillなしでタスクを完了：通常のプロンプティングを使用してClaude Aと問題に取り組みます。作業中、自然とコンテキストを提供し、好みを説明し、手順の知識を共有します。繰り返し提供する情報に注意してください。
2. 再利用可能なパターンを特定：タスクを完了した後、将来の類似タスクに役立つ、提供したコンテキストを特定します。
   例：BigQuery分析を行った場合、テーブル名、フィールド定義、フィルタリングルール（「常にテストアカウントを除外する」など）、および一般的なクエリパターンを提供した可能性があります。
3. Claude AにSkillを作成させる：「今使用したこのBigQuery分析パターンをキャプチャするSkillを作成してください。テーブルスキーマ、命名規則、およびテストアカウントのフィルタリングに関するルールを含めてください。」
   ヒント：ClaudeモデルはSkillの形式と構造をネイティブに理解しています。ClaudeにSkillを作成させるために、特別なシステムプロンプトや「Skill作成」スキルは必要ありません。ClaudeにSkillを作成するよう依頼するだけで、適切なフロントマターと本文コンテンツを持つ適切に構造化されたSKILL.mdコンテンツが生成されます。
4. 簡潔さをレビュー：Claude Aが不要な説明を追加していないか確認します。「勝率が何を意味するかの説明を削除してください - Claudeはすでにそれを知っています。」と依頼します。
5. 情報アーキテクチャを改善：Claude Aにコンテンツをより効果的に整理するよう依頼します。例：「テーブルスキーマが別の参照ファイルになるように整理してください。後でテーブルを追加する可能性があります。」
6. 類似タスクでテスト：関連するユースケースで、Skillを持つClaude B（Skillがロードされた新しいインスタンス）を使用します。Claude Bが適切な情報を見つけ、ルールを正しく適用し、タスクを正常に処理するかどうかを観察します。
7. 観察に基づいて反復：Claude Bが苦労したり、何かを見逃したりした場合は、具体的な情報を持ってClaude Aに戻ります：「Claudeがこのスキルを使用したとき、Q4の日付でフィルタリングするのを忘れていました。日付フィルタリングパターンに関するセクションを追加すべきでしょうか？」

既存のSkillの反復：

Skillを改善する際にも、同じ階層パターンが続きます。以下を交互に行います：

• Claude Aと作業（Skillの改良を支援する専門家）
• Claude Bでテスト（実際の作業を行うためにSkillを使用するエージェント）
• Claude Bの動作を観察し、洞察をClaude Aに持ち帰る

1. 実際のワークフローでSkillを使用：Claude B（Skillがロードされた状態）に、テストシナリオではなく実際のタスクを与えます
2. Claude Bの動作を観察：苦労している場所、成功している場所、または予期しない選択をしている場所に注意
   観察例：「Claude Bに地域別売上レポートを依頼したところ、Skillがこのルールに言及しているにもかかわらず、テストアカウントをフィルタリングするのを忘れていました。」
3. 改善のためにClaude Aに戻る：現在のSKILL.mdを共有し、観察したことを説明します。「Claude Bが地域レポートを依頼したとき、テストアカウントをフィルタリングするのを忘れていたことに気づきました。Skillはフィルタリングに言及していますが、十分に目立たないのかもしれません？」
4. Claude Aの提案をレビュー：Claude Aは、ルールをより目立たせるために再編成すること、「常にフィルタ」ではなく「必ずフィルタ」のような強い言葉を使用すること、またはワークフローセクションを再構築することを提案するかもしれません。
5. 変更を適用してテスト：Claude Aの改良でSkillを更新し、類似のリクエストでClaude Bで再度テスト
6. 使用に基づいて繰り返す：新しいシナリオに遭遇するたびに、この観察-改良-テストサイクルを続けます。各反復は、仮定ではなく実際のエージェントの動作に基づいてSkillを改善します。

チームのフィードバックを収集：

1. チームメイトとSkillを共有し、使用状況を観察
2. 質問：Skillは期待通りにアクティブになるか？指示は明確か？何が欠けているか？
3. フィードバックを組み込んで、自分の使用パターンの盲点に対処

このアプローチが機能する理由：Claude Aはエージェントのニーズを理解し、あなたはドメインの専門知識を提供し、Claude Bは実際の使用を通じてギャップを明らかにし、反復的な改良は仮定ではなく観察された動作に基づいてSkillを改善します。

ClaudeがSkillをナビゲートする方法を観察する

Skillを反復しながら、Claudeが実際にそれらをどのように使用しているかに注意を払ってください。以下を観察します：

• 予期しない探索パス：Claudeは予期しない順序でファイルを読み取っていますか？これは、構造があなたが思っていたほど直感的ではないことを示しているかもしれません
• 見逃された接続：Claudeは重要なファイルへの参照をたどるのに失敗していますか？リンクをより明示的または目立つようにする必要があるかもしれません
• 特定のセクションへの過度の依存：Claudeが同じファイルを繰り返し読み取る場合、そのコンテンツをメインのSKILL.mdに含めるべきかどうかを検討してください
• 無視されたコンテンツ：Claudeがバンドルされたファイルにアクセスしない場合、それは不要であるか、メインの指示で適切に示されていない可能性があります

仮定ではなく、これらの観察に基づいて反復します。Skillのメタデータの「name」と「description」は特に重要です。Claudeはこれらを使用して、現在のタスクに応じてSkillをトリガーするかどうかを決定します。Skillが何をするか、いつ使用すべきかを明確に説明してください。

避けるべきアンチパターン

Windowsスタイルのパスを避ける

Windowsでも、ファイルパスには常にフォワードスラッシュを使用してください：

• ✓ 良い：scripts/helper.py、reference/guide.md
• ✗ 避ける：scripts\helper.py、reference\guide.md

Unix スタイルのパスはすべてのプラットフォームで動作しますが、Windowsスタイルのパスはunixシステムでエラーを引き起こします。

選択肢を多く提供しすぎない

必要でない限り、複数のアプローチを提示しないでください：

**悪い例：選択肢が多すぎる**（混乱する）：
「pypdf、またはpdfplumber、またはPyMuPDF、またはpdf2image、または...を使用できます」

**良い例：デフォルトを提供**（エスケープハッチ付き）：
「テキスト抽出にはpdfplumberを使用：
```python
import pdfplumber
```

OCRが必要なスキャンPDFの場合は、代わりにpdf2imageとpytesseractを使用してください。」

高度：実行可能コードを含むSkill

以下のセクションは、実行可能スクリプトを含むSkillに焦点を当てています。Skillがマークダウン指示のみを使用する場合は、効果的なSkillのチェックリストにスキップしてください。

問題を解決し、回避しない

Skill用のスクリプトを書くときは、Claudeに問題を押し付けるのではなく、エラー条件を処理してください。

良い例：エラーを明示的に処理：

def process_file(path):
    """ファイルを処理し、存在しない場合は作成。"""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 失敗する代わりにデフォルトコンテンツでファイルを作成
        print(f"ファイル{path}が見つかりません、デフォルトを作成")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 失敗する代わりに代替を提供
        print(f"{path}にアクセスできません、デフォルトを使用")
        return ''

悪い例：Claudeに押し付ける：

def process_file(path):
    # 失敗してClaudeに解決させる
    return open(path).read()

設定パラメータも、「おまじない定数」（Ousterhoutの法則）を避けるために、正当化され文書化されるべきです。正しい値がわからない場合、Claudeはどのように決定しますか？

良い例：自己文書化：

# HTTPリクエストは通常30秒以内に完了
# 遅い接続のために長いタイムアウトを設定
REQUEST_TIMEOUT = 30

# 3回のリトライは信頼性と速度のバランスを取る
# ほとんどの間欠的な障害は2回目のリトライで解決
MAX_RETRIES = 3

悪い例：マジックナンバー：

TIMEOUT = 47  # なぜ47？
RETRIES = 5   # なぜ5？

ユーティリティスクリプトを提供する

Claudeがスクリプトを書くことができたとしても、事前に作成されたスクリプトには利点があります：

ユーティリティスクリプトの利点：

• 生成されたコードよりも信頼性が高い
• トークンを節約（コンテキストにコードを含める必要がない）
• 時間を節約（コード生成が不要）
• 使用全体の一貫性を確保

上の図は、実行可能スクリプトが指示ファイルと一緒にどのように動作するかを示しています。指示ファイル（forms.md）はスクリプトを参照し、Claudeはその内容をコンテキストにロードせずに実行できます。

重要な区別：指示でClaudeが以下のいずれを行うべきかを明確にしてください：

• スクリプトを実行（最も一般的）：「analyze_form.pyを実行してフィールドを抽出」
• 参照として読む（複雑なロジックの場合）：「フィールド抽出アルゴリズムについてはanalyze_form.pyを参照」

ほとんどのユーティリティスクリプトでは、より信頼性が高く効率的なため、実行が好まれます。スクリプト実行の仕組みについては、以下のランタイム環境セクションを参照してください。

例：

## ユーティリティスクリプト

**analyze_form.py**：PDFからすべてのフォームフィールドを抽出

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

出力形式：
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**：重複するバウンディングボックスをチェック

```bash
python scripts/validate_boxes.py fields.json
# 戻り値：「OK」または競合をリスト
```

**fill_form.py**：PDFにフィールド値を適用

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

ビジュアル分析を使用する

入力が画像としてレンダリングできる場合は、Claudeに分析させてください：

## フォームレイアウト分析

1. PDFを画像に変換：
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. 各ページ画像を分析してフォームフィールドを特定
3. Claudeはフィールドの位置とタイプを視覚的に確認可能

注：この例では、pdf_to_images.pyスクリプトを書く必要があります。

Claudeのビジョン機能は、レイアウトと構造を理解するのに役立ちます。

検証可能な中間出力を作成する

Claudeが複雑でオープンエンドなタスクを実行するとき、ミスを犯す可能性があります。「計画-検証-実行」パターンは、Claudeにまず構造化された形式で計画を作成させ、その計画を実行前にスクリプトで検証することで、早期にエラーをキャッチします。

例：スプレッドシートに基づいてPDFの50のフォームフィールドを更新するようClaudeに依頼することを想像してください。検証なしでは、Claudeは存在しないフィールドを参照したり、競合する値を作成したり、必須フィールドを見逃したり、更新を誤って適用したりする可能性があります。

解決策：上記のワークフローパターン（PDFフォーム入力）を使用しますが、変更を適用する前に検証される中間のchanges.jsonファイルを追加します。ワークフローは次のようになります：分析 → 計画ファイルを作成 → 計画を検証 → 実行 → 確認。

このパターンが機能する理由：

• 早期にエラーをキャッチ：検証は変更が適用される前に問題を見つける
• 機械検証可能：スクリプトは客観的な検証を提供
• 可逆的な計画：Claudeはオリジナルに触れずに計画を反復できる
• 明確なデバッグ：エラーメッセージは特定の問題を指摘

使用するタイミング：バッチ操作、破壊的な変更、複雑な検証ルール、高リスクの操作。

実装のヒント：検証スクリプトを「'signature_date'フィールドが見つかりません。利用可能なフィールド：customer_name、order_total、signature_date_signed」のような具体的なエラーメッセージで詳細にして、Claudeが問題を修正するのに役立てます。

依存関係をパッケージ化する

Skillはプラットフォーム固有の制限があるコード実行環境で実行されます：

• claude.ai：npmとPyPIからパッケージをインストールし、GitHubリポジトリからプルできる
• Anthropic API：ネットワークアクセスなし、ランタイムパッケージインストールなし

SKILL.mdで必要なパッケージをリストし、コード実行ツールのドキュメントで利用可能であることを確認してください。

ランタイム環境

Skillは、ファイルシステムアクセス、bashコマンド、およびコード実行機能を備えたコード実行環境で実行されます。このアーキテクチャの概念的な説明については、概要のSkillsアーキテクチャを参照してください。

これが作成に与える影響：

ClaudeがSkillにアクセスする方法：

1. メタデータのプリロード：起動時に、すべてのSkillのYAMLフロントマターからの名前と説明がシステムプロンプトにロードされる
2. オンデマンドでファイルを読み取り：Claudeは必要に応じてbash Readツールを使用してSKILL.mdと他のファイルにファイルシステムからアクセス
3. スクリプトを効率的に実行：ユーティリティスクリプトは、完全なコンテンツをコンテキストにロードせずにbash経由で実行可能。スクリプトの出力のみがトークンを消費
4. 大きなファイルへのコンテキストペナルティなし：参照ファイル、データ、またはドキュメントは、実際に読み取られるまでコンテキストトークンを消費しない

• ファイルパスは重要：Claudeはスキルディレクトリをファイルシステムのようにナビゲート。バックスラッシュではなくフォワードスラッシュを使用（reference/guide.md）
• ファイルに説明的な名前を付ける：コンテンツを示す名前を使用：form_validation_rules.md、doc2.mdではなく
• 発見のために整理：ドメインまたは機能ごとにディレクトリを構造化
  • 良い：reference/finance.md、reference/sales.md
  • 悪い：docs/file1.md、docs/file2.md
• 包括的なリソースをバンドル：完全なAPIドキュメント、豊富な例、大規模なデータセットを含める；アクセスされるまでコンテキストペナルティなし
• 決定論的操作にはスクリプトを優先：Claudeに検証コードを生成させるのではなく、validate_form.pyを書く
• 実行意図を明確にする：
  • 「analyze_form.pyを実行してフィールドを抽出」（実行）
  • 「抽出アルゴリズムについてはanalyze_form.pyを参照」（参照として読む）
• ファイルアクセスパターンをテスト：実際のリクエストでテストして、Claudeがディレクトリ構造をナビゲートできることを確認

例：

bigquery-skill/
├── SKILL.md（概要、参照ファイルを指す）
└── reference/
    ├── finance.md（収益メトリクス）
    ├── sales.md（パイプラインデータ）
    └── product.md（使用状況分析）

ユーザーが収益について質問すると、ClaudeはSKILL.mdを読み、reference/finance.mdへの参照を見て、そのファイルだけを読み取るためにbashを呼び出します。sales.mdとproduct.mdのファイルはファイルシステムに残り、必要になるまでコンテキストトークンをゼロ消費します。このファイルシステムベースのモデルがプログレッシブディスクロージャーを可能にします。Claudeは各タスクが必要とするものを正確にナビゲートし、選択的にロードできます。

技術アーキテクチャの完全な詳細については、Skills概要のSkillの仕組みを参照してください。

MCPツール参照

SkillがMCP（Model Context Protocol）ツールを使用する場合、「ツールが見つかりません」エラーを避けるために、常に完全修飾ツール名を使用してください。

形式：ServerName:tool_name

例：

BigQuery:bigquery_schemaツールを使用してテーブルスキーマを取得します。
GitHub:create_issueツールを使用してイシューを作成します。

ここで：

• BigQueryとGitHubはMCPサーバー名
• bigquery_schemaとcreate_issueはそれらのサーバー内のツール名

サーバープレフィックスがないと、特に複数のMCPサーバーが利用可能な場合、Claudeはツールを見つけられない可能性があります。

ツールがインストールされていると仮定しない

パッケージが利用可能であると仮定しないでください：

**悪い例：インストールを仮定**：
「pdfライブラリを使用してファイルを処理してください。」

**良い例：依存関係を明示**：
「必要なパッケージをインストール：`pip install pypdf`

次に使用：
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

技術的な注意事項

YAMLフロントマターの要件

SKILL.mdのフロントマターには、特定の検証ルールを持つnameとdescriptionフィールドが必要です：

• name：最大64文字、小文字/数字/ハイフンのみ、XMLタグなし、予約語なし
• description：最大1024文字、空でないこと、XMLタグなし

完全な構造の詳細については、Skills概要を参照してください。

トークン予算

最適なパフォーマンスのために、SKILL.mdの本文を500行未満に保ってください。コンテンツがこれを超える場合は、前述のプログレッシブディスクロージャーパターンを使用して別のファイルに分割してください。アーキテクチャの詳細については、Skills概要を参照してください。

効果的なSkillのチェックリスト

Skillを共有する前に、以下を確認してください：

コア品質

• 説明が具体的でキーワードを含んでいる
• 説明にSkillが何をするかといつ使用するかの両方が含まれている
• SKILL.mdの本文が500行未満
• 追加の詳細は別のファイルにある（必要な場合）
• 時間に敏感な情報がない（または「古いパターン」セクションにある）
• 全体を通じて一貫した用語
• 例が抽象的ではなく具体的
• ファイル参照が1レベルの深さ
• プログレッシブディスクロージャーが適切に使用されている
• ワークフローに明確なステップがある

コードとスクリプト

• スクリプトがClaudeに問題を押し付けるのではなく解決する
• エラー処理が明示的で役立つ
• 「おまじない定数」がない（すべての値が正当化されている）
• 必要なパッケージが指示にリストされ、利用可能であることが確認されている
• スクリプトに明確なドキュメントがある
• Windowsスタイルのパスがない（すべてフォワードスラッシュ）
• 重要な操作に検証/確認ステップがある
• 品質が重要なタスクにフィードバックループが含まれている

テスト

• 少なくとも3つの評価が作成されている
• Haiku、Sonnet、Opusでテスト済み
• 実際の使用シナリオでテスト済み
• チームのフィードバックが組み込まれている（該当する場合）

次のステップ

• Agent Skillsを始める - 最初のSkillを作成
• Claude CodeでSkillsを使用 - Claude CodeでSkillを作成・管理
• Agent SDKでSkillsを使用 - TypeScriptとPythonでプログラム的にSkillを使用
• APIでSkillsを使用 - プログラム的にSkillをアップロード・使用