第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 のほかに、役割ごとのフォルダーを置けます。

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 です。

考えてみよう

1. 自分の SKILL.md（または、これから書くスキル）で、特定の場面でしか使わない説明はどこですか。それを別のファイルに分けるなら、ファイル名と、SKILL.md に書く「いつ読むか」の1文をどう書きますか
2. 「詳しくは reference/ を参照」という1文を、読む条件の付いた文に書き直してください。条件は、依頼の種類か、作業の段階で書きます
3. 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スキル入門の入口のページにまとめています。

1. スキルとは何か
2. SKILL.mdを書く
3. 発動する説明を書く
4. 複数のファイルに分ける（この記事）
5. スクリプトとallowed-tools
6. 検証スキルを作る（前編）
7. 検証スキルを作る（後編）
8. Gitでチームに共有する
9. うまく動かないとき
10. 演習（前編）：作る・確かめる・発動させる
11. 演習（中編）：分ける・事前承認
12. 演習（後編）：共有と振り返り