Claude Codeのclaude-apiスキルでAPI移行を自動化する
anthropicインポートで自動起動するclaude-apiスキルの仕組みと、8つのサブコマンドの最低バージョン、自動起動が効かないときの確認手順をまとめます。
claude-apiスキルはコードを書いた瞬間に自動起動する
claude-apiスキルは、Claude Codeにあらかじめ同梱されているバンドルスキルの1つです。/claude-apiで明示的に呼び出せますが、実務ではそれより先に自動起動するケースのほうが多くなります。プロジェクトのコードがanthropicまたは@anthropic-ai/sdkをインポートしていると、Claude Codeはそれを検知してこのスキルを自動的に有効化します。手元でSDKを使ったコードを書き始めた瞬間に、Claude APIとManaged Agentsのリファレンス知識がClaudeの手元に揃う仕組みです。
自動起動が意味するのは「毎回インストラクションを唱えなくても、AnthropicのSDKを触るコードベースではClaudeが最新のAPI仕様を前提に動く」という点です。モデルIDの命名規則、パラメータの意味、Managed Agentsのセッション設計など、SDKを跨いだ細部を確認しながら書き直す手間が減ります。バンドルスキルの仕組み自体は自作スキルと共通です。frontmatterの書き方や呼び出し制御はClaude Code Skills完全ガイドにまとめています。
プロジェクトの言語に合わせて内容が変わる
claude-apiスキルが読み込むリファレンス素材は、プロジェクトの言語に応じて変わります。公式の説明でも「your project's language」向けのClaude APIとManaged Agentsのリファレンス素材を読み込むとされています。Pythonのプロジェクトを開いているときとTypeScriptのプロジェクトを開いているときとで、Claudeが参照する具体例やSDKの呼び出し方は同じ内容の使い回しではありません。1つのマシンで複数言語のプロジェクトを行き来する開発者でも、プロジェクトを切り替えるたびに手動で言語を伝え直す必要がない設計です。
/claude-api migrateサブコマンドはスキル名のあとに続けて打ちます。サブコマンド名まで分かっているときは、上記のように直接続けて実行すれば1手で済みます。
8つのサブコマンドと、それぞれの最低バージョン
サブコマンドは全部で8つあり、公式のスキル解説ページに用途と「最低バージョン」の表があります。migrateとmanaged-agents-onboardは表が追う最古のv2.1.221より前から存在し、残りは追加されたバージョンが表に書かれています。手元のClaude Codeが古いと、記事にあるサブコマンドが存在しないことがあります。筆者の環境ではv2.1.285(claude --versionの出力は2.1.285 (Claude Code))で、8つすべてが対象に入るバージョンです。
| サブコマンド | 何をするか |
|---|---|
migrate | 何をするか既存のClaude APIコードを新しいモデルへアップグレードする |
managed-agents-onboard | 何をするか新しいManaged Agentを作るウォークスルーを進める |
prompt-audit | 何をするかプロンプト・スキル・ツール説明の中から古いモデル向けの記述を見つけ、修正案を差分で提案する(v2.1.221以降) |
upgrade | 何をするかAnthropic SDK依存をメジャーバージョンまたぎで移す。現状の対象はPythonのanthropicパッケージ0.xから1.x(v2.1.236以降) |
cost-optimize | 何をするか支出の内訳を調べ、プロンプトキャッシュ・入出力トークンの削減・バッチ処理・effort・モデル選択などの節約策を1件ずつ提案する(v2.1.247以降) |
build-eval | 何をするかClaudeを使うアプリの評価セットを作る(v2.1.259以降) |
hillclimb | 何をするか既存の評価セットに対してアプリを反復的に改善する(v2.1.259以降) |
preserved-thinking-migration | 何をするか過去のターン・システムプロンプト・ツール一覧への編集のうち、preserved thinkingのブロックを無効にするものを探し、失われる推論量を測って1件ずつ直す(v2.1.282以降) |
upgradeだけは、公式ページ同士で数字が食い違っています。スキル解説の表は「v2.1.236以降」ですが、変更履歴で/claude-api upgradeの追加が書かれているのはv2.1.239の項目です。v2.1.236(2026年8月19日)の項目には見当たりません。どちらが正しいかは公式の記述だけでは決められないため、upgradeを使うつもりなら、確実なv2.1.239以降にそろえておく形になります。
症状別にサブコマンドを選ぶ
サブコマンドが8つあると、名前だけでは選びにくくなります。対象が「コード」「指示文」「支出」「評価」のどれかで切り分けると迷いません。
- SDK呼び出しやモデルID指定といったコードを直すなら
migrateです。 - プロンプトやスキル、ツールの説明文といった自然文の指示は
prompt-auditの担当になります。 - これから作るManaged Agentの手順を知りたいときに使うのが
managed-agents-onboardです。 - すでに動いているアプリの支出を見直したいなら、
cost-optimizeが入り口です。 - 品質を測って上げる作業は、
build-evalとhillclimbが受け持ちます。
同じモデル移行の作業でも「コードを直す」のか「指示文を直す」のかで使うサブコマンドが変わる、という切り分けがこのスキルの実務上の要点です。
migrateとmanaged-agents-onboardは出発点で選ぶ
どちらを呼ぶかは、いまの状態で決まる
migrate
Claude APIを呼ぶコードは動いていて、モデルだけを新しいものへ引き上げたい場合です。すでにManaged Agentsを運用していて、使うモデルだけを上げたいときもこちらを選びます。
managed-agents-onboard
Managed Agentをこれから作る場合です。対話形式で、ゼロからの構築手順を案内します。
すでに動いているManaged Agentがあるなら、新規構築向けのウォークスルーを選ぶ理由はありません。「モデルを上げたいだけなのか」「Managed Agentそのものを新しく作りたいのか」を先に決めてから、サブコマンドを選びます。
スキルの中身はどう変わってきたか
claude-apiスキルは、Claude Codeの変更履歴でたびたび更新されています。モデル移行の案内、エージェント設計の助言、コンテキストコストの圧縮と、更新の種類はいくつかに分かれます。
claude-apiスキルの主な更新(変更履歴より)
- v2.1.69スキルが追加された
Claude APIとAnthropic SDKでアプリを作るためのスキルとして登場しました。
- v2.1.91〜98エージェント設計とManaged Agentsが対象に入った
ツールサーフェス(Claudeに与えるツールの数と粒度)・コンテキスト管理・キャッシュ戦略の助言が加わり、その後Managed Agentsも同じスキルの対象になりました。
- v2.1.154Opus 4.8への移行案内
Opus 4.8の対応と、4.7から4.8への移行ガイダンスが入りました。
- v2.1.219Opus 5がデフォルトに
デフォルトがClaude Opus 5に変わり、Opus 4.8からの移行パスも案内する内容になりました。
- v2.1.234コンテキストコストの圧縮
参照ドキュメントの読み込みが軽くなりました(次節)。
モデルの世代が変わるたびに、スキルの中身は新しい移行パスへ差し替えられる運用です。最近の更新はもっと細かく、たとえばv2.1.282では拒否時の課金の説明が更新されました。出力の途中で拒否された場合は通常料金で課金され、出力の前に拒否された場合はレート制限に数えられる、という内容です。Managed Agentsのリソースをバージョン管理されたファイルとして持つためにant applyを勧める記述も、同じ版で入っています。
コンテキストコストは200k超から25kへ圧縮された
claude-apiスキルは参照ドキュメントの分量が大きく、以前はフルロードするとコンテキストを大きく消費する構造でした。
v2.1.234でのコンテキストコストの変化
以前
約20万トークン超
参照ドキュメントをまとめて読み込む方式
v2.1.234以降
約2.5万トークン
参照ドキュメントをオンデマンドで読み込む方式
この変更は自動起動の実務に直結します。anthropicのインポートを検知するたびに大きなコンテキストを消費していた状態から、必要な部分だけを都度読み込む状態へ変わりました。そのため、SDKを使うプロジェクトで日常的にこのスキルが自動起動しても、セッションの残りコンテキストを圧迫しにくくなりました。自動起動そのものを嫌ってオプトアウトする必要性が下がった、と捉えられます。
自動起動が働かない・気づきにくい場面
自動起動はanthropicまたは@anthropic-ai/sdkのインポートを検知する仕組みなので、検知の前提が崩れる場面では手動で呼び出す必要があります。公式に書かれている検知条件は、コードがanthropicまたは@anthropic-ai/sdkをインポートすることです。SDKを直接インポートせずHTTP経由でClaude APIを叩くコードや、ライブラリ越しにSDKを使うだけでアプリ側にインポート文が無い構成では、自動起動を当てにしにくくなります。そのようなプロジェクトでは、/claude-apiを明示的に呼び出す運用が確実です。
もう1つの原因は、スキルそのものが見えなくなっている場合です。claude-apiはバンドルスキルなので/skillsには載りません。設定の確認手順を解説する公式ページによると、バンドルスキルは/contextのスキル欄に出るため、確認の入り口が違います。無効化の手段は2つあり、disableBundledSkillsは同梱スキルとワークフローをまとめて取り除きます。skillOverridesは1つのスキルだけを対象に、次の4つの状態を選べます。
| 値 | Claudeに名前と説明が見えるか | /メニューに出るか |
|---|---|---|
"on" | Claudeに名前と説明が見えるか名前と説明の両方 | /メニューに出るか出る |
"name-only" | Claudeに名前と説明が見えるか名前だけ | /メニューに出るか出る |
"user-invocable-only" | Claudeに名前と説明が見えるか見えない | /メニューに出るか出る |
"off" | Claudeに名前と説明が見えるか見えない | /メニューに出るか出ない |
"off"にされたスキルは、フルネームで呼んでも実行されず、skillOverridesが原因であるエラーが返ります。"user-invocable-only"は、Claudeには一覧として渡されず、人が/で打ったときだけ動く状態です。インポート検知による自動起動がこの設定より優先されるのかは、公式の記述からは読み取れません。skillOverridesにエントリがないスキルは"on"として扱われるので、何も書いていなければ制限はありません。
disableBundledSkillsをtrueにした場合、同梱スキルは取り除かれますが、/initのような組み込みコマンドは打てるままで、モデルの一覧から隠れるだけです。自動起動が働かないと感じたときは、次の順に確認するのが早道です。
自動起動が働かないときの確認順
- 1
コンテキストの中身を見る
/contextのスキル欄にclaude-apiがあるかを確認します。あれば、スキルはClaudeに見えていて、利用できる状態です。 - 2
設定ファイルを見る
skillOverridesにclaude-apiのエントリがないか、disableBundledSkillsがtrueになっていないかを確認します。disableBundledSkillsはどの設定ファイルにも書けるため、ユーザー・プロジェクト・管理者のどの層で入っているかも見ます。環境変数CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1でもセッション単位で同梱スキルを無効にできるため、こちらも確認します。 - 3
同名のスキルがないか探す
プロジェクトやユーザーの
claude-apiという名前のスキルは、同名のバンドルスキルを置き換えます。自作のスキルがあると、同梱のリファレンスは読み込まれません。
いつ手動で/claude-apiを呼ぶか
自動起動に任せておけば大半のケースはカバーされますが、コードをまだ書いていない段階では話が変わります。モデル選定やAPI設計の相談だけしたいときが該当します。Managed Agentsを新規に作る計画段階でmanaged-agents-onboardのウォークスルーを始めたいときも同じです。どちらもそもそもインポート文が存在しないため自動起動が働きません。手動で/claude-apiを呼び出します。
もう1つ、自動起動の対象内でもあえて手動で呼ぶ価値があるのが、大きなモデル移行(Opus 4.8→5のような世代交代)の直後です。コードだけでなくプロンプトやスキルの説明文も含めて棚卸しをしたいときはprompt-auditが主役になります。検出パターンと実際の使い方は/claude-api prompt-auditで古いモデル向けの記述を検出するで扱っています。既存コードのコスト見直しはcost-optimizeが担当です。詳しい手順は/claude-api cost-optimizeでAPIコストを段階的に削減するにまとめました。
使えない面もあります。v2.1.285では、/claude-apiをRemote Controlのクライアントから実行できないように変更されました。Remote Control経由で起動しようとして動かないときは、手元のターミナルで実行します。評価まわりの手直しも続いており、v2.1.284ではhillclimbが「評価で測れないほど小さなプロンプトの言い換え」に周回を費やさなくなりました。v2.1.285では、評価の実行用スキャフォールドが集計するとき、max_tokensで打ち切られた応答を平均に混ぜず、別枠で数えるようになっています。
よくある質問
skillOverridesで"off"にすると、Remote ControlやAgent SDKからも消えますか
消えます。Claude Codeのv2.1.199以降、"off"はターミナルの/メニューからそのスキルを隠します。Remote ControlのクライアントとAgent SDKの呼び出し側に渡すコマンド一覧からも隠れます。フルネームで呼んだ場合は、実行されずにskillOverridesが原因であるエラーが返ります。/claude-apiが一覧に出ないときは、手元のバージョンが古い可能性もあるため、claude --versionでサブコマンド表の最低バージョンと照らしてください。
anthropicをインポートしていないのに自動起動しました
検知対象はanthropicまたは@anthropic-ai/sdkのインポート文です。書いた覚えがない場合は、プロジェクト内のインポート文をanthropicで検索すると、どのファイルが検知の起点になっているかを特定できます。
まとめ
このスキルは、自動起動に任せる場面と手動で呼ぶ場面を分けると扱いやすくなります。アプリのコードにSDKのインポート文がある間は任せておき、HTTP直叩きやライブラリ越しの利用、コードを書く前の相談では最初から/claude-apiを呼びます。モデルの世代交代では、コードをmigrateで直してからprompt-auditで指示文を洗うと、コード側の変更と整合した状態で古い記述を拾えます。