Claude Code の公式スキルは、単なる「命令書」ではなく 3 つの層で構成されています。

my-skill/
├── SKILL.md        # フロントマター + スキルボディ
├── reference.md    # 補助ファイル（詳細資料）
└── scripts/
    └── run.sh      # 補助ファイル（実行スクリプト）

この構造をそのまま模倣するだけでも動きますが、「何をどの層に置くか」を意識するとスキルの品質が変わります。

第 1 層：フロントマター——Claude の判断材料

フロントマターは Claude が「いつ・どう動くか」を制御する設定です。本文には現れず、Claude の振る舞いを外から制御します。

description の書き方が自動トリガーの精度を決める

description は Claude がスキルを使うかどうか判断する唯一の手がかりです。短く曖昧だと関係ない場面でも起動し、逆に厳密すぎると必要な場面でも使われません。

効果的なのは「動詞 + 対象 + 条件」の形です。

# 曖昧すぎる
description: コードをレビューする

# 具体的
description: >
  プルリクエストのコードをレビューする。
  "PR を見て" "レビューして" "変更を確認して" と言われたときに使う。

when_to_use フィールドに典型的な発話例を追加すると、さらにマッチ精度が上がります。

副作用のある操作は disable-model-invocation: true を付ける

デプロイ・コミット・外部 API への送信など、実行タイミングを人間が制御すべき操作には必ず付けます。このフラグがないと Claude が「コードが整ったので deploy してみますね」と自動実行する可能性があります。

---
description: 本番環境へデプロイする
disable-model-invocation: true   # 人間が /deploy と打ったときだけ動く
allowed-tools: Bash(git *) Bash(cargo *)
---

第 2 層：スキルボディ——起動時の指示

スキルボディはスキルが呼び出されたときに Claude のコンテキストに乗る本文です。セッション中ずっとコンテキストに残り続けるため、長く書くと毎ターンのトークン消費が増えます。

ボディには「手順」と「判断基準」だけ書く

詳細な仕様・大量のコード例・長い参照資料はボディに書かずに補助ファイルに切り出します。ボディは「何をすべきか・どう判断するか」の骨格だけにします。

## タスク

$ARGUMENTS のコンポーネントをリファクタリングする。

## 判断基準

- 100 行を超えるコンポーネントは分割を検討する
- props が 5 つ以上なら型定義を別ファイルに出す
- 詳細なパターン集は [patterns.md](patterns.md) を参照

## 手順

1. 対象ファイルを読む
2. patterns.md のチェックリストを適用する
3. 変更前後の diff を示して確認を取る

目安は 500 行以内です。超えそうになったら補助ファイルへの分割を検討するサインです。

動的コンテキスト注入でボディを"生きた"データにする

!`command` 構文を使うと、Claude がボディを読む前にシェルコマンドが実行されて結果が埋め込まれます。

---
description: コミット前の差分を確認してリスクを指摘する
---

## 現在の差分

!`git diff HEAD`

リスクのある変更（ハードコード・エラー処理漏れ・テスト未更新）があれば指摘してください。

「git diff の内容を Claude に渡してほしい」という場面でファイルを手動で貼り付ける必要がなくなります。ボディが静的な指示だけでなく、実行時の状態を取り込めるのがこの構文の利点です。

第 3 層：補助ファイル——遅延ロードの参照資料

補助ファイルはスキルと同じディレクトリに置くファイル群で、必要なときだけ Claude がロードします。常時コンテキストに乗るスキルボディとは異なり、参照されない限りトークンを消費しません。

何を補助ファイルに出すか

ボディに書く 補助ファイルに出す
手順・判断基準（骨格） 詳細なコード例・パターン集
補助ファイルへの参照リスト API 仕様・スキーマ定義
よく使う短いチェックリスト 大量の選択肢・網羅的な一覧

補助ファイルはボディから明示的に参照する

単に置くだけでは Claude は存在を知りません。ボディに「何が入っているか・いつ見るか」を書きます。

## 参照ファイル

- **[patterns.md](patterns.md)**: コンポーネント分割のパターン集。分割方法を判断するときに参照する
- **[examples.md](examples.md)**: リファクタリング前後のコード例。出力形式の確認に使う
- **scripts/validate.sh**: 変更後の静的解析スクリプト。Bash ツールで実行する

スクリプトは「ロードする」のではなく「実行する」ファイルです。Python・Shell など言語を問わず同梱できます。

設計のチェックリスト

スキルを書き終えたら次を確認します。

  • description に「いつ使うか」の条件が書いてあるか
  • 副作用のある操作に disable-model-invocation: true があるか
  • ボディが 500 行以内に収まっているか
  • 繰り返し参照される詳細資料を補助ファイルに出しているか
  • 補助ファイルをボディから参照しているか（何が入っているか・いつ見るかを明記）
  • 実行時データが必要なら !`command` を使っているか

まとめ

  • フロントマターは Claude の「いつ・どう動くか」を制御する設定層。description の精度が自動トリガーの品質を左右する
  • スキルボディはセッション中ずっとコンテキストに残る。手順と判断基準の骨格だけを置き、詳細は補助ファイルへ
  • 補助ファイルは必要なときだけロードされる遅延参照層。大量の資料をスキルに持たせても常時コストがかからない
  • 3 層の分離は「常時ロードするもの vs 必要時にロードするもの」というコスト設計の結果

出典