Tutorials

Claude Agent Skills APIガイド：Claude APIでスキルを使う方法

Claude Agent Skills APIガイド — Agent SkillsをClaude APIで使用する方法を学びましょう。Python、TypeScript、cURLのコード例を含むClaude Agent Skills APIの完全ガイドです。

AnthropicOctober 16, 202518 min read
#agent-skills#claude-api#python#typescript#code-examples
Claude Agent Skills API

この記事は、Anthropicの公式ドキュメント「Using Agent Skills with the API」に基づいています。

Claude Agent Skills APIは、整理されたフォルダに格納された指示、スクリプト、リソースを通じてClaudeの機能を拡張します。このClaude Agent Skills APIガイドでは、ビルド済みおよびカスタムのAgent SkillsをClaude APIで使用する方法を説明します。

Claude Agent Skills APIの概要

Claude Agent Skills APIは、コード実行ツールを介してMessages APIと統合されます。Anthropicが管理するビルド済みのAgent Skillsを使用する場合でも、アップロードしたカスタムAgent Skillsを使用する場合でも、Claude Agent Skills APIの統合方法は同じです。どちらもコード実行が必要で、同じcontainer構造を使用します。

Claude Agent Skills APIのアーキテクチャと統合フロー
Claude Agent Skills APIのアーキテクチャと統合フロー

Claude Agent Skills API：Anthropic Skillsとカスタムスキルの比較

項目Anthropic Skillsカスタムスキル
Type値anthropiccustom
スキルID短縮名: pptx, xlsx, docx, pdf生成値: skill_01AbCdEfGhIjKlMnOpQrStUv
バージョン形式日付ベース: 20251013 または latestエポックタイムスタンプ: 1759178010641129 または latest
管理Anthropicがビルド・メンテナンスSkills APIでアップロード・管理
利用可能性全ユーザーが利用可能ワークスペースに限定

Claude Agent Skills APIの前提条件

Claude Agent Skills APIを使用するには、以下が必要です：

  1. Anthropic APIキー（コンソールから取得）
  2. Betaヘッダー:
    • code-execution-2025-08-25 - コード実行を有効化（Skillsに必須）
    • skills-2025-10-02 - Skills APIを有効化
    • files-api-2025-04-14 - コンテナへのファイルアップロード・ダウンロード用
  3. コード実行ツールがリクエストで有効化されていること

Claude APIでAgent Skillsを使用する

コンテナパラメータ

Claude Agent Skills APIでは、Messages APIのcontainerパラメータでAgent Skillsを指定します。1リクエストあたり最大8つのAgent Skillsを含めることができます。

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}],
)

TypeScriptでの同等コード：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-sonnet-4-5-20250929",
  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" }]
});

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

Skillsがドキュメントを作成すると、レスポンスにfile_id属性が含まれます。Files APIを使用してこれらのファイルをダウンロードできます：

  1. Skillsがコード実行中にファイルを作成
  2. レスポンスに各作成ファイルのfile_idが含まれる
  3. Files APIを使用して実際のファイルコンテンツをダウンロード
# ステップ1：Skillを使用してファイルを作成
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids

# ステップ3：各ファイルをダウンロード
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

マルチターン会話

コンテナIDを指定することで、複数のメッセージにわたって同じコンテナを再利用できます：

# 最初のリクエストでコンテナを作成
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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"}],
)

長時間実行オペレーション

Skillsは複数ターンを必要とするオペレーションを実行する場合があります。pause_turn停止理由を処理してください：

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

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

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-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

複数スキルの使用

1つのリクエストで複数のSkillsを組み合わせることができます（最大8つ）：

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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_01...", "version": "latest"},
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Claude APIでカスタムAgent Skillsを管理する

Agent Skillの作成

from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"],
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

ZIPファイルや個別のファイルタプルを使用してアップロードすることもできます：

# オプション2：ZIPファイルを使用
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"],
)

# オプション3：ファイルタプルを使用
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"],
)

要件：

  • トップレベルにSKILL.mdファイルを含める必要があります
  • すべてのファイルは共通のルートディレクトリを指定する必要があります
  • アップロード合計サイズは8MB以下である必要があります
  • name：最大64文字、小文字・数字・ハイフンのみ
  • description：最大1024文字、空でないこと

スキルの一覧表示

# すべてのSkillsを一覧表示
skills = client.beta.skills.list(betas=["skills-2025-10-02"])
for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# カスタムSkillsのみを一覧表示
custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"])

スキルの取得

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")

スキルの削除

Skillを削除する前に、すべてのバージョンを先に削除する必要があります：

# ステップ1：すべてのバージョンを削除
versions = client.beta.skills.versions.list(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)
for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01...",
        version=version.version,
        betas=["skills-2025-10-02"],
    )

# ステップ2：Skillを削除
client.beta.skills.delete(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)

バージョニング

Skillsは安全な更新のためにバージョニングをサポートしています：

# 新しいバージョンを作成
new_version = client.beta.skills.versions.create(
    skill_id="skill_01...",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"],
)

# 本番環境の安定性のために特定バージョンを固定
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "1759178010641129",  # 固定バージョン
    }]
}

# 開発時はlatestを使用
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "latest",
    }]
}

Claude Agent Skills APIがスキルを読み込む仕組み

Claude Agent Skills APIでコンテナにAgent Skillsを指定すると：

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

段階的開示アーキテクチャにより、効率的なコンテキスト利用が実現されます。Claudeは必要な時にのみ完全なSkill指示を読み込みます。

ユースケース

組織向けスキル

  • ブランド＆コミュニケーション：企業固有のフォーマットを適用し、テンプレートに沿ったコミュニケーションを生成
  • プロジェクト管理：企業固有のフォーマットでノートを構造化し、標準化された会議レポートを作成
  • ビジネスオペレーション：企業標準のレポートを作成し、分析手順を実行

個人向けスキル

  • コンテンツ作成：カスタムドキュメントテンプレート、専門的なフォーマット
  • データ分析：カスタムデータ処理パイプライン、専門的なビジュアライゼーション
  • 開発：コード生成テンプレート、テストフレームワーク、デプロイワークフロー

例：財務モデリング

ExcelとカスタムDCF分析Skillsを組み合わせる：

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"],
)

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

ベストプラクティス

プロンプトキャッシング

コンテナ内のSkillsリストを変更すると、プロンプトキャッシュが無効になります。最高のキャッシュパフォーマンスを得るために、リクエスト間でSkillsリストを一貫させてください。

バージョン管理

  • 本番環境：安定性のために特定バージョンに固定
  • 開発環境：アクティブなイテレーションには"latest"を使用

エラーハンドリング

try:
    response = client.beta.messages.create(...)
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
    else:
        raise

Claude Agent Skills APIの制限と制約

  • リクエストあたりの最大Agent Skills数：8
  • Agent Skillの最大アップロードサイズ：8MB（全ファイル合計）
  • 実行コンテナではネットワークアクセス不可
  • ランタイムでのパッケージインストール不可 — プリインストール済みパッケージのみ利用可能
  • 隔離された環境 — 各Claude Agent Skills APIリクエストは新しいコンテナで実行されます

Skills in This Post

PDF ProcessorComprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documentsWord Document ProcessorComprehensive document creation, editing, and analysis with support for tracked changes and commentsPowerPoint ProcessorPresentation creation, editing, and analysis with support for layouts and speaker notesExcel Spreadsheet ProcessorComprehensive spreadsheet creation, editing, and analysis with support for formulas and data visualization

Related Posts

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills
Tutorials

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills

Agent skills best practices for writing effective Claude Skills. Learn agent skills best practices from core principles like conciseness and progressive disclosure to advanced patterns with executable code.

Anthropic
Oct 16, 202520 min read
agent-skillsbest-practicesskill-creation
AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows
Tutorials

AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows

Learn how to build AI agent workflows with persistent memory and tool integration using Claude Skills. Step-by-step guide to agent memory systems, tool coordination, and production-ready agent architectures.

Claude Skills Team
Mar 10, 20268 min read
agent-memorytool-integrationai-agents
Automate Code Quality: Write, Fix, and Review Tests with Claude Skills
Tutorials

Automate Code Quality: Write, Fix, and Review Tests with Claude Skills

Learn how to automate test writing, test fixing, and code review using Claude Skills. Practical guide with examples for teams using Claude Code in 2025.

Claude Skills Team
Mar 10, 202610 min read
testingcode-reviewautomation