「SKILL.md に手順も注意も例外も書いていたら、どんどん長くなります。全部1つのファイルに入れて大丈夫ですか」
「補助のファイルを置いておけば、Claude は必要なときに読んでくれるのですか」
第3回までで、スキルの置き場所と SKILL.md の形、そして発動する説明（description）の書き方を見ました。次は、SKILL.md が育って長くなったときの分け方です。
スキルの本文は、発動するたびに会話（コンテキスト）へ入ります。手順書を1つに詰め込むと、その場面に要らない部分まで毎回読ませることになり、直すのも大変です。かといって別ファイルに分けただけでは、Claude に「いつ読むか」が伝わりません。
第4回では、SKILL.md を目次にして詳しい資料を別ファイルに置く段階的開示、フォルダーの構成、SKILL.md から「いつ読むか」を書く書き方を扱います。スクリプトの実行と allowed-tools は第5回の「スクリプトは読まずに実行させる」「allowed-tools で事前承認する」です。例には、この連載で作る Ansible の検証スキル ansible-verify（第6回の「題材：検証の6段階」から作り始めます）を使います。数値・仕様は2026年10月時点です。
段階的開示：SKILL.md は目次
すべてを2,000行の1つのファイルに詰め込むと、コンテキストを大きく使い、保守も大変です。段階的開示は、これを解決する考え方です。
- SKILL.md には必須の指示だけを書く
- 詳しい資料は別のファイルに置き、必要なときにだけ Claude に読ませる
Academy の講座「Introduction to agent skills」（日本語版の名前は「Agent Skills入門」。第1回の「あわせて読みたい公式の教材」で紹介した公式の教材）の動画の言い方では、コンテキストの中に文書全体ではなく目次を持つ、ということです。
下の2つの箱は、第1回の「読み込みの3段階」で見たのと同じ並びです。起動時には全スキルの名前と説明だけが入り、description が依頼に一致したときに SKILL.md の本文が入り、本文から指された reference/ や scripts/ のファイルは、必要になったときにだけ読まれます。Anthropic の API ドキュメント（Platform）のスキルの説明も、この3段を Level 1（メタデータ、いつも読み込まれる）、Level 2（指示、発動したときに読み込まれる）、Level 3（資料とコード、必要に応じて読み込まれる）と呼んでいます。
たとえば ansible-verify では、SKILL.md に手順と止まるところを書き、changed の項目の読み方は reference/ の資料に分けます。検証の手順は毎回使いますが、changed の読み方の細かい説明は、差分を確かめるときにしか要らないからです。
目安は、SKILL.md を500行未満に保つことです。超えたら、別のファイルに分けられないか考えます。この数字は、Claude Code の公式の文書、Platform のベストプラクティス、オープン標準の仕様（agentskills.io）の3か所に、同じ形で書かれています。
- SKILL.md には必須の指示だけを書く
- 詳しい資料は別ファイルに置き、必要なときだけ読ませる
- 目安は SKILL.md 500行未満
フォルダーの構成
スキルのフォルダーには、SKILL.md のほかに、役割ごとのフォルダーを置けます。
| 場所 | 入れるもの | 筆者の例 |
|---|---|---|
| SKILL.md | 手順と、資料を読む条件。唯一の必須 | ansible-verify |
scripts/ | 実行するコード | scripts/verify.sh |
references/（標準） | 追加の文書 | 筆者の例は reference/reading-diff.md |
assets/ | テンプレート・データ | 資料づくりのスキル share-deck は templates/ |
ansible-verify のフォルダーは、次のような形になります。
.claude/skills/ansible-verify/
├── SKILL.md
├── reference/
│ └── reading-diff.md
└── scripts/
└── verify.sh補足：scripts/・references/・assets/ は、オープン標準（agentskills.io）が提案する名前です。標準の仕様では、必須なのは SKILL.md だけで、ほかは任意です。標準の references/ は複数形ですが、筆者の例（ansible-verify と、資料づくりのスキル share-deck）は単数形の reference/ です。名前は SKILL.md からリンクするので、チームで決めてよく、どれにするかは、チームで使うときの運用ルール（筆者の例）で決めておきます（第8回の「チームで使うときの運用ルール（筆者の例）」）。share-deck は、SKILL.md、reference、templates、scripts などの構成です。この連載の例は、すべて reference/（単数）にそろえます。
なお、share-deck の元になった資料づくりのプロジェクトは、連載「Claude活用入門」第5回の「筆者の実例：資料づくりのプロジェクト」で紹介しています。
SKILL.md から「いつ読むか」を書く
別のファイルに分けただけでは、Claude はそのファイルが何で、いつ読めばよいのか分かりません。SKILL.md の側に、中身と読む時機を書きます。公式の文書も、SKILL.md から補助ファイルを参照し、各ファイルに何が入っていて、いつ読み込むべきかが Claude に分かるようにするよう書いています。
- リンクに条件を付ける：例「changed の読み方は
reference/reading-diff.mdを読む（差分確認のときだけ）」 - 書かないとどうなるか：何のファイルか、いつ読むかが Claude に伝わらない。公式も、中身と読む時機が分かるように書くとある
- 参照は1段まで：SKILL.md から直接リンクする。資料からさらに別の資料へ辿らせない（Platform のベストプラクティス）
- パスの基準：Claude が
cdすると作業フォルダーが動く。公式は、スキルのフォルダーを表す${CLAUDE_SKILL_DIR}を勧める。筆者の例はリポジトリ直下からの相対パス。Code タブで両方動くかは、筆者は確かめていない - 「読む」と「実行する」を分ける：スクリプトは実行する（第5回の「スクリプトは読まずに実行させる」）
条件の付け方の例です。
悪い例：詳しくは reference/reading-diff.md を参照。
良い例：changed の読み方は reference/reading-diff.md を読む（差分確認のときだけ）。悪い例では、reading-diff.md が何の資料で、毎回読むのか、ときどき読むのかが分かりません。良い例なら、差分を確かめる場面になったときだけ読まれ、それ以外の場面ではコンテキストを使いません。
参照は1段までというのは、SKILL.md から reading-diff.md へリンクし、reading-diff.md からさらに別の資料へ辿らせる、という鎖を作らない、という意味です。Platform のベストプラクティスは、すべての資料を SKILL.md から直接リンクするよう勧めています。直接リンクしておけば、必要なときにファイルが最後まで読まれるからです。Platform のベストプラクティスの説明では、資料から別の資料へ辿るような入れ子の参照だと、Claude は head -100 のようなコマンドで先頭だけを確かめ、不完全な情報になることがあります。
パスの基準にも注意が要ります。Claude Code は、コマンドを、セッションのシェルの現在の作業フォルダーで実行します。Claude が途中で cd すると、その作業フォルダーが動いてしまい、相対パスで書いたスクリプトの場所が合わなくなります。公式の文書は、毎回同じように解決させたいパスには、スキルのフォルダーを表す ${CLAUDE_SKILL_DIR}（スキルの SKILL.md があるフォルダー）か、プロジェクトのフォルダーを表す ${CLAUDE_PROJECT_DIR} を使うよう書いています。
筆者の例は、bash .claude/skills/ansible-verify/scripts/verify.sh … のように、リポジトリ直下からの相対パスで書く形です。この形は、CLI の claude -p（2.1.302）で、allowed-tools に書いたうえで確認なしに動くことを確かめました（第11回の手順6）。2.1.289 では承認待ちで、動きませんでした。${CLAUDE_SKILL_DIR} の形と、Code タブでどちらが動くかは、筆者は確かめていません。
補足：出典は https://code.claude.com/docs/ja/skills （Add supporting files）と https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices です。
考えてみよう
- 自分の SKILL.md（または、これから書くスキル）で、特定の場面でしか使わない説明はどこですか。それを別のファイルに分けるなら、ファイル名と、SKILL.md に書く「いつ読むか」の1文をどう書きますか
- 「詳しくは reference/ を参照」という1文を、読む条件の付いた文に書き直してください。条件は、依頼の種類か、作業の段階で書きます
SKILL.md→reading-diff.md→handler-notes.mdのように、資料から資料へ辿る構成になっています。参照を1段までにするには、どう直しますか
ヒント：1は「段階的開示：SKILL.md は目次」、2・3は「SKILL.md から「いつ読むか」を書く」の節を見直してください。
まとめ
- 段階的開示は、SKILL.md を目次にして、詳しい資料を別ファイルに置き、必要なときにだけ読ませる考え方。目安は SKILL.md 500行未満（公式・Platform・オープン標準の3か所に同じ数字）
- 起動時は名前と説明だけ、一致したときに SKILL.md、必要なときに
reference/やscripts/。第1回の「読み込みの3段階」と同じ並び - フォルダーの構成は、SKILL.md（唯一の必須）・
scripts/（実行するコード）・references/（追加の文書）・assets/（テンプレート・データ）。名前は標準の提案で、SKILL.md からのリンクで決まる。この連載はreference/（単数）にそろえる - SKILL.md からは、条件付きでリンクする。書かないと、何のファイルで、いつ読むかが伝わらない
- 参照は1段まで。SKILL.md から直接リンクする
- パスの基準は、
cdで動かない書き方にする。公式は${CLAUDE_SKILL_DIR}を勧める
次回は、スクリプトを読まずに実行させる書き方、allowed-tools による事前承認と、権限ルールとの関係を扱います。
連載「Claude Codeスキル入門」全12回
全回の目次と、読む順番・目的別の読み方は、Claude Codeスキル入門の入口のページにまとめています。
- スキルとは何か
- SKILL.mdを書く
- 発動する説明を書く
- 複数のファイルに分ける（この記事）
- スクリプトとallowed-tools
- 検証スキルを作る（前編）
- 検証スキルを作る（後編）
- Gitでチームに共有する
- うまく動かないとき
- 演習（前編）：作る・確かめる・発動させる
- 演習（中編）：分ける・事前承認
- 演習（後編）：共有と振り返り
コメント