はじめに 🩺
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万文字規模、これが毎ターン常駐する計算です。ここが「スキルのコンテキスト税」の正体です。
🩺 /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
✂️ スキルを軽くする5つの手段
診断で犯人が分かったら、次は削り方です。「消す」以外に4つの選択肢があります。
① 使っていないスキルは消す・止める
一番効きます。プラグイン由来なら /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文字）
診断してから削ると、こういう判断が数字で下せるようになります。「なんとなく重そう」で消すのとは精度が違います。
⚠️ ハマりどころと関連アップデート
スキル運用で踏みやすい地雷を、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万トークン を達成している。効果は桁違い
まずは手元で /skill-doctor を一発叩いて、自分のスキル在庫を数字で見るところから始めてみてください。
claude update
/skill-doctor