Claude CodeのskillOverridesとmodelOverridesの使い方

skillOverridesとmodelOverridesで何ができるか

skillOverridesは個別Skillの表示状態を、modelOverridesはAnthropicモデルIDのプロバイダー固有値へのマッピングを、それぞれsettings.jsonのキー単位で制御する設定です。どちらも管理者専用のキーではありません。user・project・local・managedのどのスコープに書いても有効です。

Claude Code組織管理ガイドがmanaged settings全体の配信経路を扱うのに対し、この記事は2つのキーの値・優先順位・効かないケースだけを掘り下げます。個別のSKILL.mdを書き換えずにSkillを隠したい、あるいはBedrockやFoundryでモデルIDを固定のARNやデプロイ名にルーティングしたい、という具体的な場面で読む記事です。settings.jsonの全フィールドを辞書的に引きたい場合はClaude Code設定ガイドを、SKILL.mdの書き方やfrontmatterの制御を先に押さえたい場合はClaude Code Skills完全ガイドを参照してください。

skillOverridesでSkillの表示状態を制御する

skillOverridesは、Skill名をキーに4段階の状態を割り当てる設定です。SKILL.mdのfrontmatterを編集せずに、共有リポジトリに置かれたSkillの見え方を変えられます。

値は4種類あります。

設定はJSONで書きます。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

skillOverridesに書かれていないSkillはon扱いです。/skillsメニューからも操作できます。対象のSkillを選んでSpaceキーで状態を巡回させ、Enterで確定すると.claude/settings.local.jsonに書き込まれます。

v2.1.199以降、offにしたSkillはRemote ControlクライアントとAgent SDK呼び出し元に提示されるコマンド一覧からも除外されます。それ以前は端末の/メニューだけが対象でした。ただしoffにしたSkillの名前を直接指定して呼び出そうとすると、実行はされずskillOverridesに由来するエラーが返ります。存在自体が消えるわけではありません。

バンドルSkillにも同じ仕組みが使えます。v2.1.205以降、/doctorは組み込みコマンドからバンドルSkillに変わりましたが、disableBundledSkills: trueで全体を無効化しても/doctorだけは有効なまま残ります。/doctorだけを隠したい場合はskillOverridesに"doctor": "off"を追加します。

プラグインが提供するSkillにはskillOverridesが効きません。無効化や更新は/pluginメニュー、または/plugin uninstallから行います。

modelOverridesでモデルIDをプロバイダー固有値にマップする

modelOverridesは、AnthropicモデルIDをプロバイダー固有の文字列に変換するマッピングです。ユーザーが/modelピッカーで対応するエントリを選ぶと、Claude CodeはビルトインのモデルIDの代わりに設定した値をAPIへ送ります。

エンタープライズの管理者が、モデルのバージョンごとにAmazon Bedrockの推論プロファイルARN、Google Cloud's Agent Platformのバージョン名、Microsoft Foundryのデプロイ名を個別に割り当てたいときに使います。ANTHROPIC_DEFAULT_OPUS_MODELのようなファミリー単位の環境変数では、同じファミリー内の複数バージョンを別々のIDにマップできません。そこがmodelOverridesの出番です。

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  }
}

キーはModels overviewに載っているAnthropicモデルIDそのものを使います。日付付きIDなら日付部分も含めて正確に書きます。存在しないキーは黙って無視されます。

v2.1.200以降、--modelフラグやANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL系の環境変数で直接指定したモデルIDも、このマッピングを経由するようになりました。それより前のバージョンでは、これらの経路で指定した値はマッピングを通らずプロバイダーへそのまま送られていました。

modelOverridesに載っていないIDを送ると、Claude Codeはそのまま実行を続けつつ[claude-code:unrecognized_model]という診断行を出力します。LLMゲートウェイのエイリアスのように意図して未知のIDを使っている場合、そのIDを値にしたmodelOverridesのエントリを追加すれば診断行は止まります。

{
  "modelOverrides": {
    "claude-opus-4-6": "my-proxy-model"
  }
}

availableModelsとの併用では、許可リストの評価対象はマッピング後の値ではなく元のAnthropicモデルIDです。管理設定でenforceAvailableModelsが有効なとき、強制されるDefaultモデルは最高優先度の管理設定ソースが持つmodelOverridesだけを経由して解決されます。userやprojectの設定に書いたマッピングは、このDefaultの解決には影響しません。

Amazon Bedrockでは、Claude Codeが起動時に推論プロファイルを自動検出する仕組みがありますが、modelOverridesのエントリはこの自動検出結果より優先されます。自動検出されたプロファイルと手動で指定したいARNが競合する場合は、modelOverridesに明示的なエントリを書けば確実にそちらが使われます。Bedrock推論プロファイルARNやFoundryのデプロイ名のように、値がすでにプロバイダーネイティブな形式であれば、Claude Codeはそのままの形でプロバイダーへ渡します。Bedrock経由で認証やcontent-type関連のエラーに当たった場合は、Bedrock content-typeエラーの原因と対処が切り分けの入口になります。

skillOverridesとmodelOverridesはどこが違うか

対象もキーの意味も異なりますが、どちらも「個別のSKILL.mdやモデル選択ロジックを直接いじらずに、settings.json側から挙動を差し替える」という設計は共通しています。

managed settingsの文脈で語られがちな2つのキーですが、実際にはmanaged-only設定の一覧には入っていません。個人のuser設定やproject設定に置いても普通に効きます。組織で統一したい場合だけ、managed settingsの配信経路に載せる、という順番で考えると混乱しません。

設定が反映されているかを確認する

skillOverridesは/skillsメニューを開けば即座に確認できます。offにしたSkillは一覧そのものから消え、name-onlyにしたSkillは説明文だけが空欄になります。設定ファイルを直接編集した場合も、保存後にこのメニューを開けば反映を確認できます。

modelOverridesは/modelピッカーの表示だけでは反映を確認しにくいキーです。手早く確認したいときは、対象のIDでリクエストを送ったあとに[claude-code:unrecognized_model]の診断行が出ていないかを見る方法が実務的です。マッピングが効いていれば、Claude Codeが認識できないIDとして扱うことはなく診断行も出ません。診断行は--debug付きで起動したセッションのデバッグログか、-p実行時のstderrに出力されます。

GUI操作とsettings.json直接編集はどちらを使うべきか

Skillの状態は/skillsメニューからも、skillOverridesをsettings.jsonへ直接書いても変えられます。両者は最終的に同じキーへ書き込むため、結果に違いはありません。差はスコープの選びやすさです。/skillsメニューは常に.claude/settings.local.json(その端末・そのリポジトリだけに効く)へ書き込みます。チーム全体やuser設定に対して統一したい場合は、対象のスコープのsettings.jsonを直接編集する方が確実です。

モデル側にはGUI操作の代替がありません。modelOverridesは常に対象の設定ファイルを直接編集して設定します。書き込み先を.claude/settings.local.jsonにするかuser・project・managedのどのスコープにするかは、/skillsメニューのようなGUI経由の操作がないぶん、編集するファイルパスを自分で選ぶ形になります。

よくある質問

skillOverridesとfrontmatterのdisable-model-invocationはどちらを使うべきですか

SKILL.mdを自分で編集できるならdisable-model-invocation: trueで十分です。共有リポジトリのSkillのように編集したくない、あるいはできない場合にskillOverridesを使う、という使い分けになります。両方が同時に指定された場合の優先順位は公式ドキュメントに明記されていないため、片方だけを設定する運用が安全です。

modelOverridesの値はどのプロバイダーでも同じ形式ですか

いいえ。Bedrockでは推論プロファイルARN、Foundryではデプロイ名、Google Cloud's Agent Platformではバージョン名を渡します。いずれもプロバイダー側がすでにネイティブな形式として認識する値を、Claude Codeがそのまま渡す仕組みです。

skillOverridesで一度offにしたSkillを完全に削除できますか

skillOverridesは表示状態を切り替えるだけで、Skill自体のファイルは残ります。ファイルごと削除したい場合は.claude/skills/配下から直接削除するか、プラグイン由来のSkillなら/plugin uninstallを使います。

modelOverridesを設定してもモデルピッカーに反映されないのはなぜですか

availableModelsが管理設定で有効な場合、--modelフラグや環境変数経由のIDに効くmodelOverridesは最高優先度の管理設定ソースにあるものだけです(v2.1.200以降)。userやprojectの設定に書いたマッピングは、この経路では無視されます。

まとめ

skillOverridesはSkill名をキーにした4段階の表示制御、modelOverridesはAnthropicモデルIDをプロバイダー固有値に変換するマッピングです。どちらもmanaged-only専用キーではなく、個人のuser設定からでも書けます。組織全体で統一したいときだけ、managed settingsの配信経路に載せて統制する、という順番で考えると設計がぶれません。