中身の組み立てと、ファイルを分けるとき

descriptionが整い、スキルが呼ばれるようになったら、次は中身の組み立てです。SKILL.mdに何を書き、何を書かないかで、スキルの使い勝手は大きく変わります。

SKILL.mdは案内役、詳しい話は別ファイルへ

Claude Codeの公式ドキュメントは、スキルのフォルダに複数のファイルを含められると説明しています。目的は、SKILL.md本文を要点だけに絞りつつ、必要なときだけ詳しい資料にアクセスできるようにすることです。

この3つの役割を混ぜないことが、組み立ての基本です。毎回必ず読んでほしい要点はSKILL.mdに、量が多く必要なときだけ参照すればよい資料は別ファイルに、実行すればよいだけの処理はスクリプトに、それぞれ置き場所を分けます。

いつファイルを分けるべきか

公式ドキュメントは、SKILL.mdを500行未満に保ち、詳細な資料は別ファイルに移すよう勧めています。行数そのものより、スキルが呼ばれるたびに、その内容を全部読ませる必要があるかどうかが判断の軸です。

分けた資料は、使われない限りコンテキストに乗らないという利点があります。逆にSKILL.md本体に全部詰め込むと、スキルが呼ばれるたびに使わない部分までまとめて読み込まれ、無駄になります。

別ファイルは、SKILL.mdから案内する

ファイルを分けただけでは、Claudeはその存在に気づけません。公式ドキュメントは、SKILL.md本文の中で、それぞれのファイルに何が書いてあり、いつ読めばよいかを案内するよう勧めています。

たとえば、取引先ごとの契約書ひな形を分けたスキールなら、SKILL.mdの末尾にこう書きます。

## 参考資料

- A社向けの契約書ひな形は contracts/a-sha.md を参照
- B社向けの契約書ひな形は contracts/b-sha.md を参照
- 見積書のチェック項目一覧は checklist.md を参照

この案内があるおかげで、Claudeは「今回はA社の話だから、contracts/a-sha.mdだけ読めばよい」と判断できます。案内を書き忘れると、せっかく分けたファイルが一度も読まれないまま放置されることになります。

Claude（アプリ）は構成が少し違う

Claude（アプリ）でスキルをアップロードする場合、フォルダの中に小文字のskill.mdを1つ置き、追加の資料はresources/フォルダにまとめる構成になります。Claude Codeのようにreference.mdとexamples.mdを役割ごとに分けて置くというより、1つの本体ファイルと、補助資料フォルダというシンプルな2層構成です。前のレッスンで扱ったname・descriptionの文字数上限とあわせて、アプリ向けに作るときはClaude Codeよりコンパクトにまとめる意識が必要になります。

やってみよう

演習1：自分のスキル候補のファイル構成を考える

最初のレッスンで書き出したスキル候補について、SKILL.md本体に残す内容と、別ファイルに切り出したい内容を分けてみましょう。切り出す場合は、ファイル名も仮に決めてみてください。

演習2：案内文を1つ書く

切り出したファイルがある場合、それをSKILL.mdからどう案内するか、1〜2行のMarkdownで書いてみましょう。何が書いてあり、いつ読めばよいかが伝わる文にしてください。

今日のまとめ

3行で振り返ります。

• SKILL.mdは案内役、詳しい資料はreference.md等、実行するだけの処理はscripts/と役割を分ける
• 判断の軸は行数そのものより、毎回全部読ませる必要があるかどうか
• 分けたファイルはSKILL.mdから案内しないと、存在に気づかれず読まれないまま残る

次のレッスンでは、スキルが使える道具を、allowed-toolsなど公式で確認した項目だけで安全に絞る方法を扱います。