概要
Claude Agent Skills のアーキテクチャと利点を理解する。
Agent Skills は、Claude の機能を拡張するモジュール型の能力です。各 Skill は、指示、メタデータ、必要に応じて使うリソース(スクリプトやテンプレート)をまとめたもので、関連する場面で Claude が自動的に利用します。
Skills を使う理由
Skills は、ファイルシステムを基盤にした再利用可能なリソースです。ワークフロー、文脈、ベストプラクティスといった領域固有の知識を Claude に与え、汎用エージェントを専門家のように振る舞える状態へ近づけます。プロンプトが一度きりの会話レベルの指示であるのに対し、Skills は必要になった時点で読み込まれるため、複数の会話で同じ説明を何度も渡す必要がなくなります。
主な利点:
- Claude を専門化する: 特定領域のタスクに合わせて能力を調整できます
- 繰り返しを減らす: 一度作れば、自動的に再利用できます
- 能力を組み合わせる: 複数の Skills を組み合わせて複雑なワークフローを作れます
Note
Agent Skills のアーキテクチャと実運用での使い方を詳しく知りたい場合は、エンジニアリングブログ Equipping agents for the real world with Agent Skills を読んでください。
Skills の使い方
Anthropic は、PowerPoint、Excel、Word、PDF などの一般的なドキュメント作業向けに、事前構築済みの Agent Skills を提供しています。また、自分専用のカスタム Skills を作ることもできます。どちらも動作の仕組みは同じです。リクエストに関連すると Claude が判断したとき、自動的に利用されます。
事前構築済み Agent Skills は、claude.ai と Claude API のすべてのユーザーが利用できます。完全な一覧は、下の 利用可能な Skills セクションを参照してください。
カスタム Skills では、領域知識や組織内の知見をパッケージ化できます。Claude Code で作成したり、API 経由でアップロードしたり、claude.ai の設定から追加したりできます。
Note
はじめ方:
- 事前構築済み Agent Skills を使う場合: クイックスタートチュートリアルを参照し、API で PowerPoint、Excel、Word、PDF の Skills を使い始めてください
- カスタム Skills を作る場合: Agent Skills Cookbook を参照し、自分の Skills を作る方法を学んでください
Skills の仕組み
Skills は Claude の VM 環境を活用し、プロンプトだけでは実現しにくい能力を提供します。Claude はファイルシステムにアクセスできる仮想マシン上で動作します。そのため Skills は、指示、実行可能なコード、参照資料を含むディレクトリとして存在できます。これは、新しいチームメンバーに渡すオンボーディングガイドのように整理できます。
このファイルシステムベースのアーキテクチャにより、段階的開示が可能になります。Claude は最初からすべてをコンテキストに詰め込むのではなく、必要になった情報を段階的に読み込みます。
3 種類の Skill 内容と 3 段階の読み込み
Skills には 3 種類の内容を含めることができ、それぞれ読み込まれるタイミングが異なります。
レベル 1: メタデータ(常に読み込まれる)
内容の種類: 指示。Skill の YAML frontmatter は、Skill を発見するための情報を提供します。
---
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 など、専門的なガイダンスやワークフローを含む追加の Markdown ファイルです。
コード: fill_form.py や validate.py など、Claude が bash 経由で実行するスクリプトです。スクリプトはコンテキストを消費せず、決定的な処理を提供できます。
リソース: データベーススキーマ、API ドキュメント、テンプレート、例などの参照資料です。
Claude は、参照されたときにだけこれらのファイルへアクセスします。ファイルシステムモデルでは、内容の種類ごとに得意分野が異なります。柔軟なガイダンスには指示、信頼性にはコード、事実確認にはリソースが向いています。
| レベル | 読み込まれるタイミング | トークンコスト | 内容 |
|---|---|---|---|
| レベル 1: メタデータ | 常に(起動時) | Skill あたり約 100 token | YAML frontmatter の name と description |
| レベル 2: 指示 | Skill がトリガーされたとき | 5k token 未満 | 指示とガイダンスを含む SKILL.md 本文 |
| レベル 3+: リソース | 必要に応じて | 実質的に制限なし | bash で実行または参照される同梱ファイル。内容全体はコンテキストに入らない |
段階的開示により、その時点で関連する内容だけがコンテキストウィンドウを占有します。
Skills のアーキテクチャ
Skills は、Claude がファイルシステム、bash コマンド、コード実行能力にアクセスできるコード実行環境で動作します。イメージとしては、Skills は仮想マシン上のディレクトリとして存在し、Claude はあなたが自分のコンピューターでファイルを移動したり読んだりするときと同じ bash コマンドを使って操作します。
Claude が Skill の内容へアクセスする方法:
Skill がトリガーされると、Claude は bash を使ってファイルシステムから SKILL.md を読み込み、その指示をコンテキストウィンドウに入れます。その指示が FORMS.md やデータベーススキーマのような別ファイルを参照している場合、Claude は追加の bash コマンドでそれらのファイルも読みます。指示に実行可能なスクリプトが書かれている場合、Claude はそれを bash で実行し、出力だけを受け取ります。スクリプトのコード自体はコンテキストに入りません。
このアーキテクチャで可能になること:
オンデマンドのファイルアクセス: Claude は各タスクに必要なファイルだけを読みます。Skill に多数の参照ファイルが含まれていても、タスクに sales スキーマだけが必要なら Claude はその 1 ファイルだけを読みます。残りのファイルはファイルシステム上に残り、トークンを一切消費しません。
効率的なスクリプト実行: Claude が validate_form.py を実行するとき、そのスクリプトのコードはコンテキストウィンドウに入りません。消費されるのは、「Validation passed」や具体的なエラーメッセージなどの出力だけです。そのため、スクリプトは Claude に同等のコードをその場で生成させるよりもはるかに効率的です。
同梱内容に実用上の上限がない: ファイルはアクセスされるまでコンテキストを消費しないため、Skills には包括的な API ドキュメント、大きなデータセット、豊富な例、その他必要な参照資料を含められます。使われない同梱内容にはコンテキスト上のペナルティがありません。
このファイルシステムベースのモデルこそが、段階的開示を機能させています。Claude は、あなたがオンボーディングガイドの特定セクションを参照するのと同じように Skill をたどり、各タスクに必要な内容だけへアクセスします。
例: PDF 処理 Skill の読み込み
Claude が PDF 処理 Skill を読み込んで使う流れは次のとおりです。
- 起動時: システムプロンプトに
PDF Processing - Extract text and tables from PDF files, fill forms, merge documentsが含まれます - ユーザーリクエスト: 「この PDF からテキストを抽出して要約して」
- Claude が呼び出す:
bash: read pdf-skill/SKILL.md-> 指示がコンテキストに読み込まれます - Claude が判断する: フォーム入力は不要なので、FORMS.md は読まれません
- Claude が実行する: SKILL.md の指示を使ってタスクを完了します
この図は、次の流れを示しています。
- システムプロンプトと Skill メタデータが事前に読み込まれたデフォルト状態
- Claude が bash 経由で SKILL.md を読み、Skill をトリガーする
- Claude が必要に応じて FORMS.md のような追加同梱ファイルを読む
- Claude がタスクを進める
この動的な読み込みにより、関連する Skill 内容だけがコンテキストウィンドウを占有します。
Skills が使える場所
Skills は Claude の各エージェント製品で利用できます。
Claude API
Claude API は、事前構築済み Agent Skills とカスタム Skills の両方をサポートしています。どちらも同じように動作します。コード実行ツールとあわせて、container パラメータに該当する skill_id を指定します。
前提条件: API で Skills を使うには、3 つの beta ヘッダーが必要です。
code-execution-2025-08-25- Skills はコード実行コンテナ内で動作しますskills-2025-10-02- Skills 機能を有効にしますfiles-api-2025-04-14- コンテナとの間でファイルをアップロードまたはダウンロードするために必要です
事前構築済み Agent Skills は、pptx や xlsx などの skill_id を参照して使います。自分の Skills を作成してアップロードする場合は、Skills API(/v1/skills エンドポイント)を使います。カスタム Skills は組織全体で共有されます。
詳しくは Use Skills with the Claude API を参照してください。
Claude Code
Claude Code はカスタム Skills のみをサポートしています。
カスタム Skills: SKILL.md ファイルを含むディレクトリとして Skills を作成します。Claude はそれらを自動的に発見し、利用します。
Claude Code のカスタム Skills はファイルシステムベースであり、API へのアップロードは不要です。
詳しくは Use Skills in Claude Code を参照してください。
Claude.ai
Claude.ai は、事前構築済み Agent Skills とカスタム Skills の両方をサポートしています。
事前構築済み Agent Skills: これらの Skills は、ドキュメントを作成するときに裏側ですでに動作しています。Claude は追加設定なしで利用します。
カスタム Skills: Settings > Features から、自分の Skills を zip ファイルとしてアップロードできます。コード実行が有効な Pro、Max、Team、Enterprise プランで利用できます。カスタム Skills は各ユーザー個人に属し、組織全体で共有されたり、管理者が集中管理したりすることはできません。
Claude.ai で Skills を使う方法については、Claude Help Center の以下の資料を参照してください。
- What are Skills?
- Using Skills in Claude
- How to create custom Skills
- Tech Claude your way of working using Skills
Skill の構造
すべての Skill には、YAML frontmatter を持つ 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
YAML frontmatter でサポートされているフィールドは、この 2 つだけです。
Frontmatter の制限:
name: 最大 64 文字description: 最大 1024 文字
description には、Skill が何をするのか、そして Claude がいつ使うべきかの両方を含める必要があります。作成方法の詳しいガイダンスは、ベストプラクティスガイドを参照してください。
セキュリティ上の注意
Skills は、信頼できるソースから入手したものだけを使うことを強く推奨します。信頼できるソースとは、自分で作成したもの、または Anthropic から入手したものです。Skills は指示とコードを通じて Claude に新しい能力を与えます。これは強力である一方、悪意ある Skill が、表向きの目的と合わない形で Claude にツールを呼び出させたり、コードを実行させたりする可能性があることも意味します。
Warning
信頼できない、または出所不明の Skill をどうしても使う必要がある場合は、最大限に注意し、使用前に徹底的に監査してください。Skill 実行時に Claude が持つアクセス権によっては、悪意ある Skills がデータ流出、不正なシステムアクセス、その他のセキュリティリスクにつながる可能性があります。
主なセキュリティ上の注意点:
- 徹底的に監査する: 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 はサーフェス間で同期されません。あるサーフェスにアップロードした 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.ai は現在、カスタム Skills の管理者による集中管理や組織全体への配布をサポートしていません。
実行環境の制約
Skills はコード実行コンテナ内で動作し、以下の制限があります。
- ネットワークアクセスなし: Skills は外部 API を呼び出したり、インターネットへアクセスしたりできません
- 実行時のパッケージインストール不可: 利用できるのは事前インストール済みパッケージのみです。実行中に新しいパッケージをインストールすることはできません
- 事前設定済み依存関係のみ: 利用可能なパッケージ一覧は code execution tool documentation を確認してください
これらの制約の範囲内で動作するように Skills を設計してください。
クロードスキルのドキュメント