Claude Codeのskill-doctorの使い方で未使用スキルを洗い出す
/skill-doctorは、読み込まれたまま一度も呼ばれていないスキルと各スキルのコンテキストコストを一覧にするコマンドです。実行手順とskillOverridesでの減らし方を扱います。
/skill-doctorでできること
/skill-doctorは、読み込まれているのに一度も使われていないスキルと、それぞれがコンテキストに載せ続けているコストを一覧で見せるコマンドです。プラグイン由来のスキルも対象に含まれます。1回実行するだけで、削る候補とその手当ての両方が分かります。このコマンド自体は、Claude Codeのv2.1.261で新しく追加されました。
実行結果に何が載るか
レポートが対象にするのは、バンドルスキルとエンタープライズスキルを除いた、そのセッションのスキルです。一度も呼ばれていないスキルにフラグを立て、どこで無効化すればよいかを添えます。無効化の候補として示されたスキルは、コンテキストコストが高いものから手を付けるのが近道です。加えて、しばらく使っていないプラグインの一覧も同じレポートに載ります。
対話セッションでは、レポートは/pluginマネージャーのStatsタブで開きます。-pを付けた非対話モードでは、そのままテキストとして標準出力に出ます。
実行する手順
対話セッションでは、プロンプトからそのまま呼び出します。
/skill-doctor非対話モードで動かしたい場合は、シェルから直接呼び出せます。
claude -p "/skill-doctor"実行できないケース
/skill-doctorはAnthropicから取得するfeature flag(機能フラグ)に依存しています。DISABLE_GROWTHBOOK・DISABLE_TELEMETRY・DO_NOT_TRACK・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICのいずれかを設定したセッションでは、この取得自体が行われません。Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry・Claude Platform on AWSのようなサードパーティ経由のセッションと、Claude apps gatewayのセッションも同様で、いずれも/skill-doctorは使えません。
Remote Control(スマートフォンやブラウザーから端末セッションへ接続する機能)経由で実行した場合も対象外です。コマンドが失敗するのではなく、次の応答が返ります。
Skill usage reports are not available on this connection.レポートを見るには、セッションが実際に動いている端末そのもので/skill-doctorを実行するか、その端末上でclaude -p "/skill-doctor"を動かします。
見つけた未使用スキルをどう減らすか
レポートに未使用として出てきたスキルは、放置しても実害はありませんが、毎ターンのコンテキストを食い続けます。対処の粒度はskillOverrides設定の値で選べます。
| 状況 | skillOverridesの値 | 効果 |
|---|---|---|
| Claudeにも自分にも見せたくない | skillOverridesの値"off" | 効果Claudeの一覧にも/補完にも出なくなる |
| たまに手動で呼ぶが自動発火は要らない | skillOverridesの値"user-invocable-only" | 効果Claudeの一覧からは消えるが/nameは打てる |
| 存在は残したいが説明文の分のコンテキストだけ削りたい | skillOverridesの値"name-only" | 効果名前だけ残り、descriptionとwhen_to_useの分が消える |
| バンドルスキル・ワークフローをまとめて止めたい | skillOverridesの値disableBundledSkills: true | 効果/doctorを除く全部が対象になる |
プラグイン経由のスキルはskillOverridesの対象外です。止めたい場合は/pluginからそのプラグイン自体を無効化します。バンドルスキルと組み込みコマンドの境界はバンドルスキルと組み込みコマンドの違いの記事で扱っています。
手で設定ファイルを書き換える代わりに、/skillsコマンドから直接切り替える方法もあります。一覧でスキルを選んでSpaceキーを押すと4状態が順に切り替わり、Escで確定すると.claude/settings.local.jsonに書き込まれます。文字を打てば名前・説明・提供元でも絞り込めるので、/skill-doctorが挙げた候補をここから探すと手早く済みます。tキーを押すとトークン数の多い順に並べ替えられるので、コストの高いスキルから手を付けたいときはこちらが近道です。
"off"はv2.1.199以降、端末の/メニューだけでなく、Remote Control(スマートフォンやブラウザーから接続するクライアント)やAgent SDK経由の呼び出し元に見せるコマンド一覧からも同じスキルを外します。設定はどこからでも変えられますが、SKILL.md自体を編集できるスキルであれば、frontmatterにdisable-model-invocation: trueを書く方法もあります。こちらはClaudeの自律的な呼び出しだけを止め、ユーザーが/nameで手動起動する経路は残す設定です。
そもそも/skill-doctorが対象にするのは、一覧に載っているのに一度も呼ばれていないスキルに限られます。disable-model-invocation: trueを設定したスキルはこの一覧自体に出ないため、コンテキストコストがかからず、レポートの指摘対象にもなりません。未使用として指摘されるのは、いま一覧に載って毎ターンのコストを払い続けているスキルだけです。
スキル一覧のコンテキスト予算とのつながり
Claude Codeは毎ターン、有効なスキルの名前と説明文の一覧をコンテキストへ載せます。この一覧はコンテキストウィンドウの既定1%(skillListingBudgetFraction)に収まるよう予算管理されていて、予算を超えると呼び出し頻度の低いスキルから順に説明文が削られます。名前自体は必ず残りますが、説明文が消えるとClaudeがそのスキルを自分の判断で選びにくくなります。
一覧全体の見積もりと内訳の大きい順を知りたいなら/doctorを、個々のスキルの要否まで踏み込みたいなら/skill-doctorを使います。両方を突き合わせると、予算超過の主因がどのスキルなのかまで追えます。予算を広げたい場合はskillListingBudgetFractionを上げるか、各スキルの説明文の上限を決めるskillListingMaxDescChars(既定1,536文字)を調整します。
コンテキストコストの数字が何を表すか
/skill-doctorが示す「コスト」は、公式ドキュメントの言葉では「コンテキストに占めるコスト(what they cost in context)」です。プラグイン単位でこの内訳をコンポーネントごとに見る手段として、claude plugin detailsがあります。
claude plugin details formatter出力は次のような形になります(公式ドキュメントの例に沿った形)。
Projected token cost
Always-on: ~146 tok added to every session
Per-component (rounded)
component always-on on-invoke
format-code ~40 ~30
lint-fix ~50 ~30この例のプラグインは、名前と説明文だけで毎セッション約146トークンを常時消費します。実行されて初めて追加でかかる分(on-invoke)は別枠で計上されます。
見積もりに含まれるのはスキルとエージェントだけです。コマンドはスキルの一部としてこの内訳に含まれますが、hookは「harness-only」としてトークンコストの計算対象に入らず、MCPサーバーが提供するツールのスキーマも実行時に解決される扱いで、この見積もりには出てきません。MCPサーバーがどれだけコンテキストを使っているかを知りたいときは、そのプラグインを有効にしたセッションで/contextを実行し、MCP toolsのカテゴリを確認します。
数値の大小をどこで判断するかの目安もあります。公式マーケットプレイスのプラグイン詳細画面にはContext cost欄があり、Every turn:の常時コストが2,000トークン以上になると強調表示されます。プラグイン単位のコストを見る目安として、この2,000トークンという線は覚えておく価値があります。
他の使用状況の見え方との違い
未使用のスキルやプラグインを知る手段は/skill-doctorだけではありません。知りたい対象と立場で使う面が変わります。
| 面 | 何が分かるか | 誰が使うか |
|---|---|---|
/skill-doctor | 何が分かるか未使用スキルと個々のコンテキストコスト | 誰が使うか自分のセッション |
/pluginのInstalledタブ | 何が分かるか14日かつ10セッション以上未使用の「Not used recently」表示 | 誰が使うか自分のセッション |
/doctor | 何が分かるか未使用のスキル・MCPサーバー・プラグインの一覧と無効化の推奨 | 誰が使うか自分のセッション |
/usage | 何が分かるか直近の使用量に占めるスキル・サブエージェント・プラグイン・MCPサーバーの割合(Pro/Max/Team/Enterprise限定) | 誰が使うか自分のセッション |
claude plugin details <name> | 何が分かるかプラグインが毎セッション必ず載せるトークン量のコンポーネント別内訳 | 誰が使うかプラグインの作者・保守者 |
「Not used recently」の表示にも例外があります。--plugin-dir経由やスキルディレクトリから読み込んだプラグイン、組織の管理者設定で強制有効化されたプラグイン、テーマ・出力スタイル・モニター・ワークフローを含むプラグインには、このラベルが付きません。呼び出しという行為そのものが記録の対象にならない、または常に使われている扱いになるためです。言語サーバー(LSP)を含むプラグインは、診断やコードナビゲーションのリクエストに応答した時点で「使用済み」と数えられます。ここまでは自分のセッションから見える範囲ですが、組織で複数マシンの利用状況をまとめて把握したい管理者には、OpenTelemetryイベントやAnalytics APIという横断的な経路も別に用意されています。
コンテキストの逼迫はスキルだけが原因とは限りません。MCPサーバーが返すツール定義も同じように毎ターンのコンテキストを圧迫します。この側面はMCPのツール定義がコンテキストを圧迫する理由の記事で扱っています。実際にどれだけ余白が残っているかを/contextで確認する手順はClaude Codeのコンテキストウィンドウを可視化する記事を参照してください。
よくあるつまずき
- バージョンが古くてコマンドが出ない:
/skill-doctorはv2.1.261で追加された機能です。それより前のバージョンでは/補完にも表示されません - Bedrock・Google Cloud's Agent Platformなどで動かない: サードパーティのプロバイダー経由のセッションはfeature flagの取得をスキップするため、対象から外れます。サードパーティ経由でないセッションで、
DISABLE_GROWTHBOOK等の4つの環境変数を設定せずに実行します - スマホから実行したのに結果が出ない: Remote Control越しの実行はレポートを送らない仕様です。「Skill usage reports are not available on this connection.」と表示されたら、セッション本体の端末で実行し直します
- バンドルスキルが対象に見当たらない: レポートの対象は自作スキルとプラグインのスキルで、バンドルスキルとエンタープライズスキルは最初から集計に入りません
まとめ
/skill-doctorは、読み込まれているのに一度も呼ばれていないスキルと、そのコンテキストコストを1コマンドで洗い出します。対話セッションでは/pluginのStatsタブに開き、-pでは標準出力にテキストで出ます。Bedrock・Google Cloud's Agent Platformのようなサードパーティ経由のセッションとRemote Control越しの実行では使えません。見つかった未使用スキルはskillOverridesを"off"・"name-only"・"user-invocable-only"のいずれかに設定し、バンドルスキルごと止めたいときはdisableBundledSkillsを使います。同じ「使われているか」を知る手段は/doctorや/usageにもあるので、知りたい粒度に応じて使い分けます。