はじめに 🩺
Claude Code の Skills（スキル）は、便利だからといって増やし続けると 確実にコンテキストを食います。しかも厄介なことに、その代償は「使ったスキル」ではなく 「置いてあるだけのスキル」 にも発生します。
- スキルを 30 個入れたら、なんとなく応答が遅くなった気がする
- スキルを作ったのに、なぜか Claude が拾ってくれない
-
/contextを見ると何かが膨らんでいるが、犯人が特定できない
これらは全部、スキルの「listing（一覧）」がコンテキストを占有していることと関係しています。
そして v2.1.261 で、この状況を数字で殴れるコマンドが追加されました。
/skill-doctor
どのスキルが使われていないか、そして 各スキルがコンテキストをどれだけ食っているか を出してくれます。本記事では、この /skill-doctor を軸に、スキルを「増やす」のではなく「削る・軽くする」ための実践手順をまとめます。
日本語圏には「スキルの作り方」の記事は充実していますが、「増やしすぎた後の運用」 の情報はほとんどありません。ここを埋めるのが本記事の目的です。
3行まとめ 📝
- スキルは name + description の一覧（listing）が常時コンテキストに載る。本文は呼ばれたときだけロードされ、以降ターンをまたいで残り続ける 🧾
- listing には モデルのコンテキストウィンドウの約1% という予算があり、超えると 使用頻度の低いスキルから description が削られる（＝トリガーされなくなる）📏
-
/skill-doctor（v2.1.261） で未使用スキルとコスト内訳を出し、disable-model-invocation/references/分割 /context: fork/pathsの4手で削る ✂️
🧾 前提：スキルは「どこまで」コンテキストに載るのか
まず、コストの発生地点を正確に押さえます。Claude Code のスキルは Progressive Disclosure（段階的開示） で読み込まれます。
| 段階 | 読み込まれるもの | タイミング | コスト |
|---|---|---|---|
| ① listing |
name と description（＋when_to_use） |
セッション中ずっと常駐 | 全スキル分が常時 |
| ② SKILL.md 本文 | スキル本体の指示 | 呼び出されたとき | 呼ばれた分だけ |
③ references/ 等 |
参照ドキュメント | 本文から読みに行ったとき | 読んだ分だけ |
ここで重要なのが以下の2点です。
- ①は「使っていないスキル」でも必ず課金される（Claude が「何が使えるか」を知るために必要なため）
- ②は一度ロードされるとその後のターンにも残り続ける
Invoking a skill loads its rendered content into the conversation as a single message and stays there across later turns.
（スキルを呼び出すと、その内容は1つのメッセージとして会話にロードされ、以降のターンにも残り続けます）
つまり、「巨大な SKILL.md を1回呼んだ」だけでセッションの最後までコンテキストを占有し続けるわけです。これが体感速度とコストに効いてきます。
なお、以前は同じスキルを再度呼ぶと指示が二重にコンテキストへ積まれる不具合がありましたが、これは v2.1.202 で修正済みです。
📏 listing には「予算」がある
スキルを増やしたときに真っ先に効いてくるのが listing の予算です。
- listing の文字数予算は モデルのコンテキストウィンドウの 1% を基準にスケールする
- 1スキルあたりの
description+when_to_useは 1,536文字で打ち切り - 予算を超えると、呼び出し回数の少ないスキルから description が落とされる
3つ目が重要です。「スキルを作ったのに Claude が拾ってくれない」現象の正体はこれであることが少なくありません。description が落ちれば、Claude はそのスキルが何をするものか分からないので、当然トリガーできません。
予算は設定で調整できます。
{
"skillListingBudgetFraction": 0.02,
"skillListingMaxDescChars": 1536
}
| 設定 | 意味 | デフォルト |
|---|---|---|
skillListingBudgetFraction |
listing に使うコンテキストの割合 | 0.01（1%） |
skillListingMaxDescChars |
1スキルの description 上限文字数 | 1536 |
ただし、予算を広げるのは根本解決ではありません（その分だけ会話に使える領域が減ります）。まずは実測して、削れるものを削るのが先です。
自分のスキルの listing コストを数える
listing は結局のところ「name: description」の羅列なので、手元でも概算できます。
for f in .claude/skills/*/SKILL.md ~/.claude/skills/*/SKILL.md; do
[ -f "$f" ] || continue
python3 -c "
import re,sys
s=open(sys.argv[1],encoding='utf-8').read()
m=re.match(r'^---\n(.*?)\n---\n', s, re.S)
fm=m.group(1)
name=re.search(r'^name:\s*(.+)$', fm, re.M).group(1)
desc=re.search(r'^description:\s*(.+)$', fm, re.M).group(1)
print(f'{len(name)+len(desc)+2:>5}文字 {name}')
" "$f"
done
筆者のスキル用リポジトリ（スキル2個）で実行した結果がこちらです。
75文字 qiita-claude-code-release-notes
23文字 qiita
2個なら 98 文字で誤差ですが、description を丁寧に書いた実用スキルは1つ 300〜1,500文字になります。30個入れれば1万文字規模、これが毎ターン常駐する計算です。ここが「スキルのコンテキスト税」の正体です。
予算超過時、どのスキルの description が落ちるのか
「呼び出し回数の少ないものから」の中身をもう少し正確に書きます。実装を追うと、優先順位は次のルールで決まっています（v2.1.270 時点）。
- バンドルスキル（公式同梱）は truncation の対象外。名前だけで並ぶ設定のスキルも対象外で、これらは満額で予算を先に確保する
- 残りの予算を、スキルごとの優先度スコアが高い順に配分する
- スコア ＝
呼び出し回数 × 時間減衰（減衰は 半減期7日、下限は 0.1 倍） - 一度も呼ばれていないスキルのスコアは 0（最下位グループ）
- スコア ＝
- 配分は貪欲法。ある description が残り予算に入らなくてもそこで打ち切らず、後続のより短い description は入る
- 入らなかったスキルは listing 上で
- スキル名だけの行になる（description が丸ごと消える）
ここから実践的に効いてくるのは2点です。「長い description ほど落ちやすい」（ルール3。description短縮が効く理由）と、「落ちるのは自分のスキルだけ」（ルール1。公式バンドル分を減らしたいなら後述の disableBundledSkills）。
なお、予算超過は黙って起きるわけではありません。デバッグログに次の警告が出ます。
Skill listing over budget: <N> skills, <X> chars > <Y> budget — descriptions will be truncated.
Run /skills to disable some, or raise skillListingBudgetFraction in settings.
⚠️ 新規スキルは構造的に「落とされる側」— 足す順番の話
このルールには、新しく足したスキルにとって不利な副作用があります（コメントで @Skillselion さんにご指摘いただいた点です）。
- 足したばかりのスキルは当然呼び出し回数ゼロ ＝ スコア 0 の最下位グループ
- 予算が溢れている状態だと description が落とされる → モデルからトリガーされない
- トリガーされないので呼び出し回数はゼロのまま → スコアも上がらない
つまり「予算が溢れた環境に新規スキルを足す」と、そのスキルだけが自然には抜けにくいループに入ります。ただし細かい点として、未使用スキルは全員スコア 0 で同着なので「新しいものが優先的に落とされる」わけではなく、実際の勝敗は listing 上の並び順と description の長さで決まります。新規スキルほど description を短く保つのが効くのはここです。
抜け道は2つあります。
① 足す前に棚卸しする（順番を逆にする）
既存の未使用スキルを disable-model-invocation で listing から降ろしてから、新規スキルを足す。「新しく作ったスキルが拾われない」ときの切り分けも、自分の description の書き方を疑う前に listing 全体の総量を疑うのが先です。
② 手動で数回叩いて「実績」を作る
使用実績は、モデルが Skill ツールで呼んだときだけでなく、ユーザーが /スキル名 と打ったときにも記録されます。詰まったら自分で数回起動すればスコアが 0 から抜け、同着の未使用スキル群より優先されるようになります。ループは構造としては実在しますが、完全な閉路ではないというのが実装上の答えです。
診断が後追いになっても問題ありません。上の予算超過警告や /skill-doctor / /doctor で「いま description が何個落ちているか」は見えるので、足した後に気づいた場合でも状況は特定できます。
🩺 /skill-doctor で診断する（v2.1.261）
手計算はここまでにして、公式の診断コマンドを使います。
/skill-doctor
表示される内容は次のとおりです。
- 各スキルのコンテキストコスト（どれだけ食っているか）
- 各スキルの使用頻度（どれだけ呼ばれているか）
- 一度も呼ばれていないスキルのフラグ
- 最近使っていないプラグインの一覧
つまり 「コストが高い × 使っていない」 の象限にあるスキルが、削除の第一候補としてそのまま出てきます。
| コマンド | 分かること |
|---|---|
/skill-doctor |
スキル単位のコストと使用状況、未使用スキルの洗い出し |
/doctor |
listing 全体のコンテキストコスト見積もりと、その主な要因 |
/usage |
skills / subagents / plugins / MCP サーバー別の使用量内訳 |
/context |
現在のコンテキスト内訳全体 |
/plugin の Stats タブでも同じレポートを対話的に確認できます。非対話（-p）セッションではテキストで出力されるため、CI に組み込んで定期的にレポートさせることも可能です。
claude -p "/skill-doctor" > skill-report.txt
✂️ スキルを軽くする6つの手段
診断で犯人が分かったら、次は削り方です。「消す」以外に5つの選択肢があります。
① 使っていないスキルは消す・止める
一番効きます。プラグイン由来なら /plugin から無効化、バンドルスキルごと止めるなら設定で一括です。
{
"disableBundledSkills": true
}
export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1
バンドルスキル・ワークフロー・組み込みスラッシュコマンドがモデルから見えなくなります（v2.1.169 で追加）。切り分け目的なら、全カスタマイズを無効化して起動する --safe-mode も使えます。
claude --safe-mode
組織で配布している場合は、マネージド設定の skillOverrides や Skill(name) の deny ルールでコントロールします。ネストした .claude/skills のスキルは <dir>:name という名前で並ぶため、deny ルールもこの形式で書く必要がある点に注意してください（v2.1.260 で修正済み）。
② listing から降ろす — disable-model-invocation
「自分では使うが、Claude に自動で選ばせる必要はない」スキルに有効です。
---
name: release-notes
description: リリースノート記事を作成する
disable-model-invocation: true
---
- Claude の自動起動対象から外れる → listing に載らなくなる
- 自分で
/release-notesと打てば従来どおり使える
「週1で手動起動するだけのスキル」は、ほぼ全部これで良いはずです。逆に user-invocable: false にすると、ユーザーからは呼べず Claude だけが呼べるスキルになります。
③ description を削る（ただし先頭は死守）
description は listing に常駐する唯一のテキストなので、1文字が最も高い場所です。
# ❌ 冗長：使用例やNG例まで description に詰め込む
description: このスキルはQiitaに投稿する記事を作成するためのスキルです。ユーザーが「記事を書いて」「Qiitaにまとめて」などと言った場合に使用します。なお、技術記事以外には使用しないでください。出力は必ず日本語で…
# ⭕️ 簡潔：キーユースケースを先頭に、詳細は本文へ
description: Qiita投稿用の技術記事を作成する。「記事を書いて」「Qiitaにまとめて」で起動。
キーユースケースを先頭に置くのが鉄則です。1,536文字で打ち切られるため、後ろに書いたトリガー語は消える可能性があります。
④ 本文を references/ に逃がす
SKILL.md 本文は呼び出し時に丸ごとロードされます。長い手順書やAPIリファレンスは、別ファイルに切り出して必要になったときだけ読ませるのが定石です。
.claude/skills/qiita/
├── SKILL.md # 手順の骨子だけ（軽く保つ）
└── references/
├── markdown-guide.md # Qiita記法の詳細
└── templates.md # 記事テンプレート集
## 実行手順
1. 記事構成を決める
2. Qiita 独自記法が必要になったら `references/markdown-guide.md` を読む
3. テンプレートを使う場合は `references/templates.md` を読む
効果は公式スキル自身が証明しています。
- バンドルの
claude-apiスキル：参照ドキュメントをオンデマンド化して 約20万トークン → 約2.5万トークン（v2.1.234） - Workflow ツール：説明文を
workflow-authoringスキルに移して 5.7k トークン → 約1k トークン（v2.1.248）
1桁違うレベルで効きます。 長い SKILL.md を持っている人は、ここが最優先です。
⑤ サブエージェントに逃がす — context: fork
「調査系スキル」のように 大量のファイルを読むがメイン会話には結論だけ欲しい ものは、フォークして別コンテキストで走らせます。
---
name: deep-research
description: リポジトリ内を横断調査して結論だけ返す
context: fork
agent: Explore
background: false
---
$ARGUMENTS について調査し、結論のみを要約して報告してください。
| フィールド | 意味 |
|---|---|
context: fork |
会話履歴を持たない独立したサブエージェントとして実行 |
agent |
使用するサブエージェント種別（Explore / Plan / general-purpose / 自作） |
background |
true（デフォルト）でバックグラウンド実行。false でその場で結果を待つ |
読んだ内容はサブエージェント側に積まれるため、メイン会話のコンテキストは消費されません。 なお context: fork のスキルは v2.1.218 以降 デフォルトでバックグラウンド実行になっています。-p の非対話モードや CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 の場合はフォアグラウンド実行に切り替わります。
⑥ paths で発火条件を絞る
特定のディレクトリ・ファイル種別でのみ意味を持つスキルは、glob で発火条件を限定できます。
---
name: rails-migration
description: Railsのマイグレーションを安全に作成する
paths:
- "db/migrate/**"
- "app/models/**"
---
🧪 実際に自分のスキルを診断してみた
筆者の qiita-claude-skills リポジトリで実測した数値です。
| スキル | SKILL.md 全体 | 本文 | listing 行 |
|---|---|---|---|
qiita |
1,602文字 | 1,486文字 | 23文字 |
qiita-claude-code-release-notes |
3,406文字 | 3,238文字 | 75文字 |
読み取れることは2つあります。
- listing コストは合計98文字しかない。この規模ならスキルを増やしても listing 予算は問題にならない
-
一方で
qiita-claude-code-release-notesは本文が 3,238文字あり、これは1回呼んだらセッション終了まで残り続ける
つまり筆者のケースで削るべきは listing ではなく 本文です。このスキルは「カテゴリ絵文字の一覧」「カテゴリの並び順」「分類方針」といった参照テーブルが本文の半分以上を占めているので、④の references/ 分割がそのまま効きます。
.claude/skills/qiita-claude-code-release-notes/
├── SKILL.md # 実行手順のみ（約1,500文字）
└── references/
└── categories.md # 絵文字・並び順・分類方針（約1,700文字）
診断してから削ると、こういう判断が数字で下せるようになります。「なんとなく重そう」で消すのとは精度が違います。
🫥 自分が置いていないスキルも予算を食う（ネスト .claude/skills）
listing の予算は、セッションにロードされている全スキルの共有です。自分で書いたスキルだけでなく、ネストした .claude/skills のスキルも同じ予算を食います。つまり vendor 配下にスキル同梱のリポジトリを1つ引き込んだだけで、自分では何も足していないのに listing が膨らむという状況が起こり得ます（これもコメントでの指摘です）。
ロードのタイミングには条件があるので、正確に押さえておくと切り分けが楽になります。
| 置き場所 | ロードのタイミング |
|---|---|
起動ディレクトリと、その親（リポジトリルートまで）の .claude/skills
|
セッション開始時に必ずロード |
起動ディレクトリより下の .claude/skills（例: vendor/foo/.claude/skills） |
Claude がそのディレクトリ配下のファイルを最初に読み書きしたときにロードされ、以降そのセッション中は残り続ける |
「置いてあるだけ」では膨らまないが、そのディレクトリを1回触った瞬間に膨らんで、セッション終了まで戻らないという挙動です。調査で vendor/ のファイルを1つ覗いた、くらいで踏みます。
さらにネストスキルは listing 上の表記もわずかに重くなります。
- description の末尾に
(from <dir>/.claude/skills — applies when working on files under <dir>/)という注記が自動で付く（＝その分だけ文字数が増える） - 同名スキルがある場合は
<dir>:<name>として両方並ぶ（v2.1.178）
/skill-doctor の出力に置いた覚えのない名前が並んでいたら、まずネストした .claude/skills を疑うのが早いです。
⚠️ ハマりどころと関連アップデート
スキル運用で踏みやすい地雷を、CHANGELOG から拾ってまとめます。
| 症状 | 原因・対処 | 関連バージョン |
|---|---|---|
| スキルを編集したのに反映されない |
/reload-skills で再スキャン。SessionStart フックから reloadSkills: true を返せば同一セッションで反映 |
v2.1.152 |
スキルが / メニューに出てこない |
セッション中に追加したスキルが出ない不具合は修正済み。BOM 付き .md が無視される不具合も修正済み |
v2.1.216 / v2.1.239 |
| 同名スキルがどちらか消える | ネストした .claude/skills のスキルは <dir>:<name> として両方残る |
v2.1.178 |
| deny ルールが効かない | ネストスキルには Skill(<dir>:name) 形式で指定 |
v2.1.260 |
| スキルを複数まとめて起動したい |
/skill-a /skill-b やって で先頭から最大5個までロードされる |
v2.1.199 |
frontmatter の model: が無視される |
対話セッションで無視される不具合は修正済み。auto mode が非対応モデルを指定された場合はセッションのモデルを維持 | v2.1.259 |
| スキルにツールを使わせたくない | frontmatter の disallowed-tools でスキル有効中だけツールを外せる |
v2.1.152 |
💡 運用フロー
最後に、実際の運用に落とすとこうなります。
# 1. 週に1回、診断する
/skill-doctor
# 2. 「未使用 × 高コスト」を消す or disable-model-invocation を付ける
# 3. 残すスキルのうち本文が長いものは references/ に分割
# 4. listing 全体の見積もりを確認
/doctor
# 5. 使用量の内訳で効果を確認
/usage
ポイントは 「スキルは資産ではなく在庫」 と捉えることです。持っているだけでコストが発生するので、棚卸しの仕組みを作らないと必ず太ります。
まとめ ✅
- スキルの listing（name + description）は常時コンテキストに常駐する。使っていないスキルにもコストがかかる
- listing 予算（コンテキストの約1%）を超えると 使用頻度の低いスキルから description が落ち、トリガーされなくなる
-
/skill-doctor（v2.1.261） で「未使用 × 高コスト」のスキルを特定できる - 削り方は 消す /
disable-model-invocation/ description短縮 /references/分割 /context: fork/pathsの6手 - 公式スキル自身が
references/分割で 20万トークン → 2.5万トークン を達成している。効果は桁違い - 予算超過時に落ちるのは バンドル以外＝自分のスキル。優先度は
呼び出し回数 × 時間減衰（未使用は 0）なので、新規スキルは構造的に不利。足す前に棚卸しし、詰まったら手動で/スキル名を数回叩いて実績を作る - listing 予算は ネストした
.claude/skillsも含めた共有。vendor 配下のファイルを1回触るとそこでロードされ、セッション中ずっと残る
まずは手元で /skill-doctor を一発叩いて、自分のスキル在庫を数字で見るところから始めてみてください。
claude update
/skill-doctor