スキルの設定と複数ファイル構成の作り方

スキルは SKILL.md 1枚から始められますが、手順や参照資料が増えてくると1枚では収まらなくなります。Claude Code はスキルのディレクトリをファイルシステムとして辿るため、必要になったファイルだけを読み込ませる構成にできます。この記事では、複数ファイル構成の組み立て方と、SKILL.md のフロントマターで挙動を設定する方法を、公式ドキュメントの記載に沿って整理します。

スキルが複数ファイルになる理由

Claude Code の起動時に読み込まれるのは、すべてのスキルの name と description（フロントマターのメタデータ）だけです。SKILL.md の本文はそのスキルが必要になった時点で読まれ、同じディレクトリに置いた参照ファイルは実際に参照されるまで読まれません。この仕組みを公式ドキュメントは「段階的開示（progressive disclosure）」と呼んでいます。

ここが複数ファイル構成の利点です。公式ドキュメントは「参照ファイル・データ・ドキュメントは、実際に読まれるまで文脈トークンを消費しない」と明記しています。つまり網羅的な API リファレンスや大きなサンプル集を同梱しても、使わない限りコストにならないわけです。逆に SKILL.md 本体に全部書くと、そのスキルが呼ばれるたびに全文が文脈を占有します。

目安として、公式は SKILL.md の本文を500行未満に保ち、それを超えそうなら別ファイルへ分割することを推奨しています。分割の判断は「量」だけでなく「読まれる頻度」で考えると分かりやすく、毎回要る手順は SKILL.md に、たまにしか要らない詳細は別ファイルに置きます。

もう一点、実行スクリプトは扱いが別です。ユーティリティスクリプトはbash から実行でき、その中身を文脈に読み込む必要がありません。トークンを消費するのは実行結果の出力だけです。公式は、決定的な処理は Claude にコードを書かせるのではなく、あらかじめ用意したスクリプトを実行させるほうが信頼性・速度・一貫性の面で有利だとしています。

SKILL.md のフロントマター

スキルの設定は SKILL.md 冒頭の、--- で挟んだ YAML フロントマターで行います。最小構成は次の形です。

---
name: summarize-changes
description: git の差分を読んで変更点を要約する。コミット前のレビューや変更概要を求められたときに使う。
---

# 変更点の要約

（ここに手順を書く）

discovery（見つけてもらう）に効く2つのフィールド

description はスキル選択そのものを左右するフィールドです。Claude は100件以上のスキルの中からこの記述だけを見て選ぶため、「何をするか」と「いつ使うか」の両方を書く必要があります。公式は次の点を強調しています。

• 必ず三人称で書く。この記述はシステムプロンプトへ差し込まれるため、視点が混ざると発見の精度が落ちます。「Excelファイルを処理してレポートを生成する」は可、「私が〜を手伝えます」「あなたはこれで〜できます」は避けます。
• 具体的な語を入れる。「ドキュメントを扱う」「データを処理する」のような曖昧な記述では選ばれません。ファイル拡張子や機能名など、実際の依頼文に出てくる語を含めます。

name には検証ルールがあります。最大64文字、英小文字・数字・ハイフンのみ、XMLタグ不可、そして予約語 anthropic / claude を含められません。命名は動名詞形（processing-pdfs、analyzing-spreadsheets）が推奨で、helper や utils のような曖昧な名前は避けます。description 側は最大1,024文字で、空にはできません。

Claude Code が追加している主なフィールド

上の2つは Agent Skills 標準の項目ですが、Claude Code はこれに加えて挙動を制御するフィールドを持ちます。よく使うものを挙げます。

name と description 以外はすべて任意です。name を省いた場合はディレクトリ名が使われ、description を省いた場合は本文の最初の段落が代わりに使われます。

ディレクトリ構成と参照の書き方

公式ドキュメントが示すディレクトリ構成は次の形です。

my-skill/
├── SKILL.md       （必須・全体像と案内役）
├── reference.md   （詳細なAPIドキュメント・必要になったら読まれる）
├── examples.md    （使用例・必要になったら読まれる）
└── scripts/
    └── helper.py  （ユーティリティスクリプト・実行される。読み込まれない）

重要なのは、ファイルを置くだけでは足りないことです。SKILL.md から各ファイルへリンクし、そのファイルに何が書いてあり、いつ読めばよいのかを示します。

## 追加の資料

- API の詳細は [reference.md](reference.md) を参照
- 使用例は [examples.md](examples.md) を参照

領域ごとに分ける構成も公式が例示しています。売上・財務・プロダクト・マーケティングのように話題が分かれるスキルでは、reference/finance.md、reference/sales.md のように分割しておくと、売上を聞かれたときに財務のスキーマだけが読まれ、他のファイルはディスク上に残ったまま文脈を1トークンも使いません。

パスの書き方には注意点があります。Windows 上でも必ずスラッシュ区切りで書くことです。scripts/helper.py は可、scripts\helper.py は Unix 系で壊れます。ファイル名も doc2.md のような無内容な名前ではなく、form_validation_rules.md のように中身が分かる名前を付けます。Claude はディレクトリを手掛かりに探すので、名前がそのまま索引として働きます。

スクリプトを同梱するときは、実行させたいのか、読ませたいのかを文章で明示します。公式は「フィールドを抽出するため analyze_form.py を実行する」（実行）と「抽出アルゴリズムは analyze_form.py を参照」（読解）を区別して書くよう求めています。ほとんどのユーティリティは実行のほうが確実で、トークンも節約できます。

段階的開示を壊さない3つの原則

1. 参照は SKILL.md から1段だけにする

これは実害のある落とし穴です。参照先からさらに参照が続いていると、Claude はファイルを部分的にしか読まないことがあります。公式は、入れ子の参照に出会ったときに head -100 のようなコマンドで冒頭だけを覗き、結果として情報が欠けると説明しています。

したがって、SKILL.md → advanced.md → details.md と辿らせる形は避け、参照ファイルはすべて SKILL.md から直接リンクするようにします。

2. 長い参照ファイルには目次を付ける

100行を超える参照ファイルには、先頭に目次を置きます。部分的に読まれた場合でも、そのファイルに何が載っているかの全体像は伝わるためです。

# API リファレンス

## 目次
- 認証とセットアップ
- 基本メソッド（作成・取得・更新・削除）
- 応用機能（バッチ処理・Webhook）
- エラー処理のパターン
- コード例

3. 時期に依存する記述を本文に置かない

「2025年8月より前なら旧APIを使う」のような書き方は、時間が経つと単に誤りになります。公式は、現行の方法を本文に書き、古い方法は「旧パターン」の節に <details> で畳んで残すことを勧めています。履歴としての情報は保ちつつ、本文は現在の正解だけになります。

あわせて、用語は1つに統一します。「API エンドポイント」「URL」「API ルート」「パス」を混ぜて書くと、Claude が指示を解釈しづらくなります。1つの概念には1つの語を最後まで使い通します。

スキルを置く場所と優先順位

Claude Code がスキルを読み込む場所は3種類あります。

同じ名前が複数の場所にある場合、個人スキルがプロジェクトスキルより優先されます。プラグインのスキルは /<plugin>:<skill-name> という別の名前になるため衝突せず、両方が同時に使えます。

作成はディレクトリを作って SKILL.md を置くだけです。

mkdir -p ~/.claude/skills/summarize-changes

編集の反映は自動です。Claude Code はスキルのディレクトリを監視しており、SKILL.md の追加・編集・削除は再起動なしでその場のセッションに反映されます。ただしライブ反映の対象は SKILL.md のテキストだけで、セッション開始時に存在しなかった最上位のスキルディレクトリを新しく作った場合は再起動が必要です。

プロジェクトスキルは、Claude Code を起動したディレクトリとリポジトリルートまでの各親ディレクトリから読み込まれます。サブディレクトリで起動してもルートのスキルは拾われます。一方、起動位置より下にある入れ子の .claude/skills/ は起動時には読み込まれず、Claude がそのサブディレクトリ内のファイルを読み書きした時点で有効になります。モノレポで、パッケージごとのスキルをそのパッケージを触っているときだけ効かせる、という使い方ができます。

スキルは「貼り直している指示」から作る

最後に作り始めの判断基準を1つ。公式は、同じ指示・チェックリスト・手順を繰り返し貼っていることに気づいたとき、あるいは CLAUDE.md の一節が事実の記述ではなく手順に育ってしまったときが、スキルにする合図だとしています。CLAUDE.md と違ってスキルの本文は使われるときだけ読み込まれるので、長い参照資料を抱えていても必要になるまでほとんどコストがかかりません。

参照した一次情報

この記事は次の公式ドキュメントの記載に基づいています（2026-08-22 確認）。仕様は更新されることがあるため、最新の内容は原典を確認してください。

• Skill authoring best practices（Claude Platform ドキュメント）
• Extend Claude with skills（Claude Code ドキュメント）