Agent Skills APIクイックスタート — コード実行ツールでPDFや資料を作る

Messages APIでAgent Skillsを使うと、プレゼン資料やPDFを作らせる処理が1回のAPI呼び出しで完結します。必要なのはモデル・コード実行ツール・使いたいSkillの3点を、リクエストのcontainerとtoolsに書くことだけです。Skillの中身(手順書やスクリプト)を自分で書く必要はありません。この記事では、Anthropicが配布している4種類のプリビルドSkillを使い、一覧取得からファイル保存までを実際のリクエストで組みます。

これまで「Claudeに資料を作らせる」には、生成した文章をこちらでPowerPointの体裁に整える手間がありました。プリビルドSkillはその変換を肩代わりし、依頼文を送るとコンテナ内で作られたファイルのIDが返ります。社内レポートの自動作成や提案資料の下書きのように、人手を挟んでいた作業を1リクエストに寄せられます。

Agent Skills APIとは何か

Agent Skills APIとは、指示書・スクリプト・参照資料をまとめたフォルダ(Skill)をMessages APIのリクエストに組み込み、Claudeに特定タスクの専門知識を持たせる仕組みです。Anthropicはpptx(PowerPoint)・xlsx(Excel)・docx(Word)・pdf(PDF)の4つをプリビルドSkillとして提供しています。APIキーがあればすぐ呼び出せます。

Skillsはコード実行ツール(code execution tool)の上で動きます。Claudeがリクエスト内容からSkillが適切だと判断すると、コンテナ内でSkillのコードを実行してファイルを作ります。Skillという設計が生まれた背景はAgent Skillsとは何かで扱っています。

リクエスト1本でファイルが手に入るまで

手順1: 利用可能なSkillsを一覧する

Skills APIでAnthropic管理のSkill一覧を取得します。sourceパラメータで取得元を絞れます。

curl --fail-with-body -sS "https://api.anthropic.com/v1/skills?source=anthropic" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

結果にはpptx・xlsx・docx・pdfの4件が並びます。SDKでは各Skillのid・display_name・source.typeが読めます。Skills APIはベータを卒業しており、skills-2025-10-02のベータヘッダーは不要です。このヘッダーを付け続けた既存のリクエストは、旧形式のレスポンスのまま動き続けます。

手順2: プレゼンテーションを作成する

containerのskillsにSkillを指定し、toolsにコード実行ツールを渡します。2つが揃って初めてSkillが動きます。後続の手順で使うため、応答はresponse変数に保存します。

response=$(curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "container": {
      "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    "messages": [
      {"role": "user", "content": "Create a presentation about renewable energy with 5 slides"}
    ],
    "tools": [{"type": "code_execution_20260521", "name": "code_execution"}]
  }')

modelにはコード実行ツールに対応したモデルを指定します。対応するのはOpus 4.5以降・Sonnet 4.5以降・Fable 5系・Mythos 5系と、Haiku 4.5(claude-haiku-4-5-20251001)です。IDの例はclaude-opus-5・claude-opus-4-8・claude-sonnet-5・claude-fable-5-1・claude-mythos-5-1です。Haiku 4.5ではプログラマティックツール呼び出しとREPL状態の保持が使えず、新しいツールバージョンでもcode_execution_20250825相当の動作になります。

container.skillsには種類(type: "anthropic")・識別子(skill_id: "pptx")・バージョン("latest"は最新公開版)を渡します。toolsを忘れるとSkillは動きません。

latestのままだと、新しいバージョンの公開で挙動が変わりえます。本番では、Anthropic Skillsなら20251013のような日付、カスタムSkillならskver_...のIDで固定します。

「プレゼンを作って」という依頼だとClaudeが判断すると、PowerPointのSkillの完全な手順書が読み込まれます。名前と説明文だけを先に読む段階の次に、手順書の全文を読む段階があり、その後でコードが実行されてファイルができます。サンプルはcode_execution_20260521を使っていますが、code_execution_20250825のような旧バージョンでも動きます。現行のコード実行ツールであれば、Skillsの要件は満たされます。

Anthropic製とカスタムSkillsの違い

container.skillsには、Anthropic提供のSkillと自分でアップロードしたカスタムSkillのどちらも指定できます。実行環境とcontainerの構造は同一で、違いは出どころと管理主体、ID・バージョンの形式です。

container.skillsは1リクエストにつき最大20個まで指定でき、Excelで分析してPowerPointにまとめるような複合タスクも1回で実行できます。使わないSkillを入れると性能に響くとされているため、必要な分だけに絞ります。

カスタムSkillはワークスペース全体で共有される点にも注意が必要です。そのワークスペースにアクセスできるAPIキーなら、誰でも読み取り・実行・削除ができ、エンドユーザーやセッション単位では分離されません。分けたいSkillは別のワークスペースに置き、そのワークスペース専用のキーだけで使います。

手順3: 生成ファイルを取得する

応答にファイルの中身は入っていません。bash_code_execution_tool_resultブロックの中のfile_idが返るので、実体はFiles APIから取得します。

file_id=$(jq -r '
  last(
    .content[]
    | select(.type == "bash_code_execution_tool_result")
    | .content
    | select(.type == "bash_code_execution_result")
    | .content[].file_id
  ) // empty
' <<<"$response")
 
curl --fail-with-body -sS "https://api.anthropic.com/v1/files/$file_id/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -o "renewable_energy.pptx"

file_idの抽出パスは応答のネスト(bash_code_execution_tool_result → bash_code_execution_result → file_id)を正確に辿る必要があります。途中で外れるとfile_idは空のままで、URLが/v1/files//contentになりダウンロードに失敗します。ダウンロード後の扱いや複数ファイルが返るケースはSkillsの生成ファイルをダウンロードする4ステップに手順化してあります。

Excel・Word・PDFも同じ形で作れる

残る3つのSkillもリクエストの形は共通で、変わるのはskill_idとcontentの指示文だけです。四半期の売上トラッキング表がほしいなら、skill_idをxlsxに、contentを「Create a quarterly sales tracking spreadsheet with sample data」に替えます。

4種類それぞれの出力形式・向くタスク・claude.aiやClaude Codeでの可否はAgent SkillsのAPI標準スキル一覧にあります。この記事はcontainerとtoolsを組んでファイルを取得するまでを扱い、先方は標準Skillの一覧と面ごとの可否を扱います。

実行環境の制約と、長い処理の続け方

Skillはコード実行ツールのコンテナ内で動くため、環境の制約をそのまま受けます。手順書に「外部APIを呼ぶ」「パッケージを入れる」と書かれていても、次の制約が優先されます。

コンテナにはネットワークがなく、実行時のパッケージ追加もできません。使えるのはPython 3.11と、python-pptx・python-docx・openpyxl・pypdfなどのプリインストール済みライブラリです。リクエストごとに新しいコンテナが作られ、前のリクエストのファイルは引き継がれません。

続きの依頼で同じファイルを直したいときは、前の応答のcontainerオブジェクトにあるidを、次のリクエストのcontainerに渡します。Skillの指定も付けたまま、IDだけ足す形です。

"container": {
  "id": "container_01...",
  "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
}

作成から30日を過ぎたコンテナは再利用できず、IDを指定するとエラーになります。その場合はcontainerのIDを外して送り直すと、新しいコンテナで始まります。応答のcontainer.expires_atは短い更新値で、30日の寿命とは別物です。

長い処理では、応答のstop_reasonがpause_turnで返ることがあります。API側が処理を一時停止した合図で、その応答をそのままassistantの発話としてメッセージ末尾に足し、同じコンテナで再送すると続きが実行されます。stop_reasonがpause_turnでなくなるまで繰り返すループにしておけば、途中で打ち切られた資料を完成品と取り違えずに済みます。

入力ファイルが必要なとき(既存のExcelを分析させるなど)は、先にFiles APIでアップロードし、リクエストにコンテナアップロードブロックとして参照させます。

課金とデータ保持

Skillはコード実行ツールのコンテナ上で動くので、課金はコード実行ツールの規則に従います。Web検索かWeb Fetchの20260209以降のツールを同じリクエストに入れると、コード実行の追加料金は発生せず、トークン料金だけになります。課金される実行時間には最小5分があります。

入力ファイルを付けたリクエストは、ツールが呼ばれなくても実行時間が課金されます。ファイルがコンテナに先に読み込まれるためです。条件の詳細はコード実行ツールが無料になる条件に、プラン別・面別のSkills料金はClaude Skills料金にあります。

データ保持の面では、コード実行ツールはゼロデータ保持(ZDR)の対象外です。Agent Skills自体も対象外で、Skillの定義と実行データは標準の保持ポリシーに従います。コンテナ内のデータ(実行成果物・アップロードファイル・出力)は最長30日保持され、Files APIに作られたファイルは明示的に削除するまで残ります。ZDR契約の組織は、Skillsの本番導入前に自組織の契約との整合を確かめる必要があります。組織全体にSkillを配る場合のリスク評価やバージョン管理はAgent Skillsのエンタープライズ配布にあります。

Agent SDKやClaude Codeとの違い

Agent Skills APIはMessages APIへの単発リクエストで完結します。Claude Codeでは、SkillsがローカルのファイルとしてPCに置かれ、対話セッションの中でコマンドや自動起動で呼ばれます。frontmatterの項目や配置スコープもAPI側のSkillとは別物です。詳しくはClaude Codeの解説にあります。

アプリケーションから送る1本のリクエストで完結させたいとき、対話セッションを持たないバッチ処理でレポートを大量に作るときは、APIが向きます。Agent SDKでエージェントを常駐させながらSkillsを組み込む設計はClaude Agent SDK入門にあります。

まとめ

単発のバッチで資料を作るなら、このリクエストの形で足ります。続きの編集が要るときは、コンテナIDの受け渡しと30日の寿命を前提に組みます。ZDR契約の組織では、Skillsを使うと契約の外に出る点が導入判断の分かれ目です。