SKILL
BUDGET

Claude Code にはあらかじめ搭載された機能に加えて、あとから追加できる「専門家モジュール」がある。これがスキルだ。

たとえば 「バグを調べてほしい」 と伝えたとき、Claude Code は gstack-investigate というスキルを呼び出して体系的なデバッグを行う。「アイデアを整理したい」 と伝えれば、brainstorm-facilitator が起動してブレインストーミングをサポートする。

スキルにはそれぞれ 「説明文」 が付いている。Claude はこの説明文を読んで、ユーザーの依頼とスキルを照合し、「このスキルを今使うべきか」を判断する。

スキルの説明文は、Claude が
「どのスキルをいつ使うか」を判断する
唯一の手がかりだ。

Skill System — Claude Code

説明文がなければ、Claude はそのスキルの存在を「知っていても使い方がわからない」状態になる。本棚に本があるのに、タイトルが読めない状態に近い。

すべてのスキルの説明文を、毎回まるごと Claude に渡すことはできない。トークン（処理コスト）の問題があるからだ。

Claude Code には 「スキル一覧に使ってよいコンテキストの割合」 を制限する設定がある。それが skillListingBudgetFraction だ。

この設定は、Claude Code のバイナリ（本体ファイル）の中に次のように定義されている：

skillListingBudgetFraction: number
  .gt(0).lte(1)
  .describe(
    "Fraction of the context window reserved for
      the skill listing sent to Claude
      (default: 0.01 = 1%).
      When the list exceeds this, descriptions are
      shortened to fit."
  )

つまり、デフォルト（初期状態）では コンテキスト全体のわずか1% しかスキルの説明文に割り当てられていない。

デフォルトの1%がいかに狭いか、視覚的に確認しよう。

Claude Code の診断コマンド /doctor を実行したとき、衝撃的な一行が表示された。

Skills
  Skill listing will be truncated
    18 descriptions dropped
    (full descriptions kept for most-used skills)
    (5.8%/5% of context)

  affected: document-skills:xlsx, document-skills:docx,
           document-skills:claude-api, +15 more

  run /skills to disable some, or raise
  skillListingBudgetFraction (currently 5%) in settings.json

18個のスキル説明文が「落とされていた」。 5%の枠をスキル一覧が5.8%分オーバーしていたため、使用頻度の低いスキルの説明文が自動的に省略されていたのだ。

また、説明文が「省略」される方法は2種類ある：

スキルの説明文が省略されると、何が起きるのか。具体的に考えてみよう。

Claude Code はユーザーの依頼を受け取るたびに、すべてのスキル説明文を参照して「このスキルを呼び出すべきか」を判断している。このプロセスを スキルのマッチング と呼ぶ。

説明文がなければ、
Claude はそのスキルを
「いつ使うべきか」わからない。

スキルシステムの基本原理

たとえば document-skills:xlsx（Excelファイルを生成するスキル）の説明文が削除された場合、「Excelファイルを作って」と頼んでも Claude はそのスキルを思い出せず、代わりに汎用的な回答を返す可能性がある。

ただし、影響の大きさはスキルの使用頻度によって異なる。

日常的によく使うスキルは影響を受けにくい。しかし、「たまに使うが重要なスキル」 ほど被害が大きい。「久しぶりに使おうとしたら動かなかった」という状況が起きやすい。

自分の環境でこの問題が起きているかどうか、/doctor コマンド一発で確認できる。

1. Claude Code を起動する

   ターミナルで claude と入力してClaude Code を開く。

2. /doctor と入力して Enter

   診断コマンドが実行され、現在の状態が表示される。

3. 「Skills」セクションを探す

   次のような表示が出たら、あなたの環境でも問題が発生している。

Skill listing will be truncated
  N descriptions dropped
  (full descriptions kept for most-used skills)

Skill listing is within budget

また、現在の skillListingBudgetFraction の値は settings.json で確認できる。

{
  "skillListingBudgetFraction": 0.05,   // ← この値を確認
  ...
}

この行がなければ、デフォルトの 0.01（1%）が適用されている。

解決策は2つある。それぞれにトレードオフがあるので、状況に合わせて選ぼう。

方法 B（バジェットを増やす） の具体的な手順：

{
  // 変更前
  "skillListingBudgetFraction": 0.05,

  // 変更後（例：8%に引き上げ）
  "skillListingBudgetFraction": 0.08,
}

どちらを選ぶか迷ったら、まず 方法 A でスキルを整理 することを推奨する。インストールしたが使っていないスキルを削除するだけで、問題が解消されることが多い。

Discovered on 2026.05.07  ·  Claude Code v2.1.132  ·  Binary inspection of claude.exe