Claude Code /doctorを実行したら警告が出た

診断してみようと思って/doctorを実行した。

するとこんなのが出た。

Skill listing will be truncated
48 descriptions dropped (full descriptions kept for
most-used skills) (3.1%/1% of context): plan-tune,
design-html, qa, +45 more
    run /skills to disable some, or raise
    skillListingBudgetFraction (currently 1%) in
    settings.json

最初は無視しようかと思ったが、48個が切り捨てられているって？

---

どういう意味か

Claude Codeは会話を開始するたびにインストールされたスキルの一覧をコンテキストに読み込む。

でもコンテキストに使えるバジェットがあって、スキルが増えると説明テキストがそのバジェットを超えてしまう。

超えた分は単純に切り捨てられる。

現在の設定では全コンテキストの1%しかスキル一覧に使えないように設定されていて、スキルが多すぎて48個の説明が消えている状況だった。

---

解決法A：バジェット比率を上げる

settings.jsonでskillListingBudgetFractionの値を上げればいい。

{
  "skillListingBudgetFraction": 0.03
}

デフォルト値の0.01(1%)から0.03(3%)程度に上げると、切り捨てられていたスキルの説明が再び読み込まれる。

ファイルの場所は~/.claude/settings.jsonまたはプロジェクトの.claude/settings.json。

ただし、これによりセッションごとにスキルの説明に使うトークンが増える。/doctorの出力にも示されているように約6kトークン程度。よく使うスキルが多いならこちらの方が合っている。

---

解決法B：使っていないスキルを無効化する

/skills

このコマンドを実行するとインストールされたスキルの一覧が表示される。そこから実際に使っていないものを切ってしまえばいい。

gstackを23個、superpowersをいくつかインストールしていても、実際に毎日使うのは5個以下かもしれない。

使っていないものを切るのがすっきりする。コンテキストの無駄もなくなるし、/doctorも静かになる。

---

どちらを選ぶべきか

スキルを多く使う → A（バジェット比率を上げる）

スキルはたくさんインストールしているが実際に使うのは数個だけ → B（無効化）

両方やっても構わない。

---

「most-used skills」はどう決まるのか

Claude Codeは実際に呼び出したスキルをトラッキングしている。

よく使うスキルは説明全体をコンテキストに保持し、ほとんど使っていないスキルは説明を切り捨てる。

つまり、切り捨ては完全にランダムではない。ある程度インテリジェントに動いている。

ただし、落とし穴がある。

新しくインストールしたスキルや、しばらく使っていなかったスキルは、すでに説明が切り捨てられている可能性がある。

/skillnameと打ってもClaudeが認識しない — 「そんなスキルはないです」という反応が返ってくる — のはこのケースかもしれない。

だから、/skillsで不要なスキルを無効化した後は、必ず/doctorを再度実行して警告が消えたことを確認するべきだ。

---

実際にどう確認するか

順番にやっていけばいい。

• /doctorを実行 → 現在の切り捨て状況と、どのスキルが落とされているか確認
• /skillsを実行 → インストールされた全スキルと現在の有効/無効状態を確認
• 実際によく使うスキルを把握する
• 使っていないスキルはトグルで無効化
• /doctorを再実行 → 警告が消えたことを確認

settings.jsonは2か所に存在できる。

• ユーザーレベル：~/.claude/settings.json — 全プロジェクトに適用
• プロジェクトレベル：.claude/settings.json — そのプロジェクトのみに適用

両方存在する場合、プロジェクト設定がユーザー設定を上書きする。skillListingBudgetFractionを変更する前に、どのレベルで適用するかを決めておく — 全体に反映したいなら~/.claude/settings.json、プロジェクトごとに設定を変えたいなら.claude/settings.json。

---

一言まとめ

/doctorの警告を無視しても動作はするが、切り捨てられたスキルはClaudeが認識できない。

実際に使うスキルがちゃんと読み込まれているか、一度確認した方がいい。