apply-anthropic-skill-best-practices

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

Anthropic 公式のスキル作成ベストプラクティスをスキルに適用します。

優れたスキルは簡潔で、構成が整っており、実際の使用環境でテストされています。このガイドでは、Claude がスキルを効果的に見つけて使えるようにするための、実践的な作成方法を紹介します。

基本原則

スキルのメタデータ

スキル内のすべてのトークンが、直ちにコストになるわけではありません。起動時には、すべてのスキルのメタデータ（名前と説明）のみが事前に読み込まれます。Claude は、スキルが関連するようになったときにのみ SKILL.md を読み込み、追加ファイルは必要に応じて読み込みます。ただし、SKILL.md を簡潔に保つことは依然として重要です。Claude が読み込むと、その中のすべてのトークンが会話履歴やほかのコンテキストと競合するためです。

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

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

モデルごとのテスト項目：

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

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

スキルの構成

**YAML Frontmatter**：SKILL.md のフロントマターでサポートされるフィールドは 2 つです。

• name - スキルの人間が読みやすい名前（最大 64 文字）

• description - スキルの機能と使用する場面を説明する 1 行の説明（最大 1024 文字）

  スキルの構成の詳細は、スキルの概要を参照してください。

命名規則

スキルを参照したり説明したりしやすくするために、一貫性のある命名パターンを使ってください。スキル名には動名詞形（動詞 + -ing）を使うことをおすすめします。スキルが提供する活動や機能を明確に表せるためです。

適切な命名例（動名詞形）：

• 「PDF の処理」
• 「スプレッドシートの分析」
• 「データベースの管理」
• 「コードのテスト」
• 「ドキュメントの作成」

許容される代替案：

• 名詞句：「PDF 処理」「スプレッドシート分析」
• 行動指向：「PDF を処理する」「スプレッドシートを分析する」

避けるべき名前：

• 曖昧な名前：「ヘルパー」「ユーティリティ」「ツール」
• 汎用的すぎる名前：「ドキュメント」「データ」「ファイル」
• スキルコレクション内で一貫性のないパターン

一貫性のある命名により、次のことが容易になります。

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

効果的な説明を書く

description フィールドはスキルの発見に役立つため、スキルの機能と使用する場面の両方を含めてください。

**必ず三人称で書いてください**。説明はシステムプロンプトに挿入されます。一貫性のない視点で書くと、発見に支障をきたす場合があります。

• 適切な例：「Excel ファイルを処理してレポートを生成します」
• 避ける例：「Excel ファイルの処理をお手伝いできます」
• 避ける例：「Excel ファイルを処理するために使えます」

具体的に書き、重要なキーワードを含めてください。スキルの機能に加え、使用するきっかけや状況を具体的に含めてください。

各スキルに設定できる説明フィールドは 1 つだけです。説明はスキルの選択において重要です。Claude は、利用可能な 100 以上のスキルから適切なスキルを選ぶために、この説明を使います。Claude がこのスキルを選ぶべき場面を判断できるだけの詳細を説明に含め、SKILL.md の残りの部分で実装の詳細を記述してください。

効果的な例：

PDF 処理スキル：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Excel 分析スキル：

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

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

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

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

description: Helps with documents

description: Processes data

description: Does stuff with files

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

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

実践的なガイダンス：

• 最適なパフォーマンスを得るため、SKILL.md の本文は 500 行未満にします
• この上限に近づいたら、内容を別々のファイルに分割します
• 以下のパターンを使って、手順、コード、リソースを効果的に整理します

視覚的な概要：シンプルな構成から複雑な構成へ

基本的な Skill は、メタデータと指示を含む SKILL.md ファイルだけで構成されます。

Skill が大きくなるにつれて、必要なときだけ Claude が読み込む追加コンテンツをまとめて含めることができます。

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

pdf/
├── SKILL.md              # Main instructions (loaded when triggered)
├── FORMS.md              # Form-filling guide (loaded as needed)
├── reference.md          # API reference (loaded as needed)
├── examples.md           # Usage examples (loaded as needed)
└── scripts/
    ├── analyze_form.py   # Utility script (executed, not loaded)
    ├── fill_form.py      # Form filling script
    └── validate.py       # Validation script

パターン 1：参照資料を含む概要ガイド

---
name: PDF Processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

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

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude は必要なときだけ FORMS.md、REFERENCE.md、または EXAMPLES.md を読み込みます。

パターン 2：ドメイン別の構成

複数のドメインを扱う Skill では、無関係なコンテキストを読み込まないよう、ドメインごとにコンテンツを整理します。ユーザーが営業指標について尋ねた場合、Claude が読む必要があるのは営業関連のスキーマだけで、財務やマーケティングのデータは必要ありません。これにより、トークンの使用量を抑え、コンテキストを関連する内容に絞れます。

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

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

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

基本的な内容を示し、応用的な内容にリンクします。

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

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

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

別の参照ファイルから参照されているファイルは、Claude が一部しか読み込まない場合があります。ネストされた参照に遭遇すると、ファイル全体を読む代わりに head -100 のようなコマンドで内容をプレビューすることがあり、情報が不完全になる可能性があります。

SKILL.md からの参照は 1 階層にとどめてください。必要なときに Claude がファイル全体を読めるよう、すべての参照ファイルから SKILL.md に直接リンクしてください。

悪い例：深すぎる構造：

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

良い例：1 階層の構造：

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

長い参照ファイルには目次を付ける

100 行を超える参照ファイルには、先頭に目次を付けてください。これにより、一部しか読み込めない場合でも、Claude は利用できる情報の全体像を把握できます。

例：

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

これにより、Claude は必要に応じてファイル全体を読んだり、特定のセクションに移動したりできます。

このファイルシステムベースのアーキテクチャが段階的な情報開示をどのように実現するかについては、以下の応用セクションにある「実行環境」をご覧ください。

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

複雑なタスクにはワークフローを使う

複雑な操作を、明確で順序立てた手順に分割します。特に複雑なワークフローでは、Claude が回答にコピーし、進行に合わせてチェックできるチェックリストを用意してください。

例 1：調査内容の統合ワークフロー（コードを使わない Skill の場合）：

## Research synthesis workflow

Copy this checklist and track your progress:

```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

この例では、コードを必要としない分析タスクにワークフローを適用する方法を示しています。チェックリストのパターンは、複雑で複数の手順からなるあらゆるプロセスで使えます。

例 2：PDF フォーム入力ワークフロー（コードを使う Skill の場合）：

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```

**Step 1: Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

This extracts form fields and their locations, saving to `fields.json`.

**Step 2: Create field mapping**

Edit `fields.json` to add values for each field.

**Step 3: Validate mapping**

Run: `python scripts/validate_fields.py fields.json`

Fix any validation errors before continuing.

**Step 4: Fill the form**

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

**Step 5: Verify output**

Run: `python scripts/verify_output.py output.pdf`

If verification fails, return to Step 2.

明確な手順を設けることで、Claude が重要な検証を省略するのを防げます。チェックリストを使うと、複数の手順からなるワークフローの進捗を Claude とあなたの両方が確認できます。

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

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

このパターンにより、出力の品質が大幅に向上します。

例 1：スタイルガイドへの準拠（コードを使わない Skill の場合）：

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

この例では、スクリプトではなく参照ドキュメントを使った検証ループのパターンを示しています。「バリデーター」は STYLE_GUIDE.md であり、Claude はそれを読み、内容を比較してチェックを行います。

例 2：ドキュメント編集プロセス（コードを使う Skill の場合）：

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document

検証ループを使うと、エラーを早期に発見できます。

コンテンツのガイドライン

時間の経過で古くなる情報を避ける

古くなる情報は含めないでください。

悪い例：時間の経過で古くなる情報（誤りになる可能性があります）：

If you're doing this before August 2025, use the old API.
After August 2025, use the new API.

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

## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>

古いパターンのセクションを設けると、メインコンテンツを煩雑にせず、過去の背景を伝えられます。

用語を統一する

用語を 1 つ選び、Skill 全体で統一して使ってください。

良い例：統一されている：

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

悪い例：統一されていない：

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

用語を統一すると、Claude が指示を理解して従いやすくなります。

一般的なパターン

テンプレートのパターン

出力形式のテンプレートを用意します。必要な厳密さに合わせて指定してください。

厳密な要件がある場合（API レスポンスやデータ形式など）：

## Report structure

ALWAYS use this exact template structure:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

柔軟なガイダンスを示す場合（状況に合わせた調整が役立つとき）：

## Report structure

Here is a sensible default format, but use your best judgment based on the analysis:

```markdown
# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]
```

Adjust sections as needed for the specific analysis type.

例のパターン

出力の品質が例の参照に左右される Skill では、通常のプロンプトと同様に入力と出力のペアを示してください。

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling

- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```

Follow this style: type(scope): brief description, then detailed explanation.

例を示すと、説明だけの場合よりも、望ましいスタイルや詳細さを Claude が理解しやすくなります。

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

判断が必要なポイントごとに、Claude に手順を示します。

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete

ワークフローが大規模になったり、手順が多く複雑になったりした場合は、別ファイルに分け、タスクに応じて適切なファイルを読むよう Claude に指示することを検討してください。 ## 評価と反復

まず評価を作成する

詳細なドキュメントを書く前に、評価を作成してください。 これにより、想像上の問題を文書化するのではなく、Skill が実際の問題を解決できるようになります。

評価主導の開発：

1. ギャップを特定する：Skill を使わずに、代表的なタスクで Claude を実行します。具体的な失敗や不足しているコンテキストを記録します
2. 評価を作成する：これらのギャップを検証する3つのシナリオを作成します
3. ベースラインを確立する：Skill を使わない場合の Claude のパフォーマンスを測定します
4. 最小限の指示を書く：ギャップを埋め、評価に合格するために必要な内容だけを作成します
5. 反復する：評価を実行し、ベースラインと比較して改善します

このアプローチにより、実現するかどうかも分からない要件を先回りして想定するのではなく、実際の問題を解決できます。

評価の構成：

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

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

Claude と反復しながら Skills を開発する

最も効果的な Skill の開発プロセスには、Claude 自身を活用します。あるインスタンスの Claude（「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 の作成を手伝ってもらうために、特別なシステムプロンプトや「スキルを書くスキル」は必要ありません。Claude に Skill の作成を依頼するだけで、適切なフロントマターと本文を含む、正しく構成された SKILL.md が生成されます。

4. 簡潔さを確認する：Claude A が不要な説明を追加していないか確認します。「勝率の意味についての説明を削除してください。Claude はすでに知っています」と依頼します。

5. 情報アーキテクチャを改善する：Claude A に、内容をより効果的に整理するよう依頼します。たとえば、「テーブルスキーマを別のリファレンスファイルにまとめてください。今後、テーブルを追加する可能性があります」と依頼します。

6. 類似タスクでテストする：Skill を読み込んだ新しいインスタンスである Claude B を使い、関連するユースケースで Skill をテストします。Claude B が適切な情報を見つけ、ルールを正しく適用し、タスクを成功裏に処理できるか観察します。

7. 観察結果に基づいて反復する：Claude B が苦戦したり、何かを見落としたりした場合は、具体的な内容を添えて Claude A に戻ります。「Claude がこの Skill を使ったとき、第4四半期の日付でフィルタリングするのを忘れました。日付フィルタリングのパターンについてのセクションを追加すべきでしょうか？」

既存の Skills を反復的に改善する：

Skills を改善する際も、同じ階層的なパターンを繰り返します。次の作業を交互に行います。

• Claude A と作業する（Skill の改善を支援するエキスパート）
• Claude B でテストする（Skill を使って実際の作業を行うエージェント）
• 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 システムでエラーを引き起こします。

あまりに多くの選択肢を提示しない

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

**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

応用: 実行可能なコードを含むスキル

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

先送りせず、解決する

スキル用のスクリプトを書く際は、Claude に先送りするのではなく、エラー条件を処理してください。

良い例: エラーを明示的に処理する:

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ''

悪い例: Claude に先送りする:

def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()

設定パラメータも同様に、根拠を示して文書化し、「ブードゥー定数」（Ousterhout の法則）を避けるべきです。適切な値がわからない場合、Claude はそれをどのように判断するのでしょうか？

良い例: 自己文書化:

# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3

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

TIMEOUT = 47  # Why 47?
RETRIES = 5   # Why 5?

ユーティリティスクリプトを用意する

Claude がスクリプトを作成できる場合でも、あらかじめ用意されたスクリプトには利点があります。

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

• 生成されたコードよりも信頼性が高い
• トークンを節約できる（コードをコンテキストに含める必要がありません）
• 時間を節約できる（コードの生成が不要です）
• 使用するたびに一貫性を保てる

上の図は、実行可能なスクリプトが指示ファイルと連携する仕組みを示しています。指示ファイル（forms.md）がスクリプトを参照しているため、Claude はスクリプトの内容をコンテキストに読み込まずに実行できます。

重要な違い：指示の中で、Claude が次のどちらを行うべきかを明確にしてください。

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

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

例：

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

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

Output format:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Check for overlapping bounding boxes

```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```

**fill_form.py**: Apply field values to PDF

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

視覚的に分析する

入力を画像としてレンダリングできる場合は、Claude に分析させます。

## Form layout analysis

1. Convert PDF to images:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

この例では、`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 が問題を修正しやすくなります。

パッケージの依存関係

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

• claude.ai：npm および PyPI からパッケージをインストールでき、GitHub リポジトリから取得できます
• Anthropic API：ネットワークにアクセスできず、実行時のパッケージインストールもできません

必要なパッケージを SKILL.md に記載し、コード実行ツールのドキュメントで利用可能かどうかを確認してください。

実行環境

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

作成時の注意点：

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

1. メタデータを事前に読み込み：起動時に、すべてのスキルの YAML frontmatter に記載された名前と説明がシステムプロンプトに読み込まれます
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 (overview, points to reference files)
└── reference/
    ├── finance.md (revenue metrics)
    ├── sales.md (pipeline data)
    └── product.md (usage analytics)

ユーザーが収益について尋ねると、Claude は SKILL.md を読み、reference/finance.md への参照を確認してから、bash を呼び出してそのファイルだけを読み込みます。sales.md と product.md はファイルシステム上に残り、必要になるまでコンテキストトークンを消費しません。このファイルシステムベースのモデルにより、段階的な情報開示が可能になります。Claude は各タスクで必要なファイルだけを選択して読み込み、移動できます。

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

MCP ツールの参照

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

形式：ServerName:tool_name

例：

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

内訳：

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

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

ツールがインストール済みだと決めつけない

パッケージが利用可能だと決めつけないでください。

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

技術上の注意事項

YAML frontmatter の要件

SKILL.md の frontmatter に含めるフィールドは、name（最大 64 文字）と description（最大 1024 文字）のみです。完全な構成の詳細については、スキルの概要を参照してください。

トークンの予算

最適なパフォーマンスを得るには、SKILL.md の本文を 500 行未満にしてください。これを超える場合は、前述の段階的な情報開示のパターンに従って、内容を別のファイルに分割します。アーキテクチャの詳細については、スキルの概要を参照してください。

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

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

コア品質

• 説明が具体的で、重要なキーワードが含まれている
• 説明に、Skill が行うことと、使用するタイミングの両方が含まれている
• SKILL.md の本文が500行未満である
• 必要に応じて、詳細を別ファイルに記載している
• 時間の経過で古くなる情報を含めていない（または「古いパターン」セクションに記載している）
• 用語が一貫している
• 例が抽象的ではなく具体的である
• ファイル参照が1階層以内である
• プログレッシブ・ディスクロージャーを適切に活用している
• ワークフローの手順が明確である

コードとスクリプト

• スクリプトが問題を解決しており、Claude に丸投げしていない
• エラー処理が明示的で、役に立つ
• 「根拠のない定数」がない（すべての値に根拠がある）
• 必要なパッケージが手順に記載され、利用可能であることを確認している
• スクリプトのドキュメントが明確である
• Windows 形式のパスを使用していない（すべてスラッシュ / を使用）
• 重要な操作に対する検証・確認手順がある
• 品質が重要なタスクにフィードバックループが含まれている

テスト

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