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

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

これまで「Claudeに資料を作らせる」には、生成した文章をこちらでPowerPointの体裁に整形し直す手間がかかっていました。プリビルドSkillはこの変換の手間そのものを肩代わりする仕組みで、依頼文を送るだけで完成済みのファイルが返ってきます。実装に必要な事前準備はAPIキーとリクエストの組み方だけで、社内向けのレポート自動作成や顧客提案資料の下書き生成のような、これまで人手を挟んでいた作業を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を作る場合はAnthropic公式のサンプルノートブックが配布されていますが、本記事はプリビルドSkillをそのまま使う最短ルートに絞ります。

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

Skills APIでAnthropic管理のSkill一覧を取得します。返るのは各Skillのidとdisplay_nameだけで、中身の手順書はまだ読み込まれません。

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件が並びます。Claudeは起動時にこのメタデータ(名前と説明文)だけを先に読み込んでおり、これが段階的開示の第1段階です。実際にどのSkillを使うかは、次のリクエスト内容に応じてClaudeが判断します。

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

containerパラメータのskillsにSkillを指定し、toolsにコード実行ツールを渡します。この2つが揃って初めてSkillが動きます。

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・Sonnet・Fable・Mythosの各系統(claude-opus-5・claude-opus-4-8・claude-sonnet-5・claude-fable-5-1・claude-mythos-5-1など)とclaude-haiku-4-5で、Haiku 4.5だけはプログラマティックツール呼び出しとREPL状態の保持が使えず旧バージョン相当の動作になります。container.skillsでSkillの種類(type: "anthropic")・識別子(skill_id: "pptx")・バージョン(version: "latest"は最新公開版)を渡し、toolsでコード実行を有効にします。このtools指定を忘れるとSkillは動作しません。

リクエストが「プレゼンを作って」という内容だとClaudeが判断すると、PowerPointのSkillの完全な手順書を読み込みます。これが段階的開示の第2段階で、実際にコードを実行してファイルを作るのはこの後です。

サンプルはcode_execution_20260521ツールバージョンを使っていますが、code_execution_20250825のような旧バージョンでも動きます。コード実行ツールの現行バージョンであれば、Skillsの要件は満たされます。

Anthropic製とカスタムSkillsの違い

container.skillsには、Anthropicが提供するSkillと自分でアップロードしたカスタムSkillのどちらも指定できます。統合の形は同じですが、識別子の付き方と公開範囲が異なります。

どちらのSkillもSkill一覧エンドポイントのsourceパラメータで絞り込んで取得できます。実行環境やcontainerの構造は完全に同一で、違いは出どころと管理主体だけです。またcontainer.skillsには1リクエストにつき最大20個までSkillを指定できるため、複数のSkillを組み合わせた複合タスクも1回のリクエストで実行できます。

手順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)を正確に辿る必要があり、途中で構造を誤ると空文字のまま処理が進みます。抽出後のダウンロード手順・複数ファイルが返るケース・保存先の扱いは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を組んでファイルを取得するまでの3ステップの最短手順、先方の記事は4つの標準Skillの一覧と面ごとの可否という役割分担です。

ゼロデータ保持(ZDR)契約を結んでいる組織がSkillsを使う場合の扱いも、通常のコード実行ツールと同じ規約が適用されます。データ保持のポリシーを厳しく運用している組織は、Skillsを本番導入する前に自組織のZDR設定と実行環境の保持ルールを照らし合わせておくと安全です。個人利用を超えて組織全体にSkillを配布する場合は、リスク階層評価やバージョン管理まで含めた運用設計が必要になります。手順はAgent Skillsのエンタープライズ配布にまとめています。

Agent SDKやClaude Codeとの違い

Agent Skills APIはMessages APIへの単発リクエストで完結する点が、Agent SDKやClaude Codeでの利用と異なります。Claude CodeのSkillsはローカルのファイルとして置かれ、対話セッションの中でコマンドや自動起動によって呼び出される仕組みで、frontmatterの項目や配置スコープもAPI側のSkillとは別物です。一方でAgent Skills APIは、アプリケーションから送るリクエスト1本の中に完結させたい場合に向いています。バッチ処理でレポートを大量生成するような、対話セッションを持たない用途との相性がよい構成です。Agent SDKでエージェントを常駐させながらSkillsを組み込む設計はClaude Agent SDK入門にまとめています。

Skills自体の実行コストは、コード実行ツールの課金ルールに従います。Web検索やWeb Fetchと併用しない単体呼び出しでは無料にならない条件があるため、コード実行ツールが無料になる条件を先に確認しておくと想定外の課金を避けられます。プラン別・面別のSkills料金の全体像はClaude Skills料金で整理しています。

なぜこの4つが最初に用意されたのか

Anthropicが最初のプリビルドSkillとしてオフィス文書系の4つを選んだのは、業務で発生する「決まった形式に整形する」作業の頻度が高く、かつ手順が定型化しやすいためだと考えられます。文書生成は毎回テンプレートが決まっている一方、内容は都度変わるという性質を持ち、Skillのように「手順は固定・入力は可変」という設計と相性がよいタスクです。オフィス文書という誰もが理解できる題材を最初の実例に選ぶことで、Skillsという仕組み自体の使い方を学習しやすくする狙いも読み取れます。この設計思想の背景はAgent Skillsとは何かで詳しく扱っています。

よくあるつまずき

• toolsにコード実行ツールを入れ忘れる: container.skillsだけを指定してもSkillは動きません。tools配列にコード実行ツールを必ず含めます。
• モデルがコード実行ツールに対応していない: 対応しているのはOpus・Sonnet・Fable・Mythosの各系統とclaude-haiku-4-5のみです。非対応モデルを指定するとSkillごと無効になります。
• file_idの抽出パスを誤る: 応答のネストが深いため、bash_code_execution_tool_resultを経由しないパスでfile_idを探すと取得できません。
• versionを固定しない: latestを指定したままにすると、誰かが新しいバージョンを公開した瞬間に本番の挙動が変わります。本番運用では具体的なバージョンIDに固定するのが安全です。
• カスタムSkillだと思い込む: プリビルドSkill(type: "anthropic")と自作のカスタムSkill(type: "custom")はSkill IDの形式が異なります。カスタムSkillはskill_01...のような生成IDになります。

まとめ

Agent Skills APIの最小構成は、container.skillsでSkillを指定し、toolsでコード実行を有効にするだけです。プリビルドSkillはpptx・xlsx・docx・pdfの4種類で、リクエストの骨格は共通なのでskill_idと指示文を変えるだけで用途を切り替えられます。生成ファイルはレスポンスに直接入らずfile_id経由でFiles APIから取得する点だけ、通常のMessages APIのやり取りと異なる注意点になります。