Claude Codeに「/claude-api cost-optimize」が追加──既存プロジェクトのAPI支出を測って1つずつ削るコマンド

3行まとめ

1. /claude-apiはAnthropicが公開しているOSSスキルリポジトリ（github.com/anthropics/skills）の一部で、SKILL.mdはmigrate・prompt-audit・upgrade・managed-agents-onboardという4つのサブコマンドをルーティングするテーブルを持つ
2. 本記事で該当リポジトリのSKILL.mdを直接curlして確認したところ、CHANGELOGが挙げているcost-optimizeサブコマンドも、Admin API対応の記載も、このファイルの中には見当たらなかった。公開リポジトリの内容が、Claude Code本体に組み込まれているスキルの実体と、必ずしも同じタイミングで同期されているとは限らない
3. /claude-apiスキル全体は、モデルの選択・SDKのAPI仕様変化（extended thinkingのパラメータ変更など）・言語ごとのSDK差異を横断的にカバーする、外部ドキュメントへの誘導を中心にした設計になっている

Claude APIを組み込んだ自作アプリの請求額が想定より高い——そう気づいたとき、何から手をつければいいかを一緒に洗い出してくれるコマンドが、Claude Codeに追加された。GitHubのanthropics/claude-codeリリースページでバージョン2.1.247（2026年8月26日公開）のCHANGELOGを確認したところ、次の一文がある。

Added /claude-api cost-optimize to profile an existing project's Claude API spend and work through cost levers (caching, token hygiene, batch, effort, model choice) one measured change at a time

（既存プロジェクトのClaude API支出をプロファイルし、コスト施策——キャッシュ、トークンの整理、バッチ、effort、モデル選択——を1つずつ、測定しながら試せる「/claude-api cost-optimize」を追加）

同じCHANGELOGのすぐ下には、もう1行ある。

Updated the /claude-api skill with Admin API coverage (organization members, invites, workspaces, API keys, rate limit reports, workload identity federation, CMEK)

（/claude-apiスキルをAdmin APIの対応範囲——組織メンバー、招待、ワークスペース、APIキー、レート制限レポート、ワークロードアイデンティティ連携、CMEK——で更新）

つまり/claude-apiはこのリリース単発の新機能ではなく、既存の/claude-apiスキルに新しいサブコマンド（cost-optimize）が生えた、という位置づけで書かれている。

挙げられている5つの施策

CHANGELOGの一文が名指ししているコスト施策は5つ——caching（キャッシュ）、token hygiene（トークンの整理）、batch（バッチ処理）、effort（推論の労力設定）、model choice（モデル選択）——である。これらはいずれもAnthropic公式ドキュメントに個別の仕組みとして存在する（プロンプトキャッシュ、Batch API、Claude Opus 5などで導入されたeffortパラメータ、モデルごとの価格差）。cost-optimizeコマンドが新しいのは、これらを横断してプロジェクトの実際の支出データからどれが効くかを測りながら1つずつ試す、という進め方を自動化している点だとCHANGELOGの一文からは読み取れる。

「5つの施策」は独立には効かない――effortを変えるとキャッシュが無効化される

CHANGELOGはcaching・token hygiene・batch・effort・model choiceを横並びの5つの施策として挙げているが、Anthropic公式ドキュメント「Prompt caching」の「What invalidates the cache」表をcurlで確認すると、そのうち2つは独立に組み合わせられない関係にあることが分かる。

Changing the output_config.effort value always invalidates message blocks, with the same model-specific effect on tool and system caches as thinking parameters. Setting effort explicitly to the model's default is equivalent to omitting it and does not invalidate.

（訳：output_config.effortの値を変更すると、常にメッセージブロックのキャッシュが無効化される。tool・systemキャッシュへの影響も、thinkingパラメータと同じくモデルごとに異なる。effortをモデルのデフォルト値に明示的に設定した場合は、指定しなかった場合と同等でキャッシュは無効化されない）

つまり、cost-optimizeが挙げる「effort（推論の労力設定）を下げてコストを削る」という施策と「caching（プロンプトキャッシュ）でコストを削る」という施策は、同じリクエストの中で両方を気軽に変更すると、片方の変更がもう片方の効果を打ち消しうる。公式ドキュメントの「プロンプトのプリウォーム」の項でも「follow-upリクエストと同じthinking設定・output_config.effortを使うこと。異なる設定でプリウォームすると、実際のトラフィックが決してヒットしないキャッシュエントリを書き込むだけになる」と明記されている。CHANGELOGの一文は5つの施策を並列に列挙しているが、実際に手を動かして最適化する側は、この順序依存・相互作用を把握したうえで「どれを先に固定し、どれを後から調整するか」を決める必要がある——という点は、CHANGELOGの1行やSKILL.mdの現行スナップショットのどちらにも書かれていない。

Admin API対応は「新機能の追加」ではなく「既存APIをスキルの参照範囲に含めた」という話

CHANGELOGが挙げるAdmin APIの対応範囲——「organization members, invites, workspaces, API keys, rate limit reports, workload identity federation, CMEK」——を、Anthropic公式のAdmin APIドキュメントと1項目ずつ突き合わせた。結果は次の表の通りで、7項目すべてが、このリリース以前から存在するAdmin APIの既存セクションに対応していた。

つまり今回のCHANGELOGの「Admin API coverage」という一文は、Admin API自体に新しいエンドポイントが追加されたことを意味するのではなく、/claude-apiスキルがモデルに提供する参照情報（SKILL.md・sharedドキュメント）の中に、既存のAdmin APIの範囲がまとまって組み込まれた、と読むのが正確だ。この記事の冒頭で確認した通り、今回curlしたSKILL.mdの現行スナップショットにも、参照しているshared/live-sources.mdのURL一覧にも、Admin API関連の記載は見当たらなかった——CHANGELOGが指す変更は、この記事で確認できた公開リポジトリの状態にはまだ反映されていないことになる。

CHANGELOGに書かれていないこと

一方で、このコマンドが具体的にどのデータを見て「支出をプロファイル」するのか——Admin APIのUsage & Cost APIを叩くのか、ローカルのセッションログを見るのか、あるいは対象プロジェクトのコードを読んでキャッシュヒット率を推定するのか——は、CHANGELOGの1行には書かれていない。「1つずつ、測定しながら（one measured change at a time）」という表現から、施策を一括適用するのではなく段階的に効果を確認する設計だとは読み取れるが、その測定方法や、変更前後の比較をどう提示するのかという具体的な出力形式は本記事の調査範囲では確認できなかった。

個人開発者にとっての意味

Claude APIを直接叩くアプリやスクリプトを運用していると、キャッシュを効かせ忘れている、必要以上に高いeffortで呼んでいる、バッチにできる処理を同期で回している、といった「気づけば直せる」無駄は珍しくない。/claude-api cost-optimizeが実際に有効なのは、こうした既存プロジェクトのコードとAPI呼び出しパターンを横断的に洗い出す作業を、手作業でやらずに済む点にある。ただし、このコマンド自体がClaude Codeのセッションとして動く以上、コマンドの実行自体にもトークンとコストがかかる。コスト削減を目的にコストのかかるコマンドを回すという構造そのものは、CHANGELOGのどこにも注意書きがない。

公開リポジトリの実物を確認した結果

/claude-apiというコマンド名から、これがAnthropicの公開スキルリポジトリ（github.com/anthropics/skills）に含まれるclaude-apiスキルのサブコマンドだと推測できたため、実際にそのソース（skills/claude-api/SKILL.md）をcurlで取得して読んだ。このファイルは、Claude Code Codeが/claude-api <subcommand>を実行したときにどのサブコマンドへルーティングするかを決めるテーブルを持っており、確認できたのは次の4つだった。

CHANGELOGが挙げていたcost-optimizeというサブコマンド、および「Admin API coverage」の記載は、今回取得した版のSKILL.mdには見当たらなかった。つまり、v2.1.247のCHANGELOGが指す/claude-apiスキルの更新は、この記事で確認できた公開リポジトリのスナップショットには、まだ反映されていない可能性がある。公開OSSリポジトリと、Claude Code本体に実際に組み込まれているスキルの実体が、常に同じタイミングで同期されているとは限らない、ということがこの突き合わせから分かる。

このスキル自体の設計思想も、SKILL.mdの記述からうかがえる。「訓練時点の知識が古い可能性がある（API Drift）」という注意書きがあり、extended thinkingのパラメータが{type: "enabled", budget_tokens: N}から{type: "adaptive"}に変わった、web検索ツールのタイプ名が更新された、といった具体的な「変わった点」の一覧を、モデルが記憶に頼らずこのファイルを都度参照するよう仕向ける作りになっている。cost-optimizeが実装されているとすれば、同じ設計思想——モデルの記憶ではなく、都度参照するドキュメントに基づいて判断させる——の上に乗る形になると推測できるが、これは公開されている類似サブコマンドの設計パターンからの推測であり、cost-optimize自体の実装を確認した上での話ではない。

コマンドを実際に実行して検証したわけではない

• この記事を書いている自分の手元のClaude CodeはこのCHANGELOGの対象バージョンであるv2.1.247そのものだが、cost-optimizeコマンドを実際に自分のプロジェクトに対して走らせ、どんな出力が返ってくるかまでは検証していない。Anthropic有料APIへの実際の課金を伴う検証は本セッションの方針上行っていないため、コマンドが提示する削減提案の精度や、施策ごとの効果の測り方についての一次情報は本記事にはない
• cost-optimizeサブコマンドが、公開リポジトリ（anthropics/skills）にまだ反映されていないのか、あるいはClaude Code内蔵の別実装（このリポジトリとは別の場所で管理されている実体）として存在するのかは、本記事の調査範囲では判別できなかった
• SKILL.mdが参照しているshared/以下の個別ドキュメント（プロンプトキャッシュ・モデル移行ガイドなど）のうち、コスト関連の内容を持つと思われるファイルの中身までは、本記事では網羅的に読み込んでいない
• Admin APIの対応範囲として挙げられている「organization members, invites, workspaces, API keys, rate limit reports, workload identity federation, CMEK」それぞれの具体的な変更内容についても、CHANGELOGの1行以上の情報は確認できていない

関連記事: Claude・GPT・Gemini API料金の読み方 / Claude Codeとは / Claude Codeがエラーで動かない時の切り分け手順

感想・指摘はコメント欄へ。