Claude Code スキルのコンテキスト消費にまつわる議論を整理する

こんにちは、クロスイノベーション本部リーディングエッジテクノロジーセンターの小澤です。
「Claude Codeのスキルを多数運用しているとコンテキストを圧迫する」といった意見がGitHub Issuesやブログに複数あり、独自のワークアラウンドも生まれているようです。
本ブログでは、スキルの読み込みの仕様を整理し関連する議論を概観したうえで、執筆時の最新バージョンでのコンテキスト消費を計測します。

検証バージョン
Claude Codeのスキル読み込みの仕様
関連する議論
計測
- 第1段階（起動時）：分割による変化なし
- 第2段階（呼び出し時）：分割版のほうがコストが高い
まとめ
参考リンク

検証バージョン

Claude Code v2.1.50（2026年2月23日時点の最新） / Claude Opus 4.6

Claude Codeのスキル読み込みの仕様

Claude Codeのスキル読み込みはProgressive Disclosureという段階的に読み込む仕組みで設計されています。
これはClaude Code固有の仕様ではなく、Anthropicが公開したAgent Skillsオープンスタンダードに基づくもので、Codex、Cursor、Gemini CLI、GitHub Copilot、opencodeなど、多くのプラットフォームが採用しています。

段階	タイミング	読み込まれる内容
第1段階	起動時	YAMLフロントマター（`name` と `description`）のみをシステムプロンプトに読み込む
第2段階	スキル呼び出し時	SKILL.md本文をコンテキストに注入する
第3段階	必要に応じて	スキルディレクトリ内の追加ファイルをReadツール等で読み込む

公式ドキュメントのスキルの例

つまり、第1段階の起動時にはYAMLフロントマターだけが読み込まれ、SKILL.md本文は第2段階のスキルが呼び出されるまでコンテキストを消費しません。スキルが多数あっても起動時のコストはフロントマターの個数分だけであり、全スキルの本文が常時コンテキストに載るわけではない、というのがProgressive Disclosureの設計意図です。

第3段階は、スキルが複雑になり単一のSKILL.mdに収まりきらない場合や、特定のシナリオでしか使わないコンテキストがある場合に、追加ファイルをスキルディレクトリにバンドルしてSKILL.mdから参照する設計です。
公式ドキュメントで例示されているPDFスキルでは、フォーム入力の手順をforms.mdに分離しています。PDF処理全般がスキルの責務ですが、フォーム入力はそのうちの一部のシナリオでしか発生しません。SKILL.mdに全手順を書くとフォーム入力しないときもコンテキストを消費するため、forms.mdに分離してフォーム入力タスクのときだけClaudeがReadツールで参照します。

また、ベストプラクティスには Keep SKILL.md body under 500 lines for optimal performance とあり、500行を超える場合に別ファイルへの分割を推奨しています。

関連する議論

問題は上記仕様のProgressive Disclosureが期待通りに動いていないのではないか、という指摘がGitHub Issuesやブログ記事で複数見られることです。

GitHub Issues

2025年12月 ~ 2026年1月にかけて、スキルのトークン消費に関するIssueが報告されています。

Issue	起票日	ステータス	主張	Claude Code バージョン
#14834	2025/12/20	Open	`/context`でスキル全量のトークン数を表示しているが、実際はフロントマターだけロードされている	v2.0.74
#14882	2025/12/21	Open	`/context`でスキル全量のトークン数を表示。Progressive Disclosureが動いていない	v2.0.74
#15530	2025/12/28	Closed as duplicate	6スキルで17.8kトークン。フルファイルがロード	v2.0.76
#16616	2026/01/07	Closed as not planned	スキルが全量ロード（5.9k〜1.7k）。Pluginのフォーマット`.claude-plugin/plugin.json`に変換して解消	v2.0.76

これらのIssueで注目したい点が2つあります。

#14834の報告者が「実際にはフロントマターだけロードされている。/contextの表示が間違っているだけ」と主張していることです。この報告者は#16616にも「表示バグであり、v2.1.1で修正された」とコメントしています。ただし、報告者はAnthropic社員でないため公式回答ではありません。
#16616でPluginのフォーマットへの変換で解消したことです。表示バグだけなら両方とも同様に大きく表示されるはずで違和感があります。

なお、v2.1.1（2026/01/07）はCHANGELOGに記載がなく、修正内容の公式の記録はありません。

Zenn記事

Zenn記事「スキルを87個運用したら898KBになった。SKILL.md分割で27KBに戻した実測記録」（2026/02/21公開）では、以下の主張があります。

スキルが増えるほどClaude Codeが遅くなる。原因はSKILL.mdがコンテキストを圧迫しているからだった。SKILL.md（フロントマター+参照1行）とINSTRUCTIONS.md（詳細手順）に分割したところ、87スキル全体で898KB→27KBへ97%削減できた。

スキルを増やすほど問題が起きる。スキルが呼ばれるたびに、SKILL.mdの全内容がシステムプロンプトに注入されるのだ。

ただし、Claude Codeのバージョン明記がなく、計測もファイルサイズの比較のみでコンテキスト消費量の比較がないため、検証の余地があります。

議論の整理

これらの報告をまとめると、以下の状況が見えてきます。

v2.0.x時代（2025年12月頃）に、/contextコマンドの表示バグ、あるいは実際のロードバグがあった可能性がある
表示バグなのか実際のロードバグなのかは、Claude Codeのソースコードが非公開のため確定できない
v2.1.1以降で修正されたという報告があるが、公式の記録はない

重要なのは最新バージョンでの挙動なので、次のセクションでコンテキスト消費を計測して確認します。

計測

関連する議論で紹介したZenn記事のワークアラウンド（SKILL.md + INSTRUCTIONS.mdへの分割）が実際に効果があるのかを確認するため、同一スキルを「SKILL.md単体」と「SKILL.md + INSTRUCTIONS.mdに分割」の2パターンで比較しました。起動時と呼び出し時のトークン消費を/contextコマンドで計測しています。

/contextコマンドはトークン消費の内訳を表示します。本計測ではSkills（システムプロンプト内のスキル情報）とMessages（会話のやり取り）の2項目に注目します。

第1段階（起動時）：分割による変化なし

パターン	Skillsのトークン数	スキル分
スキルなし	393	0（ベースライン、スキルなしでもトークン消費あり）
SKILL.md単体	441	48（YAMLフロントマターのみ）
SKILL.md + INSTRUCTIONS.mdに分割	441	48（YAMLフロントマターのみ）

「SKILL.md単体」と「SKILL.md + INSTRUCTIONS.mdに分割」の起動時のSkillsのトークン数は同一です。

SKILL.md本文のサイズは起動時のコストに影響がなく、Progressive Disclosureが仕様通りに動作していることが確認できます。

第2段階（呼び出し時）：分割版のほうがコストが高い

パターン	Messages（呼び出し前）	Messages（呼び出し後）	Skills（呼び出し前）	Skills（呼び出し後）
SKILL.md単体	8	7.1k	441	441
SKILL.md + INSTRUCTIONS.mdに分割	8	9.4k	441	441

分割版ではMessagesのトークン数が2.3k多くなっています。

単体ではSKILL.md本文が1回で注入されるのに対し、分割版ではSKILL.md本文にINSTRUCTIONS.mdへの参照のみが書かれているため、Claudeが必ずReadツールで読みに行きます。その結果、ツール呼び出しのオーバーヘッドが加算されます。
また、どちらのパターンでもSkillsのトークン数の441はスキル呼び出し後も変化していません。SKILL.md本文はシステムプロンプトではなくMessagesのトークンとして計上されていました。

なお、v2.0.x時代に/contextコマンドの表示バグが報告されていましたが、本計測ではSkillsとMessagesのトークン数が仕様通りに変動しており、表示バグの影響はないと判断しています。

まとめ

計測結果は以下の通りです。

観点	結果
起動時のSkillsのトークン数	SKILL.md単体・分割版ともに同一（YAMLフロントマターのみ）
スキル呼び出し時のMessagesのトークン数	分割版のほうが2.3kトークン多い（Readツールのオーバーヘッド）
SKILL.md分割の効果	v2.1.50では不要。むしろ逆効果

v2.0.x時代に表示バグ、あるいはロードバグがあった可能性はありますが、少なくともv2.1.50ではProgressive Disclosureが正しく動作しており、全スキルの本文をINSTRUCTIONS.mdに分離するような対策は不要です。

スキルの運用で意識したい点は2つです。

YAMLフロントマターのdescriptionを適切に書く
- descriptionを見てスキルを呼び出しを判断するので、曖昧だと不要なスキルが呼ばれてMessagesのトークンを浪費します。
SKILL.md本文が大きくなったら関心ごとにファイルを分割する
- Progressive Disclosureの第3段階にあたり、特定のシナリオでしか使わない手順を別ファイルに分離することで、呼び出し時のトークン消費を抑えられます。ただし、全スキルの本文を一律に別ファイルへ逃がすのではなく、1つのスキル内でシナリオに応じて読み込みを分岐させる設計です。