ホーム / チュートリアル / Agent SkillsをClaude APIから使う

Agent SkillsをClaude APIから使う

Claude API エンジニアリング 7分で読めます

Claude API から PowerPoint や Excel、Word、PDF を作らせたいとき、ファイル形式ごとのライブラリの使い方をプロンプトに書き並べる必要はありません。Anthropic があらかじめ用意した Agent Skills を container パラメータで有効にすると、Claude が課題に合うスキルを自分で選び、コード実行環境の中でそのスキルのコードを走らせてファイルを作ります。この記事では、公式チュートリアル Get started with Agent Skills in the API の内容を日本語で整理します。

Agent Skills とは何か

Agent Skills は、特定の作業のための手順とコードをまとめたもので、Claude の能力を外から拡張します。API では Anthropic が管理する既製のスキルが4つ用意されています。

仕組みで押さえておきたいのは段階的な開示（progressive disclosure）です。Claude はまず起動時に、各スキルの名前と説明だけを読み込みます。この時点ではスキルの中身（詳細な手順書）は読んでいません。そのうえで、依頼された作業に合うスキルがあると判断したときにはじめて、そのスキルの完全な指示を読み込んで実行します。手順書の全文を常に文脈へ載せないので、スキルを増やしても入力トークンが際限なく膨らまない、という設計になっています。

この記事で扱うのは既製スキルの使い方です。自分で作ったスキルを持ち込みたい場合は、Skills API のアップロードを使います。

使えるスキルの一覧を取る

まず、いま何が使えるかを確認します。source に anthropic を渡すと、Anthropic が管理しているスキルだけが返ります。

from anthropic import Anthropic

client = Anthropic()

skills = client.skills.list(source="anthropic")

for skill in skills.data:
    print(f"{skill.id}: {skill.display_name}")

TypeScript も同じ形です。

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

const client = new Anthropic();

const skills = await client.skills.list({ source: "anthropic" });

for (const skill of skills.data) {
  console.log(`${skill.id}: ${skill.display_name}`);
}

raw HTTP なら次のようになります。

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件と、それぞれの名前と説明です。この一覧を実行時に取っておくと、スキルの追加や改名をコードにハードコードせずに済みます。

container.skills でスキルを有効にする

スキルは Messages API の container パラメータで指定します。合わせてコード実行ツールを有効にする必要があります。スキルの実体はコンテナの中で走るコードなので、コード実行ツールが無いとスキルは動きません。

response = client.messages.create(
    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"}],
)

print(f"stop_reason={response.stop_reason}, blocks={len(response.content)}")

リクエストの各部分の意味は次のとおりです。

プレゼンテーションを頼んだので、Claude は PowerPoint のスキルが関係すると判断し、その完全な指示を読み込みます。これが段階的な開示の2段目です。そのうえでスキルのコードを実行してファイルを作ります。どのスキルを使うかをこちらで名指しする必要はありません。 container.skills は「使ってよいものの集合」を渡しているだけで、選ぶのは Claude です。

curl で書くと次のようになります。

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": "xlsx", "version": "latest"}]
    },
    "messages": [
      {"role": "user", "content": "Create a quarterly sales tracking spreadsheet with sample data"}
    ],
    "tools": [{"type": "code_execution_20260521", "name": "code_execution"}]
  }'

skill_id を docx や pdf に替えれば、そのまま Word や PDF の生成になります。プロンプト側で「Word で」と念を押す必要はありません。

生成されたファイルを取り出す

作られたファイルはコード実行のコンテナの中にあり、レスポンスにはそのファイル ID だけが入ります。中身は Files API で別途ダウンロードします。

ここで注意が要るのは、ファイル ID が入っている場所です。コード実行ツールはスキルのコードを Bash のサブツール経由で走らせるので、生成されたファイルは bash_code_execution_tool_result ブロックの中の bash_code_execution_result の、さらにその content の要素として現れます。

file_id = None
for block in response.content:
    if block.type == "bash_code_execution_tool_result":
        if block.content.type == "bash_code_execution_result":
            for output in block.content.content:
                file_id = output.file_id

if file_id:
    output_path = Path(tempfile.gettempdir()) / "renewable_energy.pptx"
    file_content = client.files.download(file_id=file_id)
    file_content.write_to_file(output_path)
    print(f"Presentation saved to {output_path}")

curl と jq で取り出す場合は次のようになります。

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")

if [[ -n "$file_id" ]]; then
  output_path="${TMPDIR:-/tmp}/renewable_energy.pptx"
  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 "$output_path"
  echo "Presentation saved to $output_path"
fi

1回の応答で複数のファイルが作られることもあるので、上の例のように反復して拾います。curl の例が last(...) を使っているのは、最後に出力されたファイルだけを取る、という単純化です。全部欲しいなら last() を外してください。

注意点

コード実行ツールのバージョンは合わせる。 上の例は code_execution_20260521 を使っています。スキル自体は code_execution_20250825 のような以前のバージョンでも動きますが、レスポンスの構造がバージョンによって変わります。手順4のファイル ID の取り出し方は現行のバージョンが返す形に合わせて書いてあるので、別のバージョンを使うならコード実行ツールのドキュメントで返り値の形を確認してください。

そのほか、実際に使うときに効いてくる点を挙げます。

自分の業務知識をスキルとして持ち込みたい場合は、Skills API でアップロードします。書き方の指針は公式の Skill authoring best practices にまとまっています。Claude Code 側のスキルについては、当サイトの スキルとは何か と 最初のスキルを作る も合わせてどうぞ。

関連チュートリアル

用途に合ったClaudeモデルを選ぶ Claudeを呼ぶ前にトークン数を数える 100万トークンのコンテキストウィンドウを使う Claudeモデルの移行ガイド Claude APIのエラーを扱う
← チュートリアル一覧へ戻る カテゴリで探す