skillListingMaxDescCharsでskill説明の上限1,536文字を変える

skillListingMaxDescCharsとは

skillListingMaxDescCharsは、skillの説明文をClaudeに見せるときの文字数上限を決めるsettings.jsonのキーです。Claudeは毎ターン、使えるskillの一覧(skill listing)を受け取ります。一覧には各skillのdescriptionとwhen_to_useの本文が入り、このキーはskill1つあたりに見せる文字数を制限します。上限を超えた分は打ち切られます。

型は正の整数で、既定値は1536です。スコープは「Any file」なので、ユーザー設定・プロジェクト設定・ローカル設定のどれにも書けます。

{
  "skillListingMaxDescChars": 2048
}

この例は設定リファレンスに載っている値です。上げればコンテキストの消費が増え、下げれば減ります。

何が切られるのか — 数える対象は2つの合算

打ち切りの対象はdescription単体ではありません。descriptionとwhen_to_useをつなげた文章全体に1,536文字の上限がかかります。

• description: skillが何をするか、いつ使うか
• when_to_use: 呼び出しのきっかけになる言い回しや依頼の例。一覧ではdescriptionの後ろに足される

つまりwhen_to_useを長く書くほど、descriptionに残せる文字数は減ります。逆にdescriptionだけで1,536文字を使い切ると、when_to_useは一覧に出ません。

切られた後ろ側の文章は、Claudeには届きません。skill本体(SKILL.mdの本文)は呼び出されたときに読み込まれるので、動作そのものは変わりません。変わるのは、Claudeが「このskillを今使うべきか」を判断する材料です。後半に書いたトリガー語が一覧に出ず、自動では選ばれにくくなります。

上限が働く条件は予算と独立している

skillの一覧には、もう1つ別の制限があります。skillListingBudgetFractionによる一覧全体の予算で、コンテキストウィンドウの1%(既定値0.01)が上限です。skillが多くて予算を超えると、Claude Codeは全skillの名前を残したまま、使用頻度の低いskillから説明文を落とします。

2つの制限は働く場所が違います。

各エントリの説明文は、予算にかかわらず1,536文字で頭打ちになります。説明文が短ければ上限は関係ありません。長い説明文を書いたskillが多いときに、2つの制限が重なって効いてきます。

予算側の調整は、/skillsコマンドの使い方の記事で扱っています。

上げるか下げるかの判断軸

設定リファレンスの説明は2行です。長い説明文を保ちたいなら上げ、skillListingBudgetFractionの範囲に多くのskillを収めたいなら下げます。どちらを選ぶかは、手元のskillの状態で決まります。

ここで注意したいのは、上げても一覧全体の予算は増えないことです。skillListingMaxDescCharsを上げると、1つのskillが使う文字数が増えます。その分、予算を超えやすくなり、使用頻度の低いskillの説明文が落ちる可能性があります。長い説明文を保ちたいときは、skillListingBudgetFractionも一緒に確かめます。

設定と確認の手順

設定ファイルに追記します。プロジェクト全体で揃えたいならプロジェクトの.claude/settings.json、自分だけなら~/.claude/settings.jsonが置き場所の候補です。

{
  "skillListingMaxDescChars": 800,
  "skillListingBudgetFraction": 0.02
}

例は、1つあたりの説明文を短くしつつ、一覧全体の予算を2%に広げる組み合わせです。値は手元のskillの長さに合わせて決めます。

反映後は、一覧のコンテキスト消費を確かめます。

/doctor
/context

/doctorは一覧のコンテキスト消費の見積もりと、寄与の大きいskillを示します。/contextのSkills行は、予算を適用した後の一覧の大きさを表します。モデルが受け取るサイズと一致するのは、v2.1.196以降です。それ以前は全説明文の合計が出るため、設定した予算より何倍も大きく見えることがありました。

デバッグログには、一覧が予算を超えたときの警告が出ます。claude --debugで起動すると見られます。なお、説明文の切り詰めを知らせる起動時の警告は、v2.1.105で入りました。

手元のskillの説明文が何文字かを測る

上限を決める前に、いま何文字あるかを知っておくと判断しやすくなります。次のコマンドは、descriptionが1行で書かれているskillに限った目安です。

for f in ~/.claude/skills/*/SKILL.md; do
  n=$(grep -m1 '^description:' "$f" | wc -m)
  echo "$n $f"
done | sort -rn | head

先頭の数字が、description:の行全体の長さ(改行込み)です。複数行で書く形式やwhen_to_useは数えていません。目安として、上位に並ぶskillの説明文が1,000文字を超えているなら、上限の影響を受けやすい候補です。日本語の文字をどう数えるかは、設定リファレンスに記載がありません。上限に近いskillは、実際に/doctorで見える寄与を確認してください。

設定を変える前に説明文を直す

上限は、説明文が長すぎるときの安全装置です。上限を上げて長い説明文を通す前に、書き方を見直す価値があります。スキルページも、重要な用途を先頭に置くよう勧めています。

• 最初の1〜2文で、何をするskillかと、使う場面を言い切る
• トリガーになる語は前半に集める
• when_to_useには、descriptionと重複しない呼び出し例だけを書く
• 手順の詳細は本文に回す。説明文には書かない

本文は呼び出された後に読み込まれるので、説明文に手順まで入れる必要はありません。一覧に出る文章は、毎ターン、すべてのskillの分だけコンテキストを使います。短く具体的に書くほど、上限の設定値に悩まずに済みます。

使っていないskillがたくさんあるなら、上限を触る前に整理するほうが効きます。使用状況の見方はskill-doctorの使い方にまとめています。説明文を残しつつ消費を減らしたいskillには、skillOverridesの"name-only"で説明文なしの掲載にする方法もあります。

説明文の書き直し例

同じskillでも、書く順序で一覧に残る情報が変わります。次は、後半にトリガー語を書いてしまった例と、前半に寄せた例です(説明のための架空のskillです)。

# 前半が背景説明で埋まっている例
description: このskillはチームのリリース作業の歴史的経緯を踏まえて作られた...(長い背景説明)... リリースノートを作るとき、変更履歴をまとめるときに使う
 
# 用途とトリガー語を先頭に置いた例
description: リリースノートを作る。変更履歴の要約、バージョン見出しの付与、公開前の体裁チェックに使う。背景:...

後者なら、文章が途中で切られても、Claudeが判断に使う用途とトリガー語は一覧に残ります。上限を上げて長い前置きごと通すより、先頭に重要語を置くほうが、コンテキストの消費も増えません。

チームで共有するなら、値の変更はプロジェクトの設定ファイルに入れてコミットする運用が考えられます。ただし、上限を上げると全員のターンごとの消費が増えます。説明文の長いskillが数個あるだけなら、設定を足すよりSKILL.mdを直すほうが全員に効きます。

上限の経緯 — 250文字から1,536文字へ

この上限は昔から1,536文字だったわけではありません。changelogでは、次の2段階が確認できます。

250文字は、日本語で丁寧に用途を書くと数行で埋まる長さです。1,536文字に広がったことで、トリガー語や除外条件まで書けるようになりました。今回のキーは、その既定値を利用者の側で動かすための設定です。changelogの該当項目は上限値の変更だけを扱っていて、設定キーの追加には触れていません。

MCPのツール説明文にも、同じ発想の上限があります。そちらは環境変数で変える形で、MCPツール説明文の文字数上限の記事に書きました。skillは設定キー、MCPは環境変数という違いがあります。

よくあるつまずき

設定したのに説明文が変わらないときは、次の点を見てください。

• 説明文が元から上限より短い。上限は短い文章を伸ばさない
• 設定したのが別のスコープのファイル。より優先度の高い設定ファイルに別の値が書かれていると、そちらが使われる
• 一覧全体の予算で説明文が落ちている。この場合はskillListingBudgetFractionの問題で、このキーを上げても直らない
• skillListingMaxDescCharsを、ツールの出力上限や会話の長さの設定と取り違えている。このキーが決めるのはskill一覧の説明文だけ

最後の点について補足します。このキーは、Claudeが「どのskillを使うか」を選ぶための材料の大きさを決めるものです。skillを実行したときに読み込まれる本文の長さには関係しません。

まとめ

skillListingMaxDescCharsは、skill1つあたりの説明文の打ち切り位置を動かす設定です。既定の1,536文字で困っていないなら、触る必要はありません。切れて困るのは、後半に重要なトリガー語を書いたskillです。その場合も、まず前半に寄せる書き直しを試し、それでも長さが要るときに上げます。上げるなら、一覧全体の予算との釣り合いを/doctorで確かめてからにします。