スキル作成のベストプラクティス

優れたスキルは簡潔で、よく構造化されており、実際の使用でテストされています。このガイドは、Claude が効果的にスキルを発見して使用できるスキルを作成するのに役立つ実践的な作成上の決定を提供します。

スキルの仕組みに関する概念的な背景については、スキルの概要を参照してください。

コア原則

簡潔さが重要

コンテキストウィンドウは公共の財産です。あなたのスキルは、Claude が知る必要があるすべてのものとコンテキストウィンドウを共有します。これには以下が含まれます：

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

スキル内のすべてのトークンに直接的なコストがあるわけではありません。起動時には、すべてのスキルからメタデータ（名前と説明）のみが事前にロードされます。Claude は、スキルが関連するようになったときにのみ 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 をパスを探索するロボットと考えてください：

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

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

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

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

• Claude Haiku (高速、経済的)：スキルは十分なガイダンスを提供していますか？
• Claude Sonnet (バランス型)：スキルは明確で効率的ですか？
• Claude Opus (強力な推論)：スキルは過度に説明していませんか？

Opus で完璧に機能するものは、Haiku ではより詳細が必要な場合があります。複数のモデルでスキルを使用する予定がある場合は、すべてのモデルで正常に機能する指示を目指してください。

スキル構造

命名規則

一貫した命名パターンを使用して、スキルを参照および議論しやすくします。スキル名に動名詞形 (動詞 + -ing) を使用することを検討してください。これはスキルが提供するアクティビティまたは機能を明確に説明します。

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
• スキルコレクション内の一貫性のないパターン

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

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

効果的な説明を書く

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

具体的で主要な用語を含めます。スキルが何をするか、いつ使用するかの特定のトリガー/コンテキストの両方を含めます。

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

効果的な例：

PDF 処理スキル：

description: PDF ファイルからテキストと表を抽出し、フォームに入力し、ドキュメントをマージします。PDF ファイル、フォーム、またはドキュメント抽出について言及されている場合に使用します。

Excel 分析スキル：

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

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

description: git diff を分析してコミットメッセージを生成します。ユーザーがコミットメッセージの作成を支援するよう求めるか、ステージされた変更をレビューする場合に使用します。

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

description: ドキュメントを支援します

description: データを処理します

description: ファイルで何かをします

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

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

実践的なガイダンス：

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

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

基本的なスキルは、メタデータと指示を含む SKILL.md ファイルのみで始まります：

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

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

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 処理

## クイックスタート

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：ドメイン固有の組織

複数のドメインを持つスキルの場合、関連のないコンテキストのロードを避けるためにドメイン別にコンテンツを整理します。ユーザーが売上指標について質問する場合、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 リファレンス

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

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

## コアメソッド
...

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

このファイルシステムベースのアーキテクチャがプログレッシブディスクロージャーを有効にする方法の詳細については、以下の「詳細」セクションのランタイム環境を参照してください。

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

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

複雑な操作を明確で順序立ったステップに分割します。特に複雑なワークフローの場合は、Claude が応答にコピーして進行状況をチェックできるチェックリストを提供します。

例 1：研究合成ワークフロー (コードなしのスキル)：

## 研究合成ワークフロー

このチェックリストをコピーして進行状況を追跡します：

```
研究の進行状況：
- [ ] ステップ 1：すべてのソースドキュメントを読む
- [ ] ステップ 2：主要なテーマを特定する
- [ ] ステップ 3：主張をクロスリファレンスする
- [ ] ステップ 4：構造化された要約を作成する
- [ ] ステップ 5：引用を確認する
```

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

`sources/` ディレクトリ内の各ドキュメントを確認します。主な議論と支持する証拠に注意してください。

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

ソース全体のパターンを探します。どのテーマが繰り返し現れますか？ソースが同意または不同意する場所はどこですか？

**ステップ 3：主張をクロスリファレンスする**

各主要な主張について、ソース資料に現れることを確認します。各ポイントをサポートするソースに注意してください。

**ステップ 4：構造化された要約を作成する**

テーマ別に調査結果を整理します。以下を含めます：
- 主な主張
- ソースからの支持する証拠
- 対立する見方 (ある場合)

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

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

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

例 2：PDF フォーム入力ワークフロー (コード付きスキル)：

## 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：スタイルガイド準拠 (コードなしのスキル)：

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

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

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

例 2：ドキュメント編集プロセス (コード付きスキル)：

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

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-08 で廃止)</summary>

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

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

古いパターンセクションは、メインコンテンツを散らかさずに履歴コンテキストを提供します。

一貫した用語を使用する

1 つの用語を選択して、スキル全体で使用します：

良い - 一貫性：

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

悪い - 一貫性がない：

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

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

一般的なパターン

テンプレートパターン

出力形式のテンプレートを提供します。厳密さのレベルをニーズに合わせます。

厳密な要件の場合 (API レスポンスやデータ形式など)：

## レポート構造

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

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

## エグゼクティブサマリー
[主な調査結果の 1 段落の概要]

## 主な調査結果
- サポートデータ付きの調査結果 1
- サポートデータ付きの調査結果 2
- サポートデータ付きの調査結果 3

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

柔軟なガイダンス (適応が有用な場合)：

## レポート構造

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

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

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

## 主な調査結果
[発見したものに基づいてセクションを適応させる]

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

必要に応じてセクションを調整します。

例パターン

スキルの出力品質が例を見ることに依存する場合は、通常のプロンプティングのように入出力ペアを提供します：

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

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

**例 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 を直接変更する
   - 各変更後に検証する
   - 完了時に再パックする

評価と反復

評価を最初に構築する

広範なドキュメントを作成する前に評価を作成します。 これにより、スキルが想像上のものではなく実際の問題を解決することを確認します。

評価駆動開発：

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

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

評価構造：

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

Claude を使用してスキルを反復的に開発する

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

新しいスキルを作成する：

1. スキルなしでタスクを完了する： Claude A と通常のプロンプティングを使用して問題を解決します。作業を進めるにつれて、自然にコンテキストを提供し、設定を説明し、手続き知識を共有します。繰り返し提供する情報に注意してください。

2. 再利用可能なパターンを特定する： タスクを完了した後、再利用可能なコンテキストを特定します。

   例： BigQuery 分析を実行した場合、テーブル名、フィールド定義、フィルタリングルール (「常にテストアカウントを除外」など)、および一般的なクエリパターンを提供した可能性があります。

3. Claude A にスキルを作成するよう依頼する： 「このパターンをキャプチャするスキルを作成してください。テーブルスキーマ、命名規則、テストアカウントをフィルタリングするルールを含めます。」

   Claude モデルはスキル形式と構造をネイティブに理解しています。スキルを作成するために特別なシステムプロンプトや「スキル作成」スキルは必要ありません。Claude にスキルを作成するよう依頼するだけで、適切なフロントマターと本体コンテンツを含む適切に構造化された SKILL.md コンテンツが生成されます。

4. 簡潔性をレビューする： Claude A が不要な説明を追加していないか確認します。「Claude が勝利率が何を意味するかを既に知っているので、勝利率についての説明を削除してください。」と聞いてください。

5. 情報アーキテクチャを改善する： Claude A にコンテンツをより効果的に整理するよう依頼します。例えば：「テーブルスキーマを別の参照ファイルに整理してください。後で更多のテーブルを追加する可能性があります。」

6. 同様のタスクでテストする： スキルを Claude B (スキルがロードされた新しいインスタンス) で関連する使用例に使用します。Claude B が正しい情報を見つけ、ルールを正しく適用し、タスクを正常に処理するかどうかを観察します。

7. 観察に基づいて反復する： Claude B が何かを逃したり、苦労したりした場合、具体的な情報を持って Claude A に戻ります：「Claude がこのスキルを使用したとき、Q4 の日付でフィルタリングするのを忘れました。日付フィルタリングパターンについてセクションを追加する必要がありますか？」

既存のスキルを反復する：

同じ階層パターンは、スキルを改善するときに続きます。以下の間を交互に行います：

• Claude A と協力する (スキルを改善するのに役立つエキスパート)
• Claude B でテストする (スキルを使用して実際の作業を実行するエージェント)
• Claude B の動作を観察する し、Claude A に洞察を戻す

1. 実際のワークフローでスキルを使用する： テストシナリオではなく、実際のタスクで Claude B (スキルがロードされた状態) を使用します

2. Claude B の動作を観察する： どこで苦労し、成功し、または予期しない選択をするかに注意してください

   観察例： 「Claude B に地域別売上レポートを求めたとき、クエリを作成しましたが、スキルがこのルールについて言及しているにもかかわらず、テストアカウントをフィルタリングするのを忘れました。」

3. 改善のために Claude A に戻る： 現在の SKILL.md を共有し、観察したことを説明します。「Claude B がこのスキルを使用したとき、地域別レポートを求めたときにテストアカウントをフィルタリングするのを忘れました。スキルはフィルタリングについて言及していますが、十分に目立たないのかもしれません。」

4. Claude A の提案をレビューする： Claude A は、ルールをより目立つようにするために再編成を提案するか、「常にフィルタリング」の代わりに「フィルタリングする必要があります」のような強い言語を使用するか、またはワークフローセクションを再構成することを提案する可能性があります。

5. 変更を適用してテストする： Claude A の改善でスキルを更新し、同様のリクエストで Claude B で再度テストします

6. 使用に基づいて繰り返す： 新しいシナリオに遭遇するにつれてこの観察-改善-テストサイクルを続けます。各反復は、仮定ではなく観察されたエージェント動作に基づいてスキルを改善します。

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

1. スキルをチームメイトと共有し、その使用を観察します
2. 「スキルは予想通りにアクティブになりますか？指示は明確ですか？何が不足していますか？」と聞いてください
3. フィードバックを組み込んで、独自の使用パターンの盲点に対処します

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

Claude がスキルをナビゲートする方法を観察する

スキルを反復するにつれて、Claude が実際にそれらを使用する方法に注意を払ってください。以下に注意してください：

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

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

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

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
```

スキャンされた PDF で OCR が必要な場合は、代わりに pdf2image と pytesseract を使用します。」

詳細：実行可能なコード付きスキル

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

解決する、逃げない

スキルのスクリプトを作成するときは、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 はフィールドの位置とタイプを視覚的に確認できます

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

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

Claude が複雑でオープンエンドなタスクを実行する場合、エラーが発生する可能性があります。「計画-検証-実行」パターンは、Claude に最初に構造化形式で計画を作成させ、その後スクリプトで計画を検証してから実行することで、エラーを早期に検出します。

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

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

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

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

使用する場合： バッチ操作、破壊的な変更、複雑な検証ルール、高リスク操作。

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

パッケージの依存関係

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

• claude.ai： npm と PyPI からパッケージをインストールでき、GitHub リポジトリからプルできます
• Claude API： ネットワークアクセスがなく、ランタイムパッケージのインストールもできません

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

ランタイム環境

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

これがオーサリングに与える影響：

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

1. メタデータが事前読み込みされる： スタートアップ時に、すべてのスキルの YAML フロントマターから名前と説明がシステムプロンプトに読み込まれます
2. ファイルはオンデマンドで読み込まれる： Claude は bash Read ツールを使用して、必要に応じてファイルシステムから SKILL.md および他のファイルにアクセスします
3. スクリプトは効率的に実行される： ユーティリティスクリプトは、その完全な内容をコンテキストに読み込むことなく、bash 経由で実行できます。スクリプトの出力のみがトークンを消費します
4. 大きなファイルのコンテキストペナルティなし： リファレンスファイル、データ、またはドキュメントは、実際に読み込まれるまでコンテキストトークンを消費しません

• ファイルパスが重要： Claude はスキルディレクトリをファイルシステムのようにナビゲートします。バックスラッシュではなく、フォワードスラッシュ（reference/guide.md）を使用してください
• ファイルに説明的な名前を付ける： doc2.md ではなく、form_validation_rules.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 はナビゲートして、各タスクが必要とするものを正確に選択的に読み込むことができます。

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

MCP ツール参照

スキルが 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 タグなし

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

トークン予算

最適なパフォーマンスのために SKILL.md 本体を 500 行以下に保ちます。コンテンツがこれを超える場合は、前述の段階的な開示パターンを使用して、別のファイルに分割します。アーキテクチャの詳細については、スキル概要を参照してください。

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

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

コア品質

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

コードとスクリプト

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

テスト

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

次のステップ