Claude Code:「Skill listing will be truncated」の正体と直し方

「Skill listing will be truncated」という赤文字が出た（起動時の警告）

ある日 Claude Code を立ち上げたら、見慣れない赤文字が出ていた。

Skill listing will be truncated

何これ。Skill、壊れた？

3 ヶ月ぶりのブログ復帰、龍ちゃんです。この 3 ヶ月で .claude/ に Skill だの Command だのを作りまくっていたら、起動時にこの赤文字が出るようになっていました。color: warning の黄色〜赤系で出るやつですね。最初は「設定をミスったか」と思ったんですが、調べてみたら仕様どおりの正常な警告でした。

というのも、僕は「Skill は作ったらとりあえず .claude/skills/ にぶっこむ」というスタンスでやってきたんですよね。で、気がつけばかなりの数になっていました。この進め方自体、最初の一歩としては結構よかったと思っています。ただ、その数が積み上がってきたところに、ダメ押しみたいにこの赤文字が出た、というわけです。

結論から言うと、これは character budget という仕組みからの SOS で、対処は「Skill を削除する」ことでも「budget を引き上げる」ことでもなく、description を “削減” することでした。順番に話します。

今回の内容です。

• この赤文字（Skill listing will be truncated）の正体は何か
• 実は警告は 2 種類あって、意味がまったく違うという話
• budget を上げる対症療法ではなく、”削減” で対処する 2 つの手段

赤文字の正体は character budget の超過だった

調べた結論を先に言うと、この赤文字は character budget（Skill 一覧の文字数予算）を超えたときに出ます。公式ドキュメント（Extend Claude with skills – Claude Code Docs）に明記されている仕様です。

budget の計算式と「1,536 文字の壁」（公式仕様）

Skill の description は、Claude が「どの Skill が使えるか」を知るためにコンテキストへ読み込まれます。その総量に予算（budget）があって、こう決まっています。

character budget = コンテキストウィンドウ × 1%

The budget scales at 1% of the model’s context window.

ちなみに以前のバージョンには「8,000 文字の下限」もあったんですが、現行の公式 Docs ではこの記述が消えて 1% のみになっています。最近のモデルなら 1% でだいたい 1.5 万文字ぶんくらいなので、実質この 1% が効いてくる感じですね。

そして、個別の Skill ごとにも上限があります。description と when_to_use の合計が 1,536 文字で打ち切られます。

the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage.

予算を超えるとどうなるか。description が短縮されます。ただし name（Skill 名）だけは常に残ります。

All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget.

つまり、自分は Skill を覚えているのに、Claude 側は description のキーワードを失っているわけですね。

Skill 警告は 2 種類：「shortened」と「truncated」の違い

これ、調べてみたら Claude Code の警告って 2 種類あって、意味がまったく違うんですよ。（Claude Codeのバイナリ探索談！）

実際に、僕の環境で動いている Claude Code（v2.1.162）の本体バイナリを Claude 自身に探索してもらったら、警告文を出し分けているこんなコードが見つかりました。

let v = K ? "Skill listing will be truncated"
          : "Some skill descriptions will be shortened";
// color:"warning" で描画、"N/M chars" の予算表示を伴う

整理するとこうです。

僕が見たのは後者の truncated の方でした。予算全体が足りなくなって、低頻度の Skill の description がごっそり落ちる——要は Skill が一覧から実質見えなくなるやつですね。前者（shortened）はもっと軽くて、個別の description が長すぎて切り詰められるだけなので、Skill 自体は一覧に残ります。同じ赤文字でも深刻度がぜんぜん違うんですよね。

放置すると「呼びたい Skill が来ない・別のが誤発火する」

で、truncated で description が落ちると、何が起きるのか。ここからは調べた挙動から考えられる「起こりうる症状」の話です。

Claude は description のキーワードを手がかりに「どの Skill を使うか」を判断しているので、それが欠けると次のようなことが起きる可能性があります。

• 呼びたい Skill が反応しない：キーワードが落ちて、Claude がマッチできない
• 別の Skill が誤発火する：description が残っている別の Skill が拾われる

「最近 Skill の挙動が安定しないな」という人は、一度 /doctor を叩いてみてください。budget がどれくらい溢れているか、どの Skill が影響を受けているかが見えます。

どの Skill から落ちるかは公式 Docs に明記があって、budget を超えると 使用頻度の低い Skill の description から先に落ちる仕様です（”descriptions for the skills you invoke least are dropped first”）。よく使う Skill はフルで残るので、name だけになって description が消えるのは普段あまり呼んでいない Skill の方なんですよね。

budget 引き上げは最終手段、まず description を “削減” する

で、どう対処したかなんですが。

まず、すぐ思いつくのは budget を引き上げる方法です。skillListingBudgetFraction（settings.json、例 0.02 = 2%）や環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で予算枠を広げられます。

ただ、これは最終手段かなと思っています。budget を広げても Skill が増え続ければまた頭打ちになるし、枠を広げた分だけコンテキストも食いますからね。予算に手を入れる前に、まず見直すべきは Skill 側の “使われ方”。そこを整理して description を「削減」する、というのが本筋なんですよね。

今回紹介するのは、その Skill 側に手を入れる削減です。やり方は 2 つあって、description を budget から 外す か、縮める か。順に見ていきます。

前提：Skill と Slash Command はもう同じ仕組み

1 つだけ前提を。かつて「発火しないなら Slash Commands に移す」としていた頃は、Skill と Slash Command は別の仕組みでした。でも今は 両方が同じ Skill システム上で動作するよう統合されました。公式 Docs にも “Custom commands have been merged into skills.”（カスタムコマンドは Skill に統合された）と明記されていて、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも同じ /deploy として同じように動く、と書かれています。自動発火するかどうかといった挙動は frontmatter で決まります。だから「ファイルを別ディレクトリに移す」必要はなく、frontmatter をいじるだけで済みます。これが次の話の土台です。

削減①：disable-model-invocation で budget から「外す」

1 つめは、そもそも description を予算に乗せない方法。frontmatter に 1 行足すだけです。

---
name: my-skill
description: 何をする Skill か
disable-model-invocation: true   # ← この 1 行
---

公式に記載されている効果はこうです。

Description not in context, full skill loads when you invoke.

これで何が起きるかというと、

• description が character budget から完全に除外される（＝最大の削減）
• Claude の自動発火が止まる（誤発火事故の防止）
• /skill-name での手動呼び出しは可能（/ メニューに残る）
• 本文は呼び出し時のみロード（コンテキスト効率は維持）

ディレクトリ移動なし、ファイル削除なし。frontmatter 1 行で「自動発火しない・手動でだけ呼べる」状態になります。これが “実質 Commands 化” です。

対象は、人間が発火タイミングを完全に制御したい Skill。副作用がある（commit / deploy / 送信）、特定の作業でしか使わない、手癖で /foo を打っている——こういう Skill に description は要りません。

削減②：薄い description で「縮める」

2 つめは、自動発火に価値がある Skill 向け。これは消さずに残しますが、description を 1,536 文字フルに使う必要はない。

ここで 1 つ注意。さっき「キーワードが落ちると Claude がマッチできない」と言ったので、「薄くしたら発火しなくなるのでは？」と不安になるかもしれません。でも削るのは “この Skill が何をするか” という機能説明のほうで、”どんなときに呼んでほしいか” というトリガーキーワードはむしろ残す。ここを取り違えなければ、薄くしてもちゃんと発火します。

実は公式 Docs も、description は「何をする＋いつ使うか」を簡潔に、しかも “Put the key use case first”（主要ユースケースを先頭に） が推奨なんですよね。公式が載せている例自体「〇〇する。Use when 〜（こういうときに使う）」の 1〜2 文です。だから機能を網羅的に説明するより、「どういうときに発火してほしいか」——ユーザーが自然に打つトリガーキーワードを軸に短く書くのが、むしろ公式どおりなんです。（この辺んは使いながら調整です！）

実例。僕は自社サイト（SIOS Tech Lab）のブログ記事を Markdown で保存する CLI ツールを Skill 化しているんですが、これのトリガーは実質「特定の URL」なんですよね。tech-lab.sios.jp の URL が流れてきて、「ブログ」「取得して」が添えられたら発火してほしい。それ以外は要らないんですよね。だから description はこう削れます。

# Before（公式の型には沿ってる。でも説明が多くて長め）
description: |
  SIOS Tech Lab のブログ記事を Markdown に変換して保存する CLI ツール。
  記事の URL を渡すと取得・整形して docs/data/blog/ に書き出す。
  記事を手元に取り込みたいときや、バックアップを取りたいときに使う。

# After（トリガーだけ: 「いつ発火したいか」を書く）
description: ブログをMD保存。tech-lab.sios.jp の URL +「ブログ」「取得して」で発火

長文が 1 行になりました。それでもちゃんと発火します。慣れている Skill ほど description は薄くしていいというのが僕の結論です。用途を自分が把握しているなら、Claude にもキーワードだけ伝われば十分なんですよね。

外す・縮めるの使い分けと、削除前の「降格」

判断軸：「自動発火に価値があるか」の 1 問

①外すか②縮めるかは、1 問で決まります。「自動発火に価値があるか？」。

たとえば「リサーチして」「スライド作って」みたいな自然な言葉で自動発火してほしい Skill は、消さずに残して description だけ薄くしました。さっきのブログ取得ツールみたいに、URL がトリガーになるものも同じく薄くしたグループですね。

削除の前に「降格」で様子見する

最後に安全運用のコツを。「もう要らないかも」となっても、いきなり削除しないでください。skillOverrides: "off"（settings.json）で無効化して様子見してから消すと事故りません。settings.json の編集だけで戻せるので、降格 → 戻す → 再降格がやりやすい。

skillOverrides は手書きしなくても、/skills メニューで対象 Skill を選んで Space で状態をトグル → Enter で .claude/settings.local.json に保存できます（v2.1.129 以降）。

まとめ：赤文字は budget の SOS、答えは「削除」じゃなく「削減」

今回の流れを振り返ると、

• ある日出た Skill listing will be truncated の正体は character budget（コンテキスト × 1% / 個別 1,536 文字）
• 警告は 2 種類あり、shortened（個別 cap 超過＝短縮）と truncated（予算超過＝まるごと消える）は意味が違う
• budget を上げるのは最終手段。先にやるべきは Skill 側の “削減” で、description を budget から 外す（disable-model-invocation）か、縮める（薄い description）か

棚卸しはシンプルで、/skills で一覧を出して、各 Skill を「自動発火に価値があるか？」で 外す / 縮める / そのまま に振り分ける。これを月 1 で回すだけ。慣れてきた Skill から順番に削っていけばいい。

以前は「発火しないなら Slash Commands に移す」しかありませんでしたが、今は frontmatter を 1 行いじるだけで済みます。Claude Code のアップデートで、character budget という構造的な問題にもこのやり方で対処できるようになりました。

赤文字が出たら、それは budget の SOS です。Skill を消すんじゃなく、description を削減する。答えは “削除” じゃなく “削減” でした。

ほなまた〜