Claude Code の Skill description が削られる仕組みを調べてみた

リテールアプリ共創部の末永です。

Claude Code の Skill は便利ですが、Skill の description と name は AI に渡る情報なので、tool 定義と同じように context を食ってしまうのではないか疑問に思ったので調べてみました。

description の上限

Skill は SKILL.md というファイルに、次のように書きます。

---
name: my-skill
description: 何をする Skill か、いつ使うか
when_to_use: 発火条件の追加情報 (省略可)
---

(本文)

冒頭の --- で囲まれた部分がメタデータで、Claude にはここに書かれた name / description / when_to_use が渡されます。description と when_to_use は合算されて 1 つの説明文として扱われますが、1 skill あたりデフォルトで 1,536 文字の上限が存在します。これは maxSkillDescriptionChars を設定することで変更することができます。

また、全 Skill の合計に対しても上限があり、デフォルトではモデルの context window の 1% が設定されています。こちらも skillListingBudgetFraction を設定することで変更することができます。固定文字数で指定したい場合は、環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET も使えます。

これを超えた時の挙動としては、公式ドキュメント (Skill descriptions are cut short) に以下のように書かれています。

When it overflows, descriptions for the skills you invoke least are dropped first, so the skills you actually use keep their full text.

name のほうは残りますが description は消えるので、Claude はその Skill を「名前は知っているが何をするかは分からない」状態で扱うことになります。

200K context のモデルだと、デフォルト 1% で全体予算が 2,000 文字くらいです。Skill 1 個なら 1,536 字フルに載りますが、10 個入れたら 1 個あたり平均 200 字、50 個なら平均 40 字しか持てない計算になります。

なお /doctor を叩くと、予算をオーバーしているかと、どの Skill の description が落とされているかが分かります。Skill が増えてきたら、一度見てみるのも良いかもしれません。

不要な Skill を Claude に渡さない

description が自動で 省略(truncate) されるのを待つのではなく、自分で「この Skill は Claude に見せない」と明示する手段もあります。skillOverrides という設定で、Skill ごとに 4 段階で状態を切り替えられます。

/skills を実行すると Skill 一覧の UI が開くので、そこから Space で状態を循環させて Enter で確定すると .claude/settings.local.json に書き込まれます。直接設定ファイルに書く場合は次のような形になります。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

name-only は「Claude に存在は知らせるが description は渡さない」状態で、手動起動 (/name) でしか使わない Skill に向いています。user-invocable-only は逆に「Claude には完全に隠すが人間が / から呼ぶことはできる」状態、off は完全無効化です。こうすることで、普段使わない Skill のぶんは Claude に渡らなくなり、context を圧迫しなくなります。なお skillOverrides はプラグイン由来の Skill には効かないので、そちらは /plugin 側で管理することになります。

本当に切られるのか試してみる

ここまではドキュメントの話だったので、ここからは手元で maxSkillDescriptionChars と skillListingBudgetFraction を意図的に小さく振って、書いてある通りに動くか確かめてみます。

検証用に、適当なダミー Skill を 5 つ用意しました。description と when_to_use の合算が 70〜140 字くらいでバラけるようにしてあります。

sandbox/.claude/skills/
├── greet-user/SKILL.md       # description + when_to_use ~137字
├── format-date/SKILL.md      # ~132字
├── convert-units/SKILL.md    # ~110字
├── summarize-text/SKILL.md   # ~109字
└── generate-uuid/SKILL.md    # ~69字

中身は実処理なしのダミーで、SKILL.md 冒頭の --- で囲まれたメタデータ部分の description / when_to_use だけ意味があるようにしてあります。

1 skill あたりの上限を絞ってみる

まず maxSkillDescriptionChars: 80 だけ書いた状態で、Claude に「いま system prompt に見えている description を一字一句そのまま貼ってください」と頼んでみました。generate-uuid (合算 ~69字) 以外の 4 つは合算 80 字を超えているので、効いていれば 80 字で切れた状態で返ってくるはずです。

結果はこちらでした。

- format-date: 日付を ISO 8601 や日本語表記など複数のフォーマットに整形する。「日付を整形して」「YYYY-MM-DD にして」「和暦に変換」のようなリクエストで発火する想定。検証用ダミー。 - 日付文字列が含まれていて、かつフォーマット変換の意図が明示されているとき。
- greet-user: ユーザーに挨拶を返す。朝・昼・夜で文面を変える。「挨拶して」「こんにちは」「hello」などの軽い挨拶リクエストで発火する想定。検証用のダミー Skill なので実際の処理はしない。 - ユーザーが挨拶っぽい一言を投げてきたとき。技術的な質問とセットで来た場合は発火しない。
- summarize-text: 長文を 3 行に要約する。「要約して」「サマリー」「短くまとめて」などのリクエストで発火する想定。検証用ダミーなので実際には要約処理はしない。 - 入力に長めの文章があり、要約・サマリー化が明示的に求められているとき。
- convert-units: 単位変換を行う。長さ・重さ・温度・通貨など。「メートルをフィートに」「摂氏を華氏に」のような明示的な変換指示で発火する。検証用ダミーなので実数値は適当。 - 入力に数値と単位が含まれ、別単位への変換が要求されているとき。
- generate-uuid: UUID v4 を生成する。「UUID 出して」「ID 作って」で発火。検証用ダミー。 - 一意な識別子を生成してほしいと明示されたとき。

全 Skill の description が元の長さ (70〜140字) のまま出力されており、80 字で切られた様子は見られません。maxSkillDescriptionChars がプロジェクトレベルの settings.json から読まれていないのか、別の理由で効いていないのかは判断がつきませんでした。CLI 側から system prompt の中身を直接覗く手段もないため、今回はここまでしか追えていません。

全体予算を絞ってみる

今度は skillListingBudgetFraction: 0.0005 で起動します。200K context モデルだと全体予算は約 100 文字なので、5 つの Skill だけでもまったく収まらない計算です。

/doctor の出力はこちらです。

Skill listing will be truncated
  8 descriptions dropped (full descriptions kept for most-used skills) (0.1%/0.1% of context): greet-user, format-date,
 convert-units, +5 more
    run /skills to disable some, or raise skillListingBudgetFraction (currently 0.1%) in settings.json
  Opting in would cost ~1k tokens for skills every session and uses rate limits faster

description が消えて name だけ残ったのは、自作 5 個 (format-date / greet-user / summarize-text / convert-units / generate-uuid) と、バンドル Skill 3 個 (init / review / security-review) の合計 8 個でした。description が残ったのは、残りのバンドル Skill (update-config, keybindings-help, simplify, fewer-permission-prompts, loop, schedule, claude-api) です。なお、落ちた init / review / security-review の 3 つは、公式ドキュメント (Restrict Claude's skill access) に

A few built-in commands are also available through the Skill tool, including /init, /review, and /security-review
と書かれている通り、本来は built-in command で、それを Skill tool 経由でも呼べるようにしたものです。description が残った他のバンドル Skill とは出自が違うので、そのあたりが drop の挙動に関係しているのかもしれません。

ドキュメントの "descriptions are dropped first" の記述通り、description は途中で省略されるのではなく丸ごと削除されていました。name は全 Skill で残っているので、Claude は「greet-user という Skill がいるのは知っているが何をするかは分からない」状態になります。また、削られた中に自作 Skill 5 個すべてが含まれていたのは、一度も呼んでいないため最低優先扱いになるというドキュメントの記述に沿った挙動です。

なお、設定値は 0.0005 (= 0.05%) ですが、表示上は 0.1% になっていました。下限フロアがあるのか、表示の丸めが働いたのでしょうか🧐

最後に

Skill の情報はキャッシュされるので、料金的には大差ありません。とはいえ個人的には context に絶対に使わない内容を入れたくないので、必要ない Skill は user-invocable-only で呼び出すようにしています。

では👋