【中級者向け】Claude APIでMessages APIを直接叩いたことがある人、「anthropic-beta」ヘッダーを扱ったことがある人を対象にしています。Skills機能自体を初めて触る人でも、curlの読み方さえ分かれば読み進められます。
Claude APIをプロキシ経由で使っている開発者のOSSに、こんなIssueが立っていました。「Skillsを一切使っていないはずの、普通のチャット補完リクエストが400エラーで落ちる」。
原因はたった1行、「skills-2025-10-02」というベータヘッダーを全リクエストに無条件で付けていたことでした。
Claude APIのAgent Skills(「/v1/skills」)は2026年8月19日にベータを卒業し、「skills-2025-10-02」ヘッダーが不要になった。ヘッダーを送り続けても動作は変わらないが、「条件付きで送る」実装をしていた場合はGA後もバグの温床になり得る。Skills APIには「code_execution」ツールが必須という制約は変わっていない。TL;DR
え、Claude APIでSkillsを使う場合、ベータヘッダーを送り続けても大丈夫ですか？
結論から言うと、送り続けても動作は変わりません。ただし『どう送っているか』によっては、GAになったこと自体が引き金でバグが表面化することがあります
この記事でできること
Claude Skills API(「/v1/skills」)が2026年8月19日にベータから正式版(GA)へ移行した際の公式発表内容と、実際に他の開発者が踏んだ移行時の不具合を、Anthropic公式ドキュメントとGitHub上の実例で確認します。
- Skills APIが具体的に何をするAPIで、GA前後で何が変わったか(変わっていないか)が分かる
- 自分のSkillsコード(自作・プロキシ・SDK)がGA後も安全かどうかをチェックする観点が分かる
- SKILL.mdの作成からMessages APIへのアタッチまで、公式スキーマに基づいた実装手順が分かる
対象読者
Claude APIをMessages API経由で直接、またはSDK/自作プロキシ経由で利用している開発者。「Skills」という単語は知っているが、Claude Code上のローカルSkillsとClaude API上のSkills APIの違いがあいまいな人も対象に含みます。
逆に、claude.aiのブラウザ上でSkillsを使うだけの人(API呼び出しをしない人)には、この記事の大部分は関係しません。
対象と参照資料
- 対象: Claude APIの「/v1/skills」エンドポイント群と「code_execution_20250825」以降のcode executionツール
- 参照: Anthropic公式ドキュメントと公開GitHub Issue/PR（2026-09-24確認）
背景：なぜベータヘッダーというものがあるのか
Claude APIの新機能は、いきなり正式版として公開されるわけではありません。多くは「anthropic-beta」というHTTPヘッダーに機能名とバージョン日付(例: 「skills-2025-10-02」)を指定することで、実験的に有効化する形でスタートします。
この仕組みにより、Anthropicは互換性を壊さずに新機能を試験運用でき、開発者側も「まだ仕様が変わるかもしれない機能」だと認識した上で使えます。
Agent SkillsもFiles APIやComputer Useと同様、この仕組みでベータ提供されていました。そして2026年8月19日、Anthropicはこれらをまとめて正式版に昇格させています。公式リリースノートには次のように記載されています。
Agent Skills and the Skills API (/v1/skills) are out of beta on the Claude API. Requests no longer require the skills-2025-10-02 beta header, including Messages API requests that load Skills through the container parameter.Claude Platform Docs Release Notes (2026-08-19)
同じ発表の中で、Computer Use・Browser Use・Files APIも同時にベータを卒業しました。1つの機能が単独でGAになったのではなく、Claude APIのエージェント関連機能がまとめて足並みを揃えた形です。
ここで見落とされやすいのが「ヘッダーが不要になった」ことと「ヘッダーが禁止された」ことは別だという点です。公式ドキュメントには、ヘッダーを送り続けても動作は変わらないと明記されています。廃止期限も明言されていません。
つまり急いで消す必要はない一方、「ヘッダーを送るとエラーになる」という前提で書かれた条件分岐コードがあった場合、GA移行のタイミングでその分岐がおかしな挙動を起こす、という逆向きの罠が生まれます。
何が便利なのか
GA前後で何が変わり、何が変わっていないかを整理すると、次のようになります。
| 項目 | ベータ期間 | GA後(2026-08-19〜) |
| 「anthropic-beta: skills-2025-10-02」ヘッダー | 必須(無いとSkills機能が有効にならない) | 不要(省略可)。送っても引き続き動作 |
| 「/v1/skills」のCRUD操作 | 利用可能 | 変更なし(スキーマも同一) |
| Messages APIでの「container.skills」指定 | 利用可能 | 変更なし |
| 「code_execution」ツールの同時指定 | 必須 | 変わらず必須 |
| カスタムSkillの共有範囲 | ワークスペース全体 | 変更なし |
| SDKのベータ名前空間(「client.beta.skills」) | 唯一の呼び出し方 | 「client.skills」でも同じ形が呼べる(新しいSDKバージョン) |
表で一番見落とされやすいのは4行目です。GAになったのは「ベータヘッダーが要らなくなった」という手続き面の話であり、「Skillsを使うにはcode executionツールが要る」という機能面の制約自体はそのまま残っています。
ここを混同すると、次のセクションで紹介する実例のような事故につながります。
じゃあ、もうベータヘッダーのことは全部忘れていいってことですか？
消しても問題は起きません。でも、もし『Skillsを使うときだけこのヘッダーを付ける』という条件分岐を書いていたなら、その分岐ロジックごと見直したほうがいいです。次の章で実際に起きた例を見てみましょう
必要なもの
- Claude APIのAPIキー(「ANTHROPIC_API_KEY」)
- 「curl」または各言語の公式SDK(本記事の例はcurlベース。SDKでも「client.skills.create()」のように同じ操作ができます)
- Skillsを実行に使う場合は「code_execution_20250825」以降のツール指定
- SKILL.mdを作る場合はテキストエディタとzip化の手段(本記事ではPython標準ライブラリの「zipfile」を使用)
全体像
Skills APIを使う流れは、大きく3ステップです。
- SKILL.mdを含むファイル一式を作り、「/v1/skills」へアップロードして「skill_id」を得る
- Messages APIのリクエストで、「container.skills」に「skill_id」を指定し、「code_execution」ツールを併せて指定する
- Claudeがそのタスクに関連すると判断したときだけ、SKILL.mdの内容を読み込んで実行する(常に全文がコンテキストに乗るわけではない)
400エラーの原因とベータヘッダーの見直し方は無料部分で確認できます。購入後は、Claude APIで使う自作Skillを「SKILL.md作成→zip化→Skills API登録→Messages APIから呼び出す」まで手順に沿って進められます。レスポンスと実行ログで呼び出しを確かめる方法、動かない時の切り分け、SDK更新時の確認点も載せています。添付のPythonツールキットにはzip作成・ヘッダー判定例・コンテキストコスト概算を収録。API呼び出しにはAnthropic APIキーが別途必要です。
この記事の販売者
