Claude Codeのclaude-apiスキルでAPI移行を自動化する

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

引数なしで/claude-apiとだけ打つとサブコマンドを選ぶ入り口が開き、migrate・managed-agents-onboard・prompt-auditのいずれかをその場で選べます。最初からサブコマンド名まで分かっているときは、上記のように直接続けて実行すれば1手で済みます。

3つのサブコマンドで役割が分かれる

/claude-apiは引数なしでも起動しますが、3つのサブコマンドを渡すことで用途を絞り込めます。

3つは対象が異なります。migrateはコード(SDK呼び出し・モデルID指定)を対象に、managed-agents-onboardは新規構築のプロセスを対象に、prompt-auditは自然文の指示(プロンプト・スキルの説明文・ツールの説明文)を対象にします。同じモデル移行の作業でも「コードを直す」のか「指示文を直す」のかで使うサブコマンドが変わる、という切り分けがこのスキルの実務上の要点です。

migrateサブコマンドが担う範囲

migrateは既存のClaude APIコードを新しいモデルへ引き上げる作業を担当します。このスキル自体もモデル移行の変化に合わせて更新され続けてきました。当初はClaude Opus 4.8への対応と4.7→4.8の移行ガイダンスが追加され、その後Claude Opus 5がデフォルトのOpusモデルになった際には、Opus 5をデフォルトとしつつOpus 4.8からの移行パスも案内する内容へ更新されています。モデルの世代が変わるたびに、スキルの中身が新しい移行パスへ差し替えられる運用です。

コンテキストコストは200k超から25kへ圧縮された

claude-apiスキルは参照ドキュメントの分量が大きく、フルロードするとコンテキストを大きく消費する構造でした。この点は運用上の弱点として認識されており、v2.1.234で改善が入っています。参照ドキュメントをオンデマンドで読み込む方式に変わったことで、スキルを読み込むコンテキストコストが約20万トークン超から約2.5万トークンまで圧縮されました。

この変更は自動起動の実務に直結します。anthropicのインポートを検知するたびに大きなコンテキストを消費していた状態から、必要な部分だけを都度読み込む状態へ変わったことで、SDKを使うプロジェクトで日常的にこのスキルが自動起動しても、セッションの残りコンテキストを圧迫しにくくなりました。自動起動そのものを嫌ってオプトアウトする必要性が下がった、と捉えられます。

エージェント設計のガイダンスも並行して拡張されてきた

claude-apiスキルはモデル移行の案内だけでなく、エージェント設計パターンの助言も担っています。ツールサーフェス(Claudeに与えるツールの数と粒度)をどう決めるか、コンテキスト管理をどう設計するか、キャッシュ戦略をどう組むかといった観点でのガイダンスが追加され、その少し後にはManaged Agentsの扱いもスキルの対象へ組み込まれました。SDKで単発のAPI呼び出しを書くだけの用途から、Managed Agentsを含むエージェント設計全般を相談できる範囲へと役割が広がってきた経緯があります。

自動起動が働かない・気づきにくい場面

自動起動はanthropicまたは@anthropic-ai/sdkのインポートを検知する仕組みなので、検知の前提が崩れる場面では手動で呼び出す必要があります。典型的なのは、SDKを直接インポートせずHTTP経由でClaude APIを叩いているコードや、依存パッケージの内部でだけSDKを使っていてアプリケーションコード側には該当するインポート文が出てこない構成です。どちらもプロジェクト内に検知対象のインポート文自体が存在しないため、自動起動の対象外になります。ライブラリ越しにSDKを間接的に使っているだけのプロジェクトでは、自動起動を当てにせず/claude-apiで明示的に呼び出したほうが確実です。

3つ目は、Skillそのものの可視性設定です。/skillsでスキルの一覧を確認でき、スペースキーでClaudeや/メニューへの見え方を切り替えられます。組織のポリシーで一部のバンドルスキルを無効化している環境では、インポートを検知してもclaude-apiスキルが起動しないことがあります。自動起動が働かないと感じたら、まず/skillsでclaude-apiが無効化されていないかを確認するのが早道です。

いつ手動で/claude-apiを呼ぶべきか

自動起動に任せておけば大半のケースはカバーされますが、コードをまだ書いていない段階では話が変わります。モデル選定やAPI設計の相談だけしたいとき、あるいはManaged Agentsを新規に作る計画段階でmanaged-agents-onboardのウォークスルーを始めたいときは、そもそもインポート文が存在しないため自動起動が働きません。手動で/claude-apiを呼び出す必要があります。もう1つ、自動起動の対象内でもあえて手動で呼ぶ価値があるのが、大きなモデル移行(Opus 4.8→5のような世代交代)の直後です。コードだけでなくプロンプトやスキルの説明文も含めて棚卸しをしたいときはprompt-auditが主役になり、検出パターンと実際の使い方は/claude-api prompt-auditで古いモデル向けの記述を検出するで扱っています。

migrateとmanaged-agents-onboardの実務上の分かれ目

migrateとmanaged-agents-onboardはどちらも新しいものへ向かう作業を助けるサブコマンドですが、出発点が違います。migrateは「すでに動いているClaude APIコードがあり、それを新しいモデルへ引き上げたい」という既存コード起点の作業です。対してmanaged-agents-onboardは「まだManaged Agentを作っていないが、これから作りたい」というゼロからの構築を対話形式で案内します。すでにManaged Agentsを運用していて、そこで使うモデルだけを引き上げたい場合はmanaged-agents-onboardではなくmigrateを選ぶことになります。

この切り分けを誤ると、既存のManaged Agent設定を新規構築のウォークスルーに乗せてしまい、無関係な初期設定の質問に付き合わされることがあります。「モデルを上げたいだけなのか」「Managed Agentそのものを新しく作りたいのか」を先に自分の中で言語化してからサブコマンドを選ぶと、余計なやり取りを避けられます。

よくある質問

claude-apiスキルはどのプランでも使えますか

スキル自体はClaude Codeにあらかじめ同梱されたバンドルスキルで、プラン専用の機能ではありません。手元の環境で/claude-apiが見当たらない場合は、まず/skillsで可視性設定を確認し、それでも解決しなければバージョンが古い可能性があるので/statusでアップデートの要否を確認してください。

anthropicをインポートしていないのに自動起動しました

検知対象はanthropicまたは@anthropic-ai/sdkのインポート文です。書いた覚えがない場合は、プロジェクト内のインポート文をanthropicで検索すると、どのファイルが検知の起点になっているかを特定できます。

migrateとprompt-auditはどちらを先に使うべきですか

コードのモデルID指定やAPI呼び出しを新しいモデルに合わせて直すのが先です。migrateでコードを更新したあとにprompt-auditを走らせると、コード側の変更と整合した状態でプロンプト・スキル・ツール説明の古い記述を洗い出せます。

まとめ

claude-apiスキルはanthropicまたは@anthropic-ai/sdkのインポートを検知して自動起動し、migrate・managed-agents-onboard・prompt-auditの3サブコマンドでコード移行・新規Managed Agents構築・プロンプトの棚卸しを使い分けます。v2.1.234でコンテキストコストが約20万トークン超から約2.5万トークンへ圧縮されたことで、SDKを日常的に使うプロジェクトでも自動起動のコストを気にしにくくなりました。モデルの世代交代のたびにコードをmigrateで直したら、prompt-auditで指示文側の棚卸しも忘れずに行うのが実務上の使い分けです。