APIでのAgent Skillsの使用

Agent Skillsは、指示、スクリプト、リソースを整理したフォルダを通じてClaudeの機能を拡張します。このガイドでは、事前構築済みのSkillとカスタムSkillの両方をClaude APIで使用する方法を説明します。

リクエスト/レスポンススキーマおよびすべてのパラメータを含む完全なAPIリファレンスについては、以下を参照してください。

Skill管理APIリファレンス - SkillのCRUD操作
SkillバージョンAPIリファレンス - バージョン管理

この機能はZero Data Retention (ZDR)の対象外です。データは、この機能の標準的な保持ポリシーに従って保持されます。

クイックリンク

Agent Skillsを始める

最初のSkillを作成する

カスタムSkillを作成する

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

概要

Agent Skillsのアーキテクチャと実際のアプリケーションについて詳しく知りたい場合は、エンジニアリングブログ記事Equipping agents for the real world with Agent Skillsをお読みください。

Skillはコード実行ツールを通じてMessages APIと統合されます。Anthropicが管理する事前構築済みのSkillを使用する場合でも、自分でアップロードしたカスタムSkillを使用する場合でも、統合の形式は同一です。どちらもコード実行を必要とし、同じcontainer構造を使用します。

Skillの使用

Skillは、ソースに関係なくMessages APIで同一の方法で統合されます。containerパラメータでskill_id、type、およびオプションのversionを指定すると、コード実行環境で実行されます。

Skillは2つのソースから使用できます。

項目	Anthropic Skill	カスタムSkill
Type値	`anthropic`	`custom`
Skill ID	短い名前：`pptx`、`xlsx`、`docx`、`pdf`	生成されたID：`skill_01AbCdEfGhIjKlMnOpQrStUv`
バージョン形式	日付ベース：`20251013`または`latest`	エポックタイムスタンプ：`1759178010641129`または`latest`
管理

両方のSkillソースはList Skillsエンドポイントによって返されます（フィルタリングにはsourceパラメータを使用します）。統合の形式と実行環境は同一です。唯一の違いは、Skillの提供元と管理方法です。

前提条件

Skillを使用するには、以下が必要です。

Consoleから取得したClaude APIキー
ベータヘッダー：
- code-execution-2025-08-25 - コード実行を有効化（Skillに必須）
- skills-2025-10-02 - Skills APIを有効化
- files-api-2025-04-14 - コンテナへのファイルのアップロード/ダウンロード用
リクエストで有効化された**コード実行ツール**

MessagesでのSkillの使用

Containerパラメータ

SkillはMessages APIのcontainerパラメータを使用して指定します。1つのリクエストに最大8つのSkillを含めることができます。

構造はAnthropic SkillとカスタムSkillの両方で同一です。必須のtypeとskill_idを指定し、特定のバージョンに固定する場合はオプションでversionを含めます。

生成されたファイルのダウンロード

Skillがドキュメント（Excel、PowerPoint、PDF、Word）を作成すると、レスポンスにfile_id属性が返されます。これらのファイルをダウンロードするには、Files APIを使用する必要があります。

動作の仕組み：

Skillがコード実行中にファイルを作成します
レスポンスに作成された各ファイルのfile_idが含まれます
Files APIを使用して実際のファイルコンテンツをダウンロードします
ローカルに保存するか、必要に応じて処理します

例：Excelファイルの作成とダウンロード

その他のFiles API操作：

Files APIの詳細については、Files APIドキュメントを参照してください。

マルチターン会話

コンテナIDを指定することで、複数のメッセージ間で同じコンテナを再利用できます。

長時間実行される操作

Skillは複数のターンを必要とする操作を実行する場合があります。pause_turnの停止理由を処理してください。

レスポンスにはpause_turnという停止理由が含まれる場合があります。これは、APIが長時間実行されるSkill操作を一時停止したことを示します。後続のリクエストでレスポンスをそのまま提供してClaudeにターンを継続させることも、会話を中断して追加のガイダンスを提供したい場合はコンテンツを変更することもできます。

複数のSkillの使用

複雑なワークフローを処理するために、1つのリクエストで複数のSkillを組み合わせます。

カスタムSkillの管理

Skillの作成

Skillバンドルは、トップレベルにnameとdescriptionのYAMLフロントマターを含むSKILL.mdファイルと、サポートするスクリプトやリソースを含むディレクトリです。作成方法についてはAPIでAgent Skillsを始めるを参照し、完全な制約については例の後にある要件リストを参照してください。

カスタムSkillをアップロードして、ワークスペースで利用できるようにします。zipアーカイブまたは個別のファイルオブジェクトをアップロードできます。Python SDKでは、ディレクトリパスを受け取るfiles_from_dirヘルパーも追加で提供されています。

要件：

トップレベルにSKILL.mdファイルを含める必要があります
すべてのファイルはパスに共通のルートディレクトリを指定する必要があります
アップロードの合計サイズは30 MB未満である必要があります
YAMLフロントマターの要件：
- name：最大64文字、小文字の英字/数字/ハイフンのみ、XMLタグ不可、予約語（「anthropic」、「claude」）不可
- description：最大1024文字、空でないこと、XMLタグ不可

完全なリクエスト/レスポンススキーマについては、Create Skill APIリファレンスを参照してください。

Skillの一覧表示

Anthropicの事前構築済みSkillとカスタムSkillの両方を含む、ワークスペースで利用可能なすべてのSkillを取得します。Skillタイプでフィルタリングするにはsourceパラメータを使用します。

ページネーションとフィルタリングオプションについては、List Skills APIリファレンスを参照してください。

Skillの取得

特定のSkillの詳細を取得します。

Skillの削除

Skillを削除するには、まずそのすべてのバージョンを削除する必要があります。

既存のバージョンがあるSkillを削除しようとすると、400エラーが返されます。

バージョニング

Skillは、更新を安全に管理するためのバージョニングをサポートしています。

Anthropic Skill：

バージョンは日付形式を使用：20251013
更新が行われると新しいバージョンがリリースされます
安定性のために正確なバージョンを指定してください

カスタムSkill：

自動生成されたエポックタイムスタンプ：1759178010641129
常に最新バージョンを取得するには"latest"を使用します
Skillファイルを更新する際は新しいバージョンを作成します

詳細については、Create Skill Version APIリファレンスを参照してください。

Skillのロード方法

コンテナでSkillを指定すると、以下の処理が行われます。

メタデータの検出： Claudeはシステムプロンプトで各Skillのメタデータ（名前、説明）を確認します
ファイルのロード： Skillファイルがコンテナの/skills/{directory}/にコピーされます
自動使用： Claudeはリクエストに関連する場合、自動的にSkillをロードして使用します
構成： 複数のSkillが組み合わさって複雑なワークフローを実現します

「progressive disclosure」（段階的開示）アーキテクチャにより、効率的なコンテキスト使用が保証されます。Claudeは必要な場合にのみ完全なSkill指示をロードします。

ユースケース

組織向けSkill

ブランドとコミュニケーション

企業固有のフォーマット（色、フォント、レイアウト）をドキュメントに適用
組織のテンプレートに従ったコミュニケーションの生成
すべての出力で一貫したブランドガイドラインを確保

プロジェクト管理

企業固有のフォーマット（OKR、意思決定ログ）でメモを構造化
チームの慣例に従ったタスクの生成
標準化された会議の要約とステータス更新の作成

ビジネスオペレーション

企業標準のレポート、提案書、分析の作成
企業固有の分析手順の実行
組織のテンプレートに従った財務モデルの生成

個人向けSkill

コンテンツ作成

カスタムドキュメントテンプレート
専門的なフォーマットとスタイリング
ドメイン固有のコンテンツ生成

データ分析

カスタムデータ処理パイプライン
専門的な可視化テンプレート
業界固有の分析手法

開発と自動化

コード生成テンプレート
テストフレームワーク
デプロイメントワークフロー

例：財務モデリング

ExcelとカスタムDCF分析Skillを組み合わせます。

制限と制約

リクエストの制限

リクエストあたりの最大Skill数： 8
Skillアップロードの最大サイズ： 30 MB（すべてのファイルの合計）
YAMLフロントマターの要件：
- name：最大64文字、小文字の英字/数字/ハイフンのみ、XMLタグ不可、予約語（「anthropic」、「claude」）不可
- description：最大1024文字、空でないこと、XMLタグ不可

環境の制約

Skillは以下の制限があるコード実行コンテナで実行されます。

ネットワークアクセスなし： 外部API呼び出しはできません
ランタイムパッケージインストールなし： 事前インストールされたパッケージのみ利用可能
隔離された環境： コンテナは隔離されており、既存のコンテナIDを指定しない限り、新しいコンテナが作成されます

利用可能なパッケージについては、コード実行ツールを参照してください。

ベストプラクティス

複数のSkillを使用するタイミング

タスクが複数のドキュメントタイプやドメインに関わる場合は、Skillを組み合わせます。

適切なユースケース：

データ分析（Excel）+ プレゼンテーション作成（PowerPoint）
レポート生成（Word）+ PDFへのエクスポート
カスタムドメインロジック + ドキュメント生成

避けるべきこと：

使用しないSkillを含めること（パフォーマンスに影響します）

バージョン管理戦略

本番環境向け：

# 安定性のために特定のバージョンに固定
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

開発環境向け：

# アクティブな開発には最新版を使用します
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

プロンプトキャッシングに関する考慮事項

プロンプトキャッシングを使用する場合、コンテナ内のSkillリストを変更するとキャッシュが無効になることに注意してください。

最適なキャッシングパフォーマンスを得るには、リクエスト間でSkillリストを一貫させてください。

エラー処理

Skill関連のエラーを適切に処理します。

データ保持

Agent SkillsはZDR契約の対象外です。Skillの定義と実行データは、Anthropicの標準データ保持ポリシーに従って保持されます。

すべての機能におけるZDR適格性については、APIとデータ保持を参照してください。

次のステップ

APIリファレンス

すべてのエンドポイントを含む完全なAPIリファレンス

作成ガイド

効果的なSkillを作成するためのベストプラクティス

コード実行ツール

コード実行環境について学ぶ

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

client = anthropic.Anthropic()

# ステップ1：Skillを使用してファイルを作成
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Create an Excel file with a simple budget spreadsheet",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# ステップ2：レスポンスからファイルIDを抽出
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # 具象型のリスト：List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# ステップ3：Files APIを使用してファイルをダウンロード
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # ステップ4：ディスクに保存
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

client = anthropic.Anthropic()
file_id = "file_abc123"
# ファイルのメタデータを取得
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# すべてのファイルを一覧表示
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# ファイルを削除
client.beta.files.delete(file_id=file_id)

# 最初のリクエストでコンテナを作成
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 同じコンテナで会話を継続
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 長時間の操作に対するpause_turnの処理
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# オプション1：個別のファイルをアップロード（ファイルごとに --file フラグを1つ指定）
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# オプション2：zipアーカイブをアップロード
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# ステップ1：すべてのバージョンを削除
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# ステップ2：Skillを削除
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# 新しいバージョンを作成
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# 特定のバージョンを使用
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 最新バージョンを使用
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# カスタムDCF分析Skillを作成
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
)

# Excelと併用して財務モデルを作成
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company with the attached financials",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

# 最初のリクエストでキャッシュが作成されます
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# スキルの追加・削除はキャッシュを無効化します
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # スキル固有のエラーを処理
    else:
        raise

クイックリンク

概要

Skillの使用

前提条件

MessagesでのSkillの使用

Containerパラメータ

生成されたファイルのダウンロード

マルチターン会話

長時間実行される操作

複数のSkillの使用

カスタムSkillの管理

Skillの作成

Skillの一覧表示

Skillの取得

Skillの削除

バージョニング

Skillのロード方法

ユースケース

組織向けSkill

個人向けSkill

例：財務モデリング

制限と制約

リクエストの制限

環境の制約

ベストプラクティス

複数のSkillを使用するタイミング

バージョン管理戦略

プロンプトキャッシングに関する考慮事項

エラー処理

データ保持

次のステップ

クイックリンク

概要

Skillの使用

前提条件

MessagesでのSkillの使用

Containerパラメータ

生成されたファイルのダウンロード

マルチターン会話

長時間実行される操作

複数のSkillの使用

カスタムSkillの管理

Skillの作成

Skillの一覧表示

Skillの取得

Skillの削除

バージョニング

Skillのロード方法

ユースケース

組織向けSkill

個人向けSkill

例：財務モデリング

制限と制約

リクエストの制限

環境の制約

ベストプラクティス

複数のSkillを使用するタイミング

バージョン管理戦略

プロンプトキャッシングに関する考慮事項

エラー処理

データ保持

次のステップ