スキルやCLAUDE.mdを増やすとClaudeが重く遅くなるのではと心配な人向け
スキルやCLAUDE.mdを増やすとClaudeが重くなりそうで怖い、という時にこのしくみを思い出す。たまにしか使わない長い手順は、毎回読み込まれるCLAUDE.mdに書かず、呼んだ時だけ本体が読まれるスキルへ逃がす。巨大な資料は本体ではなく別ファイル（reference.md など）に分け、本体は500行以内に薄く保つ。これで何個スキルを積んでも起動を軽いまま運用できる。
スキルを5個10個と増やすと、Claude Codeの起動が重くなって会話も遅くなるんじゃないか。そう心配して、便利そうなスキルを入れるのをためらう人は多いと思います。私も最初はそうでした。
ところが実際は、スキルを何個積んでも起動時に読み込まれるのは「スキルの名前」と「短い説明文」だけ。スキル本体の中身は、そのスキルが実際に呼び出された瞬間まで一切読まれません。この「必要になるまで読まない」段階的なしくみが Progressive Disclosure、日本語で言う段階的開示です。
だから長い手順書をスキルに入れても、使う前はほぼタダ。これは正直、知ってるかどうかで運用が変わります。
噛み砕くと、図書館の本棚みたいなもの
図書館をイメージしてください。入口には全部の本の「背表紙＝タイトルと一行紹介」がずらっと並んでいます。あなたはまずそれを眺めて、どの本が今の用事に役立つか見当をつけます。
背表紙を見るだけなら一瞬で、何冊あっても疲れません。実際に手に取って中身を読むのは、必要な1冊だけ。
Claude Codeのスキルもこれと同じです。起動時に机に載るのは全スキルの背表紙、つまり名前と説明文だけ。本文という分厚い中身は、その本を開くと決めた時に初めて机に広げられます。
さらに、その本の巻末にある資料編にあたる別ファイルは、本文を読んでいて「ここ詳しく知りたい」となった時だけめくる。読み込みは全部で3段階に分かれています。
読み込みは3段階に分かれている
公式ドキュメントはこう書いています。「In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked.」
通常のセッションでは、何が使えるか分かるように説明文だけがContextに載り、本体は呼び出された時に初めて読み込まれる、という意味です。段階に分けるとこうなります。
第1段階は起動時で、常にこうなります。全スキルの「名前＋説明文」だけが作業机に載ります。これは軽い。本体である SKILL.md の本文はまだ読まれていません。
第2段階は呼び出した時。そのスキルが呼ばれて初めて、SKILL.md の本文全体が机に広がります。
第3段階はさらに必要になった時。SKILL.md の中から案内している別ファイル、たとえば reference.md を、本当に必要になった時だけ読みます。
公式 best-practices はこう言い切っています。「Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.」
CLAUDE.mdと違い、スキルの本体は使う時だけ読まれるので、長い資料を抱えていても必要になるまでコストはほぼゼロ。ここが Progressive Disclosure の核です。背表紙はいつも見えるけど、本文は開くまで読まない。
料理レシピ投稿サイトの運営で、実際の手順を見る
料理レシピを投稿するサイトを運営しているとします。Claude Codeに手伝わせるスキルを少しずつ増やしながら、起動が重くならないのを確かめていきます。
ステップ1: レシピ整形スキルを「本体＋資料」に分けて作る
レシピの体裁を整えるスキルを1個作ります。ポイントは、よく使う指示だけを本体に書き、めったに見ない長い食材データは別ファイルに逃がすこと。公式が示すフォルダ構成はこうです。
my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
└── helper.py (utility script - executed, not loaded)料理サイト向けに置き換えると、SKILL.md に「材料→手順→盛り付けの順で整える」という短い指示を書き、reference.md に数百種類の食材の旬・カロリー・別名データをまとめて入れておく感じです。
公式の Tip は「Keep SKILL.md under 500 lines.」とはっきり言っています。SKILL.mdは500行以内に保て、ということ。本体は薄く、詳しい資料は外へ。
ステップ2: 起動して、机に載っているものを確認する
Claude Codeを起動します。この時点で机に載ったのは「recipe-format」というレシピ整形スキルの名前と、その一行の説明文だけ。数百種類の食材データが入った reference.md も、整形ルールの本文も、まだ1文字も読まれていません。
$ claude
# 起動。スキルは名前と説明文だけ把握された状態背表紙だけ見えている、図書館の入口の状態です。
ステップ3: スキルを呼び出して、本体が広がる瞬間を見る
「この鶏むね肉のレシピ、サイトの体裁に整えて」とお願いするか、自分で /recipe-format と打ちます。ここで初めて SKILL.md の本文が机に広がり、Claudeが整形ルールに沿って動き出します。
> /recipe-format
# ここで初めて SKILL.md 本文が読み込まれる ＝ 第2段階ステップ4: 食材データが要る場面で、初めて資料が読まれる
整形中に「この食材の旬と別名も添えて」と頼むと、Claudeは本体から案内されている reference.md を、ここで初めて開きます。最初から数百種類ぶんを抱え込まずに済むわけです。公式は「letting Claude access detailed reference material only when needed」と書いていて、詳しい資料は必要な時だけ読ませる、という意味。これが第3段階です。
ステップ5: スキルを10個に増やしても起動が重くならないのを確かめる
ここで初心者がやりがちな勘違いがあります。「スキルを10個入れたら、起動時に10個ぶんの本文が机を埋めるのでは」というもの。実際は違います。
カロリー計算、栄養表示、英語翻訳、タグ付け、見出し生成…とスキルを10個に増やしても、起動時に載るのは10個ぶんの「名前＋説明文」だけ。説明文は1個あたりほんの数行なので、10個でも机はほとんど埋まりません。本文10個ぶんが載るわけではないのです。
つまり「使うかもしれない手順書」は遠慮なくスキルに置ける。これがProgressive Disclosureの一番おいしいところです。
ステップ6: SKILL.mdを編集しても効かない、という罠を踏む
呼び出したあとに SKILL.md を書き換えて「さっきの整形をやり直して」と頼むと、古いルールのまま動くことがあります。理由はライフサイクルにあります。
公式はこう明言しています。「When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns」。
呼び出されたSKILL.mdの中身は1つのメッセージとして会話に入り、そのセッション中ずっと残る。そしてClaude Codeは後のやり取りでファイルを読み直さない、ということ。
一度広げた本は机に置きっぱなしで、ファイルを直しても机の上の紙は変わらない。直した内容を反映させたいなら、/recipe-format をもう一度呼び直します。
圧縮が起きると、古いスキルは机から落ちることがある
会話が長くなって机が埋まると、Claude Codeは古い内容を要約して場所を空けます。これが compaction、日本語で言う圧縮です。この時、呼び出し済みのスキルがどう引き継がれるかにもルールがあります。
公式はこう書いています。「Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens.」
要約の後、各スキルの最新の呼び出しぶんを貼り直すが、保てるのは各5,000トークンの先頭部分まで。貼り直されるスキルは合計25,000トークンの枠を分け合う、ということです。
枠は新しく呼んだスキルから順に埋まるので、1回のセッションでたくさん呼んでいると、古いスキルは圧縮後にまるごと落ちることもあります。落ちて効かなくなったと感じたら、もう一度呼び直せば本体が戻ります。
例外：subagentに先読みさせたスキルだけは起動時に全部入る
ひとつだけ例外があります。subagent、つまり別働隊のClaudeに「このスキルを先読みしておけ」と設定した場合です。
公式は「Subagents with preloaded skills work differently: the full skill content is injected at startup.」と書いています。スキルを先読みさせたサブエージェントは別扱いで、本体が起動時に丸ごと注入される、という意味です。
つまり段階的開示の「本文は呼ぶまで読まない」ルールが、ここだけ崩れます。別働隊に最初から知っておいてほしい知識は、あえて先読みさせる。逆に言うと、それ以外は全部「呼ぶまで読まない」が基本です。
つまり Progressive Disclosure は何をしてくれるのか
- やってくれる: スキルを何個積んでも、起動時に机を埋めるのは「名前＋説明文」だけに抑える。長い手順書や資料を抱えても、使うまでコストはほぼゼロ
- やってくれる: 呼び出した本体はセッション中ずっと残し、同じやり取り内で読み直す無駄をなくす
- やってくれない: 一度呼び出したスキルの自動更新はしない。
SKILL.mdを直しても呼び直すまで反映されない - 意味が薄い場面: 全セッションで必ず使う「広く効く事実」。それは
CLAUDE.mdに書く方が素直で、スキルにしてもどのみち毎回読むので段階的開示の恩恵が出ない
使いどころ3シナリオ（料理サイトで再現）
シナリオ1: たまにしか使わない長い手順をスキルに逃がす
料理サイトで「年1回の正月特集ページを組む手順」みたいな、めったに使わないけど長い段取りがあるとします。これを CLAUDE.md に書くと、正月以外の364日も毎回机に載って邪魔になります。公式 best-practices も「たまにしか関係しない手順はスキルにせよ」と勧めています。スキルにしておけば、正月特集を組む時に呼んだ瞬間だけ本体が読まれます。
シナリオ2: 巨大な食材データを別ファイルに分けて本体を薄く保つ
レシピ整形スキルに「全食材1,000種の旬・栄養・別名表」を持たせたい。これを SKILL.md 本体に全部書くと、呼ぶたびに1,000種ぶんが机を埋めます。そこで本体には「整形のルール」だけ書き、データ表は reference.md に分離します。整形だけの時はデータ表は読まれず、「栄養も添えて」と言われた時だけ読まれる。本体を500行以内に保て、という公式Tipはこのためにあります。
シナリオ3: スキルが増えすぎて説明文が削られていないか確認する
料理サイト用にスキルを30個40個と増やすと、別の落とし穴が出ます。公式いわく、スキルが多いと説明文が予算に収まるよう短く削られる。説明文の枠はデフォルトでそのモデルの作業机全体の1%ぶん（設定で変更できます）。description と when_to_use の合算で最大1,536文字を超えると切り詰められます。枠があふれると、呼び出し回数が少ないスキルから説明文が落とされ、名前だけが残る状態になります。名前だけになると会話の内容に合わせた自動の呼び出しができなくなり、自分で /スキル名 と打たない限り動かないスキルが出ます。/doctor を打てば、枠があふれていてどのスキルが削られているか確認できます。
初心者が踏みやすい落とし穴
- 「スキルを増やすと起動が重くなる」と思い込む。起動時に載るのは名前＋説明文だけ。本文は呼ぶまで読まれないので、数を増やしても起動はほぼ変わりません。
SKILL.mdを直したのに反映されないと焦る。一度呼んだ本体はセッション中机に残り続け、読み直されません。直したら同じスキルを呼び直すのが正解です。- たまにしか使わない長文を
CLAUDE.mdに書く。CLAUDE.mdは毎セッション全文が机に載る常駐メモ。たまに使う手順はスキルに移さないと、机を無駄に埋め続けます。 - 本体に巨大な資料を全部詰め込む。呼ぶたびに全部読まれて重くなります。詳しい資料は
reference.mdなどに分け、本体からは案内だけにします。 - スキルを大量に積んで説明文が削られているのに気づかない。説明文が削られると名前だけが残り、内容に合わせた自動の呼び出しができなくなります。
/doctorで枠のあふれを確認する習慣をつけてください。 - 圧縮後も全スキルがそのまま残ると思う。圧縮されると各スキル先頭5,000トークン・合計25,000トークンの枠で引き継がれ、古いものは落ちることがあります。効かなくなったら呼び直しましょう。
- subagentの先読みでも段階的開示が効くと思う。先読みさせたスキルだけは起動時に本体が丸ごと入ります。ここは例外なので、重い資料を不用意に先読みさせないこと。
書き方
（しくみの概念のため打つコマンドはなし）スキルは ~/.claude/skills/スキル名/SKILL.md として置き、起動時は名前＋説明文だけ、呼び出し時に本体、必要時に reference.md が読み込まれるやってみるとこうなる
入力
$ claude
# 起動。スキル10個ぶんの「名前＋説明文」だけが机に載る
> /recipe-format
# ここで初めて SKILL.md 本体が読み込まれる出力例
起動直後は recipe-format / calorie-calc / nutrition-label …と並ぶ説明文だけが載った軽い状態。/recipe-format を呼ぶと、その SKILL.md 本文だけが机に広がる。「食材の旬も添えて」と頼んだ時に初めて reference.md が読まれる。スキルを10個積んでも起動時の机は説明文10個ぶんしか埋まらない。このページに出てきた言葉
- Progressive Disclosure（段階的開示）
- スキルを「必要になるまで読まない」3段階のしくみ。名前＋説明文→本体→追加資料の順で、要る時だけ読み込む
- Context（コンテキスト）
- Claudeが一度に覚えていられる作業机の広さ。ここに載っているぶんだけ把握でき、埋まるほど反応は重くなる
- トークン
- 文章の量を測る単位。机にどれだけ載っているかをこの数で数える
- SKILL.md
- スキルの本体ファイル。上部に説明文などの設定、その下に動作の指示を書く
- description（説明文）
- スキルが何をして、いつ使うかを短く書いた一行。Claudeはこれを見て使うか判断する。起動時は常に机に載る
- invoke（呼び出す）
- スキルを発動させること。/スキル名 と打つか、内容に合っていればClaudeが自動で選ぶ
- CLAUDE.md
- プロジェクト用の覚え書き。毎セッション全文が机に載る常駐メモで、スキルと違い中身が常に読まれる
- compaction（圧縮）
- 会話が長くなり机が埋まった時、古い内容を要約して場所を空けるしくみ。各スキル先頭5,000トークン・合計25,000トークンの枠で引き継がれる
- subagent（サブエージェント）
- 特定の仕事だけを任される別働隊のClaude。先読みさせたスキルだけは起動時に本体が丸ごと入る（段階的開示の例外）