APIでエージェントスキルを使用する

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

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

Skill Management API Reference - スキルのCRUD操作
Skill Versions API Reference - バージョン管理

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

クイックリンク

Agent Skillsを始める

最初のスキルを作成する

カスタムスキルを作成する

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

概要

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

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

スキルの使用

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

2つのソースからスキルを使用できます：

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

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

前提条件

スキルを使用するには、以下が必要です：

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

Messages内でのスキルの使用

Containerパラメータ

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

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

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

Skills がドキュメント (Excel、PowerPoint、PDF、Word) を作成する場合、レスポンスに file_id 属性が含まれます。これらのファイルをダウンロードするには、Files API を使用する必要があります。

動作方法:

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

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

追加の Files API 操作:

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

マルチターン会話

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

長時間実行される操作

スキルは複数のターンを必要とする操作を実行する場合があります。pause_turnストップ理由を処理します：

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

複数のスキルの使用

単一のリクエストで複数のスキルを組み合わせて、複雑なワークフローを処理します：

カスタムスキルの管理

スキルの作成

カスタムスキルをアップロードして、ワークスペースで利用可能にします。ディレクトリパスまたは個別のファイルオブジェクトを使用してアップロードできます。

要件：

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

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

スキルのリスト表示

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

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

スキルの取得

特定のスキルの詳細を取得します：

スキルの削除

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

既存のバージョンを持つスキルを削除しようとすると、400エラーが返されます。

バージョン管理

スキルはバージョン管理をサポートしており、更新を安全に管理できます：

Anthropic管理スキル：

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

カスタムスキル：

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

詳細については、スキルバージョン作成APIリファレンスを参照してください。

スキルの読み込み方法

コンテナでスキルを指定すると：

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

段階的な開示アーキテクチャにより、効率的なコンテキスト使用が保証されます：Claudeは必要な場合にのみスキル命令の全文を読み込みます。

ユースケース

組織スキル

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

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

プロジェクト管理

会社固有のフォーマット（OKR、決定ログ）でノートを構造化する
チーム規約に従ったタスクを生成する
標準化された会議記録とステータス更新を作成する

ビジネスオペレーション

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

個人スキル

コンテンツ作成

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

データ分析

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

開発＆オートメーション

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

例：財務モデリング

ExcelとカスタムDCF分析スキルを組み合わせます：

制限と制約

リクエスト制限

リクエストあたりの最大スキル数： 8
最大スキルアップロードサイズ： 30 MB（すべてのファイルを合わせて）
YAMLフロントマター要件：
- name：最大64文字、小文字/数字/ハイフンのみ、XMLタグなし、予約語なし
- description：最大1024文字、空でない、XMLタグなし

環境制約

スキルはコード実行コンテナで実行され、以下の制限があります：

ネットワークアクセスなし - 外部APIコールを実行できません
ランタイムパッケージインストールなし - 事前にインストールされたパッケージのみ利用可能
分離された環境 - 各リクエストは新しいコンテナを取得します

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

ベストプラクティス

複数のスキルを使用する場合

複数のドキュメントタイプまたはドメインを含むタスクの場合、スキルを組み合わせます：

良い使用例：

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

避けるべき：

未使用のスキルを含める（パフォーマンスに影響）

バージョン管理戦略

本番環境の場合：

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

開発環境の場合：

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

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

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

最高のキャッシングパフォーマンスのために、リクエスト全体でスキルリストを一貫性のある状態に保ちます。

エラーハンドリング

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

データ保持

Agent Skillsはゼロデータ保持（ZDR）の対象ではありません。Skillの定義と実行データはAnthropicの標準的なデータ保持ポリシーに従って保持されます。

すべての機能でZDRの対象となるには、API とデータ保持を参照してください。

次のステップ

APIリファレンス

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

オーサリングガイド

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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()
file_id = "file_abc123"
# ファイルメタデータを取得します
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id, betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# すべてのファイルをリストします
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# ファイルを削除します
client.beta.files.delete(file_id=file_id, betas=["files-api-2025-04-14"])

# 最初のリクエストがコンテナを作成
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # コンテナを再利用
        "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-7",
    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-7",
        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-7",
    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"}],
)

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
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

# Create custom DCF analysis 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"),
    betas=["skills-2025-10-02"],
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
        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}")
        # Handle skill-specific errors
    else:
        raise