メインコンテンツへスキップ
AMPL/ dev
開発系講座一覧

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

SKILL.mdは案内役、詳しい資料は別ファイルへ。何を本文に残し、何を切り出すかの判断基準と、切り出したファイルの案内の仕方を扱います

このレッスンで

終わる頃には、次ができるようになります

  • SKILL.mdと、reference.md・examples.md・scriptsフォルダの役割の違いを説明できる
  • SKILL.mdの本文に何を残し、何を別ファイルに切り出すべきかを判断できる
  • 切り出したファイルをSKILL.mdから案内し、必要なときだけ読み込まれる形にできる

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


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

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

SKILL.md

必須。概要と案内役。スキルが呼ばれるたびに読み込まれる本体

reference.md / examples.md など

詳しいAPI仕様や使用例。SKILL.mdから案内されたときだけ読み込まれる

scripts/ 配下のファイル

実行されるだけで、中身がそのままコンテキストに読み込まれることはない

スキルフォルダの中身、役割の違い

この3つの役割を混ぜないことが、組み立ての基本です。

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


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

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

1ファイルで十分な例 / 分けたほうがいい例

1ファイルで十分

議事録の書式、コードレビューの確認観点リスト、社内文書で避けたい言い回しのチェックリストなど、手順そのものが短く、毎回全部使う内容。SKILL.md本体に書き切って問題ありません。

分けたほうがいい

取引先ごとに違う契約書のひな形集、製品ごとに分かれたAPI仕様、過去の提案書10本分の実例集など、量が多く、実際に使うのは毎回そのうちの一部だけになる資料。全部をSKILL.mdに書くと、関係ない取引先の分まで毎回読み込まれてしまいます。

分けた資料は、使われない限りコンテキストに乗らないという利点があります。逆に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で書いてみましょう。何が書いてあり、いつ読めばよいかが伝わる文にしてください。


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

参考

Claude Code 公式: Extend Claude with skills(Add supporting files)
SKILL.mdと補助ファイル(reference.md・examples.md・scripts/)の役割分担、500行の目安についての一次情報
code.claude.com/docs · code.claude.com

このレッスンは役に立ちましたか?