Agent Skills

Skillsを使う理由

Skillsは、再利用可能なファイルシステムベースのリソースであり、Claudeにドメイン固有の専門知識を提供します：ワークフロー、コンテキスト、ベストプラクティスにより、汎用エージェントをスペシャリストに変えます。プロンプト（単発タスクのための会話レベルの指示）とは異なり、Skillsはオンデマンドで読み込まれ、複数の会話にわたって同じガイダンスを繰り返し提供する必要がなくなります。

主なメリット：

• Claudeの専門化：ドメイン固有のタスクに合わせて能力をカスタマイズ
• 繰り返しの削減：一度作成すれば自動的に使用
• 能力の組み合わせ：Skillsを組み合わせて複雑なワークフローを構築

Skillsの使い方

Anthropicは、一般的なドキュメントタスク（PowerPoint、Excel、Word、PDF）用のビルド済みAgent Skillsを提供しており、独自のカスタムSkillsを作成することもできます。どちらも同じように動作します。Claudeはリクエストに関連する場合に自動的にそれらを使用します。

ビルド済みAgent Skillsは、claude.aiおよびClaude APIのすべてのユーザーが利用できます。完全なリストについては、以下の利用可能なSkillsセクションをご覧ください。

カスタムSkillsでは、ドメインの専門知識と組織の知識をパッケージ化できます。Claudeの製品全体で利用可能です：Claude Codeで作成、API経由でアップロード、またはclaude.aiの設定で追加できます。

Skillsの仕組み

SkillsはClaudeのVM環境を活用して、プロンプトだけでは不可能な機能を提供します。Claudeはファイルシステムアクセスを持つ仮想マシンで動作するため、Skillsは指示、実行可能なコード、参考資料を含むディレクトリとして存在でき、新しいチームメンバーのために作成するオンボーディングガイドのように整理されています。

このファイルシステムベースのアーキテクチャにより、段階的開示が可能になります：Claudeは事前にコンテキストを消費するのではなく、必要に応じて段階的に情報を読み込みます。

3種類のSkillコンテンツ、3段階の読み込み

Skillsには3種類のコンテンツを含めることができ、それぞれ異なるタイミングで読み込まれます：

レベル1：メタデータ（常に読み込み）

コンテンツタイプ：指示。SkillのYAMLフロントマターは検出情報を提供します：

---
name: pdf-processing
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.
---

Claudeは起動時にこのメタデータを読み込み、システムプロンプトに含めます。この軽量なアプローチにより、コンテキストのペナルティなしに多くのSkillsをインストールできます。Claudeは各Skillの存在と使用タイミングのみを把握します。

レベル2：指示（トリガー時に読み込み）

コンテンツタイプ：指示。SKILL.mdの本文には手続き的な知識が含まれます：ワークフロー、ベストプラクティス、ガイダンス：

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

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

For advanced form filling, see [FORMS.md](FORMS.md).

Skillの説明に一致するリクエストを行うと、Claudeはbash経由でファイルシステムからSKILL.mdを読み取ります。その時点で初めてこのコンテンツがコンテキストウィンドウに入ります。

レベル3：リソースとコード（必要に応じて読み込み）

コンテンツタイプ：指示、コード、リソース。Skillsには追加の資料をバンドルできます：

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

指示：追加のマークダウンファイル（FORMS.md、REFERENCE.md）には、専門的なガイダンスとワークフローが含まれます

コード：実行可能なスクリプト（fill_form.py、validate.py）をClaudeがbash経由で実行します。スクリプトはコンテキストを消費せずに決定論的な操作を提供します

リソース：データベーススキーマ、APIドキュメント、テンプレート、例などの参考資料

Claudeは参照された場合にのみこれらのファイルにアクセスします。ファイルシステムモデルにより、各コンテンツタイプには異なる強みがあります：柔軟なガイダンスのための指示、信頼性のためのコード、事実の検索のためのリソース。

段階的開示により、任意の時点で関連するコンテンツのみがコンテキストウィンドウを占有します。

Skillsアーキテクチャ

Skillsは、Claudeがファイルシステムアクセス、bashコマンド、コード実行機能を持つコード実行環境で動作します。次のように考えてください：Skillsは仮想マシン上のディレクトリとして存在し、Claudeはコンピュータ上でファイルを操作するのと同じbashコマンドを使用してそれらとやり取りします。

ClaudeがSkillコンテンツにアクセスする方法：

Skillがトリガーされると、Claudeはbashを使用してファイルシステムからSKILL.mdを読み取り、その指示をコンテキストウィンドウに取り込みます。それらの指示が他のファイル（FORMS.mdやデータベーススキーマなど）を参照している場合、Claudeは追加のbashコマンドを使用してそれらのファイルも読み取ります。指示が実行可能なスクリプトに言及している場合、Claudeはbash経由でそれらを実行し、出力のみを受け取ります（スクリプトコード自体はコンテキストに入りません）。

このアーキテクチャが可能にすること：

オンデマンドファイルアクセス：Claudeは各特定のタスクに必要なファイルのみを読み取ります。Skillには数十の参照ファイルを含めることができますが、タスクに必要なのが営業スキーマだけであれば、Claudeはそのファイルだけを読み込みます。残りはファイルシステム上に残り、トークンを一切消費しません。

効率的なスクリプト実行：Claudeがvalidate_form.pyを実行する際、スクリプトのコードはコンテキストウィンドウに読み込まれません。スクリプトの出力（「Validation passed」や特定のエラーメッセージなど）のみがトークンを消費します。これにより、Claudeが同等のコードをその場で生成するよりもスクリプトの方がはるかに効率的です。

バンドルコンテンツに実質的な制限なし：ファイルはアクセスされるまでコンテキストを消費しないため、Skillsには包括的なAPIドキュメント、大規模なデータセット、広範な例、または必要な参考資料を含めることができます。使用されないバンドルコンテンツにはコンテキストペナルティがありません。

このファイルシステムベースのモデルが段階的開示を機能させます。Claudeはオンボーディングガイドの特定のセクションを参照するようにSkillをナビゲートし、各タスクに必要なものに正確にアクセスします。

例：PDF処理スキルの読み込み

ClaudeがPDF処理スキルを読み込んで使用する方法は以下の通りです：

1. 起動時：システムプロンプトに含まれる内容：PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. ユーザーリクエスト：「このPDFからテキストを抽出して要約してください」
3. Claudeが呼び出す：bash: read pdf-skill/SKILL.md → 指示がコンテキストに読み込まれる
4. Claudeが判断する：フォーム入力は不要なので、FORMS.mdは読み取られない
5. Claudeが実行する：SKILL.mdの指示を使用してタスクを完了

この図は以下を示しています：

1. システムプロンプトとスキルメタデータが事前に読み込まれたデフォルト状態
2. Claudeがbash経由でSKILL.mdを読み取ることでスキルをトリガー
3. Claudeが必要に応じてFORMS.mdなどの追加バンドルファイルをオプションで読み取る
4. Claudeがタスクを進める

この動的な読み込みにより、関連するスキルコンテンツのみがコンテキストウィンドウを占有します。

Skillsが動作する場所

SkillsはClaudeのエージェント製品全体で利用できます：

Claude API

Claude APIは、ビルド済みAgent SkillsとカスタムSkillsの両方をサポートしています。どちらも同じように動作します：コード実行ツールとともにcontainerパラメータで関連するskill_idを指定します。

前提条件：API経由でSkillsを使用するには、3つのベータヘッダーが必要です：

• code-execution-2025-08-25 - Skillsはコード実行コンテナで動作します
• skills-2025-10-02 - Skills機能を有効にします
• files-api-2025-04-14 - コンテナへのファイルのアップロード/ダウンロードに必要です

ビルド済みAgent Skillsはskill_id（例：pptx、xlsx）を参照して使用するか、Skills API（/v1/skillsエンドポイント）経由で独自のSkillsを作成してアップロードします。カスタムSkillsは組織全体で共有されます。

詳細については、Claude APIでSkillsを使用するをご覧ください。

Claude Code

Claude CodeはカスタムSkillsのみをサポートしています。

カスタムSkills：SKILL.mdファイルを含むディレクトリとしてSkillsを作成します。Claudeは自動的にそれらを検出して使用します。

Claude CodeのカスタムSkillsはファイルシステムベースであり、APIアップロードは不要です。

詳細については、Claude CodeでSkillsを使用するをご覧ください。

Claude Agent SDK

Claude Agent SDKは、ファイルシステムベースの設定を通じてカスタムSkillsをサポートしています。

カスタムSkills：.claude/skills/にSKILL.mdファイルを含むディレクトリとしてSkillsを作成します。allowed_tools設定に"Skill"を含めることでSkillsを有効にします。

Agent SDKのSkillsは、SDKの実行時に自動的に検出されます。

詳細については、SDKのAgent Skillsをご覧ください。

Claude.ai

Claude.aiは、ビルド済みAgent SkillsとカスタムSkillsの両方をサポートしています。

ビルド済みAgent Skills：これらのSkillsは、ドキュメントを作成する際にバックグラウンドで既に動作しています。Claudeはセットアップなしでそれらを使用します。

カスタムSkills：設定 > 機能からzipファイルとして独自のSkillsをアップロードします。コード実行が有効なPro、Max、Team、Enterpriseプランで利用可能です。カスタムSkillsは各ユーザー個別のものであり、組織全体で共有されず、管理者による一元管理もできません。

Claude.aiでのSkillsの使用について詳しくは、Claudeヘルプセンターの以下のリソースをご覧ください：

• Skillsとは？
• ClaudeでSkillsを使用する
• カスタムSkillsの作成方法
• Skillsを使ってClaudeにあなたの作業方法を教える

Skillの構造

すべてのSkillには、YAMLフロントマターを含むSKILL.mdファイルが必要です：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

必須フィールド：nameとdescription

フィールド要件：

name：

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

description：

• 空でないこと
• 最大1024文字
• XMLタグを含めることはできません

descriptionには、Skillが何をするかとClaudeがいつそれを使用すべきかの両方を含める必要があります。完全な作成ガイダンスについては、ベストプラクティスガイドをご覧ください。

セキュリティに関する考慮事項

信頼できるソース（自分で作成したもの、またはAnthropicから入手したもの）のSkillsのみを使用することを強くお勧めします。Skillsは指示とコードを通じてClaudeに新しい機能を提供しますが、これが強力である一方で、悪意のあるSkillがClaudeにSkillの記載された目的と一致しない方法でツールを呼び出したりコードを実行したりするよう指示する可能性があることも意味します。

主なセキュリティ上の考慮事項：

• 徹底的な監査：Skillにバンドルされているすべてのファイルを確認してください：SKILL.md、スクリプト、画像、その他のリソース。予期しないネットワーク呼び出し、ファイルアクセスパターン、またはSkillの記載された目的と一致しない操作などの異常なパターンを探してください
• 外部ソースはリスクが高い：外部URLからデータを取得するSkillsは特にリスクがあります。取得されたコンテンツに悪意のある指示が含まれている可能性があるためです。信頼できるSkillsであっても、外部依存関係が時間の経過とともに変更された場合、侵害される可能性があります
• ツールの悪用：悪意のあるSkillsは、ツール（ファイル操作、bashコマンド、コード実行）を有害な方法で呼び出す可能性があります
• データの露出：機密データにアクセスできるSkillsは、外部システムに情報を漏洩するように設計されている可能性があります
• ソフトウェアのインストールと同様に扱う：信頼できるソースからのSkillsのみを使用してください。機密データや重要な操作にアクセスできる本番システムにSkillsを統合する場合は特に注意してください

利用可能なSkills

ビルド済みAgent Skills

以下のビルド済みAgent Skillsがすぐに使用できます：

• PowerPoint (pptx)：プレゼンテーションの作成、スライドの編集、プレゼンテーションコンテンツの分析
• Excel (xlsx)：スプレッドシートの作成、データ分析、チャート付きレポートの生成
• Word (docx)：ドキュメントの作成、コンテンツの編集、テキストの書式設定
• PDF (pdf)：フォーマットされたPDFドキュメントとレポートの生成

これらのSkillsはClaude APIとclaude.aiで利用できます。APIでの使用を開始するには、クイックスタートチュートリアルをご覧ください。

カスタムSkillsの例

カスタムSkillsの完全な例については、Skills cookbookをご覧ください。

制限事項と制約

これらの制限事項を理解することで、Skillsのデプロイメントを効果的に計画できます。

クロスサーフェスの可用性

カスタムSkillsはサーフェス間で同期されません。1つのサーフェスにアップロードされたSkillsは、他のサーフェスでは自動的に利用できません：

• Claude.aiにアップロードされたSkillsは、APIに別途アップロードする必要があります
• API経由でアップロードされたSkillsは、Claude.aiでは利用できません
• Claude CodeのSkillsはファイルシステムベースであり、Claude.aiとAPIの両方から独立しています

使用したい各サーフェスごとに、Skillsを個別に管理してアップロードする必要があります。

共有スコープ

Skillsは使用場所によって異なる共有モデルを持っています：

• Claude.ai：個人ユーザーのみ。各チームメンバーが個別にアップロードする必要があります
• Claude API：ワークスペース全体。すべてのワークスペースメンバーがアップロードされたSkillsにアクセスできます
• Claude Code：個人用（~/.claude/skills/）またはプロジェクトベース（.claude/skills/）。Claude Code Plugins経由で共有することもできます

Claude.aiは現在、カスタムSkillsの一元的な管理者管理や組織全体への配布をサポートしていません。

ランタイム環境の制約

Skillで利用可能な正確なランタイム環境は、使用する製品サーフェスによって異なります。

• Claude.ai：
  • ネットワークアクセスは可変：ユーザー/管理者の設定に応じて、Skillsは完全、部分的、またはネットワークアクセスなしの場合があります。詳細については、ファイルの作成と編集サポート記事をご覧ください。
• Claude API：
  • ネットワークアクセスなし：Skillsは外部API呼び出しやインターネットへのアクセスができません
  • ランタイムパッケージのインストール不可：プリインストールされたパッケージのみ利用可能です。実行中に新しいパッケージをインストールすることはできません。
  • 事前設定された依存関係のみ：利用可能なパッケージのリストについては、コード実行ツールのドキュメントをご確認ください
• Claude Code：
  • 完全なネットワークアクセス：Skillsはユーザーのコンピュータ上の他のプログラムと同じネットワークアクセスを持ちます
  • グローバルパッケージのインストールは非推奨：ユーザーのコンピュータに干渉しないよう、Skillsはパッケージをローカルにのみインストールすべきです

これらの制約内で動作するようにSkillsを計画してください。

次のステップ