# Claude APIのAgent Skills：Claude Codeなしで既製スキルを使う方法 > Claude APIに既製のpptxスキルを接続する方法：container.skills、コード実行ツール、応答の確認、Files APIを使ったプレゼンテーションのダウンロード。 Source: https://ailoot.ai/blog/ja/claude-api-agent-skills/ Canonical: https://ailoot.ai/blog/ja/claude-api-agent-skills/ Language: ja Publisher: Ailoot (https://ailoot.ai/) Translation: guide-039 Revision: sha256-737dd70aa8876d743bc2347d00fd659840e35c5cb0243376f7a2f5791107bd7f
重要なポイント ドキュメント向けの既製Agent Skillsは、Claude APIを直接使って利用できます。`container.skills`でスキルを指定し、`code_execution`を有効にしてください。最初のリクエストでは、公式の例に記載されている互換性のあるモデルとツールの組み合わせを使います。生成されたファイルは`file_id`を使って別途ダウンロードします。この例では、リクエストとダウンロードに同じAPIキーを使います。
詳しくは[Ailootのドキュメント](https://ailoot.ai/docs/)をご覧ください。 ## 必要なもの このガイドでは、Claude Codeにスキルをインストールするのではなく、プログラムからAPIを直接呼び出します。Claude APIキー、選択したモデルへのアクセス権、Python 3が必要です。以下のコードはPython標準ライブラリとHTTPを使用するため、インストール済みのSDKのバージョンに依存しません。キーは環境変数`ANTHROPIC_API_KEY`を通じて渡します。プログラムのテキストや会話には記載しないでください。 APIでは、Anthropicの既製スキルとして、プレゼンテーション用の`pptx`、スプレッドシート用の`xlsx`、Word文書用の`docx`、PDF用の`pdf`が提供されています。これらは`type: "anthropic"`を使って接続します。このガイドでは既製スキルを使い、カスタムスキルはアップロードしません。 この資料の準備時点で開かれていた[公式クイックスタート](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart.md)では、`claude-opus-5-5`と`code_execution_20260521`の組み合わせが使われています。以下のコードでもこの組み合わせを使います。この例はドキュメントに照らして確認済みですが、有料APIを実行した報告ではありません。 ## 必要なベータヘッダー この例はクイックスタートの現在のHTTP仕様に従っています。ヘッダーは`x-api-key`、`anthropic-version: 2023-06-01`、`content-type: application/json`で、`anthropic-beta`は送信しません。異なる世代のドキュメントにあるモデル、呼び出し方法、応答形式を組み合わせないでください。 [Files APIのドキュメント](https://platform.claude.com/docs/en/build-with-claude/files.md)にも、APIはベータ版ではなくなったと記載されています。旧`files-api-2025-04-14`ヘッダーを使うと旧形式の応答が維持されますが、ヘッダーを削除すると現在の形式に切り替わります。そのため、`client.beta.files`を使う古い例を新しい例とそのまま組み合わせることはできません。 ここでは、旧ベータ仕様から既存サービスを移行するわけではありません。そのようなサービスをすでにお使いの場合は、まずヘッダーと応答形式を確認してください。SDKのメソッド名に`beta`が含まれているだけでは判断できません。Files APIのドキュメントでは、SDKのバージョンごとの動作について別途説明されています。 ## プレゼンテーションを作成してファイルをダウンロードする この例では、再生可能エネルギーについて5枚のスライドを作成するタスクを送信し、応答全体を`skill-response.json`に保存してから、生成ファイルのIDを抽出します。モデルの応答から保存先のパスを取得することはありません。ファイルは`skill-output`という新しいローカルフォルダーに保存されます。このフォルダーがすでにある場合、前の結果を上書きしないようプログラムは停止します。 フォルダーはAPI呼び出しの前に作成するため、呼び出しに失敗しても残ります。再実行する前に、その試行を確認して保存してください。再実行を通すためだけに削除しないでください。 ```python import json import os from pathlib import Path from urllib.error import HTTPError from urllib.request import Request, urlopen API = "https://api.anthropic.com/v1" KEY = os.environ["ANTHROPIC_API_KEY"] HEADERS = { "x-api-key": KEY, "anthropic-version": "2023-06-01", "content-type": "application/json", } def request(path, payload=None, binary=False): data = None if payload is None else json.dumps(payload).encode("utf-8") req = Request(API + path, data=data, headers=HEADERS) try: with urlopen(req, timeout=600) as result: body = result.read() except HTTPError as error: try: details = json.loads(error.read().decode("utf-8")) except (ValueError, UnicodeError): details = {} info = details.get("error", {}) request_id = error.headers.get("request-id") or details.get("request_id") diagnostic = { "http_status": error.code, "request_id": request_id, "error_type": info.get("type"), "message": str(info.get("message", "No JSON error message")).replace(KEY, "[REDACTED]")[:1000], } (out / "skill-error.json").write_text( json.dumps(diagnostic, ensure_ascii=False, indent=2), encoding="utf-8" ) raise RuntimeError( f"Claude API HTTP {error.code}; request_id={request_id}; inspect skill-error.json" ) from None return body if binary else json.loads(body) out = Path("skill-output") out.mkdir(exist_ok=False) response = request("/messages", { "model": "claude-opus-5-5", "max_tokens": 16000, "container": { "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}] }, "messages": [{ "role": "user", "content": "再生可能エネルギーについて、希望する言語で5枚のスライドからなるプレゼンテーションを作成してください。", }], "tools": [{"type": "code_execution_20260521", "name": "code_execution"}], }) (out / "skill-response.json").write_text( json.dumps(response, ensure_ascii=False, indent=2), encoding="utf-8" ) print("stop_reason:", response.get("stop_reason")) file_ids = [] for block in response["content"]: if block["type"] == "bash_code_execution_tool_result": result = block["content"] if result["type"] == "bash_code_execution_result": for item in result["content"]: file_id = item.get("file_id") if file_id and file_id not in file_ids: file_ids.append(file_id) if not file_ids: raise RuntimeError("No generated file_id; inspect skill-response.json") for index, file_id in enumerate(file_ids, start=1): from urllib.parse import quote file_path = "/files/" + quote(file_id, safe="") metadata = request(file_path) if metadata.get("downloadable") is not True: raise RuntimeError("This file cannot be downloaded through Files API") target = out / f"result-{index}.pptx" target.write_bytes(request(file_path + "/content", binary=True)) print("Saved:", target) ``` `result-1.pptx`などのファイル名は、このプレゼンテーション作成タスク用に選んだものです。拡張子だけではファイルの中身は証明できません。ダウンロードした文書を開き、形式、スライド数、テキストを確認してください。HTTP 200が返ったことや`file_id`が存在することだけを成功とみなさないでください。 プログラムは応答が停止した理由である`stop_reason`を出力し、確認用に応答全体を保存します。会話を続けたり、有料リクエストを自動的に繰り返したりはしません。ファイルをダウンロードできても、タスク全体が完了したとは限りません。次のリクエストが必要かどうかを決める前に、保存した応答と文書そのものを確認してください。 失敗した試行では、存在する場合は`skill-error.json`を確認します。HTTPステータス、提供されていればリクエストID、設定したAPIキーを除去して長さを制限したプロバイダーのエラーメッセージが記録されます。共有前に、ほかの私的な情報が含まれていないかも確認してください。認証、権限・モデル、請求上限、リクエスト形式のエラーを[公式エラーリファレンス](https://platform.claude.com/docs/en/api/errors)と照合し、どの失敗にも新しい有料生成が必要だとは判断しないでください。 `skill-response.json`に生成済みの`file_id`があり、失敗したのがダウンロードだけなら、その応答を保存し、同じ権限のあるワークスペースへのアクセスでメタデータとダウンロードを調べます。既存の出力を取得するために生成ブロックを再実行してはいけません。リクエストの結果が不明なら、リクエストIDを保存して状態を確認してから、次の生成を送信します。新しい生成が必要だと判断した後に限り、出力先を未使用のパス、たとえば`out = Path("skill-output-attempt-2")`へ変更し、`exist_ok=False`は維持します。新しいフォルダーは上書きを防ぎますが、APIの二重課金は防ぎません。 ## 必要なファイル権限 Files APIでは、ファイルはアプリケーションの個々のユーザーや会話ではなく、ワークスペースに関連付けられます。ドキュメントによると、そのワークスペースにアクセスできるAPIキーなら、アップロードされたファイルにアクセスできます。この例では、生成時とダウンロード時に同じキーを使います。エンドユーザーやその他の信頼できない送信元から`file_id`を受け取らないでください。これらのIDはサーバーに保存し、ユーザーとファイルの対応関係は独自のアプリケーション内で管理してください。 ファイルのメタデータは個別に確認してください。`downloadable: true`が含まれている必要があります。ドキュメントでは、スキルまたはコード実行ツールが生成したファイルのダウンロードが許可されています。アップロードしたファイルは`downloadable: false`となり、ダウンロードを試みると400が返されます。ワークスペースへのアクセス権と、特定ファイルをダウンロードする権限は、それぞれ別の要件です。 複数ユーザー向けのアプリケーションでは、ファイル分離の境界としてクライアントごとに別のワークスペースを使うことをFiles APIのドキュメントが推奨しています。この推奨はファイルに関するものです。関連するAPIを確認せずに、すべてのエンティティや権限にまで適用しないでください。 ## 既製スキルとカスタムスキル 既製スキルのIDは`pptx`、`xlsx`、`docx`、`pdf`です。[スキル一覧のリファレンス](https://platform.claude.com/docs/en/api/skills/list.md)では、`custom`ソースはワークスペース内で非公開、`anthropic`ソースは共有かつ読み取り専用と説明されています。 最初の例にある`version: "latest"`は、スキルの公開済みバージョンのうち最新のものを意味します。再現可能な統合にする場合は、この選択対象が変わり得ることに留意してください。固定バージョンに切り替えるには、例から架空のIDを作るのではなく、使用するスキルの既存バージョンを選ぶ必要があります。 ## 制限事項と次のステップ この例が扱うのは、既製スキルでプレゼンテーションを作成し、ダウンロードすることだけです。カスタムスキルのアップロードや削除、サードパーティサービスへのアクセスは、ここではテストしていません。これらの作業には、該当するAPIを別途確認する必要があります。 Claudeインターフェース上のファイルを扱う場合は、[Claudeにファイルをアップロードする方法](https://ailoot.ai/blog/ja/claude-file-upload/)の別ガイドをご覧ください。直接呼び出す場合は、[APIトークン使用量の計算方法](https://ailoot.ai/blog/ja/api-token-usage-calculation/)をご覧ください。ターミナルエージェントで作業する場合は、[Claude Codeスキルの選び方](https://ailoot.ai/blog/ja/choose-claude-code-skills/)をお読みください。スキルの接続方法が異なります。 最初の確認には、既製の`pptx`スキルを1つ使えば十分です。応答を確認し、ダウンロードが許可されたファイルをダウンロードして開いてください。カスタムスキルやクライアント間のアクセス分離は、その確認を終えてから追加します。 準備ができたら、[Ailoot](https://ailoot.ai/)をご覧ください。 ## Claude APIのAgent Skills：Claude Codeなしで既製スキルを使う方法：よくある質問 ### file_idが返ればプレゼンテーションは完成ですか？ IDはファイルが返されたことを示すだけです。メタデータの`downloadable: true`を確認し、ワークスペースへのアクセス権でダウンロードして開き、形式、スライド数、文章を確認してください。 ### Claude Files APIへアップロードされたファイルはすべてダウンロードできますか？ いいえ。このガイドは、生成ファイルの`downloadable: true`と、アップロードファイルの`downloadable: false`を区別しています。ワークスペースへのアクセス権と、そのファイルのダウンロード可否は別です。利用者から任意のファイルIDをそのまま受け付けないでください。 ## Ailoot · 企業とそのプロジェクト群 Ailootは、蓄積した運営経験、幅広い顧客基盤、安定したサービス、継続的なKPI管理を基盤としています。 企業とそのプロジェクト群：数百万の顧客、毎月数十億規模の売上。 Ailootはこの運営経験を、お客様の製品、エージェント、アプリケーション、自動化でAI機能を利用するためのAPIアクセスに活かしています。