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

訂正（2026年9月10日）：初出時の中心的な主張「cost-optimizeとAdmin API対応は公開リポジトリのSKILL.mdに見当たらない＝同期ズレがある」は誤りでした。取得し直したところ両方とも記載されており、当該ファイルの最終更新（2026年9月1日）は本記事の公開より前です。該当箇所を訂正しました。

3行まとめ

1. /claude-apiはAnthropicが公開しているOSSスキルリポジトリ（github.com/anthropics/skills）の一部で、SKILL.mdはmigrate・prompt-audit・upgrade・managed-agents-onboardという4つのサブコマンドをルーティングするテーブルを持つ
2. 【2026-09-10 訂正】初出時、SKILL.mdにcost-optimizeもAdmin API対応も「見当たらなかった」と書いたが誤りだった。取得し直すと同ファイルにはcost-optimizeのルーティング行（shared/cost-optimization.mdを読ませる指示）もAdmin APIの記述も含まれている。このファイルの最終更新は2026年9月1日で、本記事の公開（9月7日）より前なので、公開時点でも反映済みだった
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の範囲がまとまって組み込まれた、と読むのが正確だ。（2026-09-10 訂正：初出時はここに「SKILL.mdにもAdmin API関連の記載は見当たらなかった」と書いていたが誤りで、取得し直すと同ファイルにAdmin APIの記述は含まれている。詳細は後述の訂正箇所を参照。）

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つだった。

【2026-09-10 訂正】 初出時、ここに「cost-optimizeと『Admin API coverage』の記載は今回取得した版のSKILL.mdには見当たらなかった」「公開リポジトリにはまだ反映されていない可能性がある」と書いたが、これは誤りだった。同じURL（raw.githubusercontent.com/anthropics/skills/main/skills/claude-api/SKILL.md）を取得し直すと、ルーティングテーブルにcost-optimizeの行があり、「Reduce what existing Claude API code costs to run, without sacrificing output quality. Read shared/cost-optimization.md immediately」という指示と、トークン内訳を「the Usage and Cost Admin API」で測る手順が書かれている。Admin APIへの言及も同ファイル内に複数ある。GitHubのコミット履歴で見ると、このファイルが最後に更新されたのは2026年9月1日で、本記事の公開日（9月7日）より前である。つまり公開時点で既に反映されており、「公開リポジトリとClaude Code本体の同期ズレ」という本記事の見立て自体が成り立たない。初出時の確認が不十分だった（取得したファイルは85KBあり、該当行を読み落としたと考えられる）。

このスキル自体の設計思想も、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）のSKILL.mdに反映済みだった（2026-09-10訂正）。ただしSKILL.mdが読ませているshared/cost-optimization.mdの中身までは、本記事では確認していない
• 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がエラーで動かない時の切り分け手順

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