Claude Codeのskill-doctorとは — 未使用スキルとコストの調べ方

/skill-doctorでできること

/skill-doctorは、読み込まれているのに一度も使われていないスキルと、それぞれがコンテキストに載せ続けているコストを一覧で見せるコマンドです。プラグイン由来のスキルも対象に含まれます。1回実行するだけで、削る候補とその手当ての両方が分かります。

よく似た名前の/doctorは別のコマンドで、インストールや設定の不具合を診断する点検です。使い方は/doctorとclaude doctorを扱った記事にあります。スキルの使用状況とコストを見たいときは/skill-doctorを打ちます。

必要なバージョンは、公式ページによって書き方が違います。changelogではv2.1.261の項目に「/skill-doctorを追加」とあり、コマンド一覧とスキルのページは「v2.1.252以降」を要件にしています。手元がv2.1.252〜v2.1.260で補完に出ないときは、更新してから試すのが確実です。

実行結果に何が載るか

レポートが対象にするのは、バンドルスキルとエンタープライズスキルを除いた、そのセッションのスキルです。一度も呼ばれていないスキルにフラグを立て、どこで無効化すればよいかを添えます。無効化の候補のうち、コンテキストコストが高いものから手を付けるのが近道です。しばらく使っていないプラグインの一覧も、同じレポートに載ります。組織全体の利用はOpenTelemetryのイベントで測れます。プラグインの導入と利用をOpenTelemetryで測る方法に整理しています。

対話セッションでは、レポートは/pluginマネージャーのStatsタブで開きます。-pを付けた非対話モードでは、そのままテキストとして標準出力に出ます。

実行する手順

/skill-doctor

claude -p "/skill-doctor"

実行できないケース

/skill-doctorはAnthropicから取得するfeature flag(機能フラグ)に依存しています。次の3条件のどれかに当たると使えません。

Skill usage reports are not available on this connection.

この文面は、エラー一覧にも同じ原文で載っています。セッションが実際に動いている端末そのもので/skill-doctorを実行するか、その端末上でclaude -p "/skill-doctor"を動かせばレポートが見られます。

見つけた未使用スキルをどう減らすか

未使用として出てきたスキルも、毎ターンのコンテキストを使い続けます。個人・プロジェクトのスキルは、skillOverrides設定の値で対処の粒度を選べます。

/doctorは、v2.1.205以降のバンドルスキルとして扱われ、disableBundledSkillsを有効にしても打てます。隠したいときはDISABLE_DOCTOR_COMMAND環境変数か、skillOverridesの"doctor": "off"を使います。バンドルスキルと組み込みコマンドの境界は、両者の違いを扱った記事にあります。

プラグイン経由のスキルはskillOverridesの対象外です。止めたい場合は/pluginからそのプラグイン自体を無効化するか、アンインストールします。

/skillsメニューで切り替える

設定ファイルを書き換える代わりに、/skillsコマンドから直接切り替える方法もあります。一覧でスキルを選んでSpaceキーを押すと状態が順に切り替わり、Escで確定すると.claude/settings.local.jsonに書き込まれます。"user-invocable-only"の状態は、メニューではuser-onlyと表示されます。

文字を打てば名前・説明・提供元で絞り込めます。tキーでトークン数の多い順に並べ替えると、/skill-doctorが挙げた高コストの候補を上から探せます。

このメニューで切り替えられないスキルもあります。対象外は3種類です。プラグインのスキルと、frontmatterにdisable-model-invocation: trueを書いたスキル。それに、managed settingsや--settingsフラグでskillOverridesが決まっているスキルです。

frontmatterで止めるか、settingsで止めるか

SKILL.mdを編集できるかどうかで、止め方の選択肢が分かれます。

"off"にしたスキルをフルネームで呼び出すと、実行されずにskillOverridesのエラーが返ります。なお、/skill-doctorが未使用として指摘するのは、Claudeの一覧に載っているスキルです。disable-model-invocation: trueのスキルは説明文がコンテキストに載らないため、指摘の対象から外れやすくなります。

スキル一覧のコンテキスト予算とのつながり

Claude Codeは毎ターン、有効なスキルの名前と説明文の一覧をコンテキストへ載せます。この一覧はコンテキストウィンドウの既定1%(skillListingBudgetFraction)に収まるよう予算管理されていて、予算を超えると呼び出し頻度の低いスキルから順に説明文が削られます。名前自体は必ず残りますが、説明文が消えるとClaudeがそのスキルを自分の判断で選びにくくなります。

一覧全体の見積もりと内訳の大きい順を知りたいなら/doctorを、個々のスキルの要否まで踏み込みたいなら/skill-doctorを使います。/doctorが大きい順の内訳を出し、/skill-doctorが未使用かどうかを示すので、役割は重なりません。

予算を広げる手段は2つあります。skillListingBudgetFractionを上げる(例は0.02で2%)か、SLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で文字数を固定します。各スキルの説明文には上限もあり、skillListingMaxDescChars(既定1,536文字)で変えられます。

予算を超えたときは、デバッグログにも警告が出ます。--debug付きで起動すると見えます。/contextのSkills行は予算を適用した後の一覧の大きさを示します。v2.1.196より前は、全説明文の全文を数えていたため、設定した予算の数倍の値が出ることがありました。

コンテキストコストの数字が何を表すか

/skill-doctorが示す「コスト」は、changelogでは「コンテキストに占めるコスト(what they cost in context)」と書かれています。プラグイン単位でこの内訳をコンポーネントごとに見る手段として、claude plugin detailsがあります。v2.1.289のclaude plugin --helpでは、このサブコマンドの説明が「Show a plugin's component inventory and projected token cost」です。

claude plugin details formatter

このコマンドはセッション内ではなくシェルで実行します。対象のプラグインは、インストール済み、スキルディレクトリ内、または--plugin-dirで渡したもののどれかで、読み込まれている必要があります。出力は次のような形になります(公式ドキュメントの例に沿った形)。

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)は別枠で計上されます。入っていない名前を渡すと、v2.1.289では次のメッセージが返ります。

Plugin "nonexistent-xyz" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.

見積もりに含まれるのはスキルとエージェントです。コマンドはスキルの一部として数えられ、format-allのようなコマンドはSkillsの下に並びます。hookは「harness-only」でトークンコストの計算対象に入らず、MCPサーバーのツールスキーマも実行時に解決されるため、見積もりには出てきません。

MCPサーバーがどれだけコンテキストを使っているかは、そのプラグインを有効にしたセッションで/contextを実行し、MCP toolsのカテゴリで見ます。

数値の大小をどこで判断するかの目安もあります。公式マーケットプレイスのプラグイン詳細画面にはContext cost欄があり、Every turn:の常時コストが2,000トークン以上になると強調表示されます。自分のマーケットプレイスのプラグインには、この欄がありません。

他の使用状況の見え方との違い

未使用のスキルやプラグインを知る手段は/skill-doctorだけではありません。知りたい対象と立場で使う面が変わります。

「Not used recently」の表示にも例外があります。このラベルが付かないプラグインがあります。--plugin-dir経由やスキルディレクトリから読み込んだもの。managed settingsで有効化されたものと、seed directoryから載せたもの。テーマ・出力スタイル・モニター・ワークフローを含むものも同じです。このうちテーマなどを含むプラグインは、呼び出しが記録されない形で使われているため、ラベルの対象になりません。

言語サーバー(LSP)を含むプラグインは、診断やコードナビゲーションのリクエストに応答した時点で「使用済み」と数えられます。組織がstrictKnownMarketplacesを設定している場合は、見出しもLast used:の行も表示されません。

組織で複数マシンの利用状況をまとめて把握したい管理者には、OpenTelemetryイベントや、Enterpriseプランで使えるAnalytics APIという横断的な経路も別に用意されています。

コンテキストの逼迫はスキルだけが原因とは限りません。MCPサーバーが返すツール定義も同じように毎ターンのコンテキストを圧迫します。この側面はMCPのツール定義がコンテキストを圧迫する理由の記事で扱っています。余白が実際にどれだけ残っているかは/contextで見ます。手順はコンテキストウィンドウを可視化する記事にあります。

スキルの効き目を測りたいとき

未使用でなくても、「入れているスキルが本当に効いているか」を確かめたい場面があります。公式のスキルのページでは、実際のプロンプトを数本用意し、スキルありとなしで新しいセッションを走らせて比べる手順を挙げています。

スキルを外す方法は出どころで変わります。個人・プロジェクトのスキルならskillOverridesで"off"にします。プラグインのスキルにはskillOverridesが効かないため、各実行をプラグインなしでも繰り返すclaude plugin evalを使います。

v2.1.289のclaude plugin --helpでは、evalの説明が「Run eval cases ... against a plugin and report scored results」です。エラー一覧にはplugin evalがearly accessである旨のメッセージもあります。

まとめ

/skill-doctorの指摘は、削る候補を絞るための材料です。止める前に、そのスキルの出どころが個人・プロジェクト、プラグイン、バンドルのどれかを確かめれば、効かない設定を書く手間を避けられます。プラグイン単位の固定費はclaude plugin detailsの記事で測れます。