Claude Code skills：スキルの仕組み、SKILL.md、エージェントがいつ読み込むか

Claude Code のスキルとは

スキル（Skill）は、特定の種類の作業の手順を書いた SKILL.md を含むフォルダです。例えば、プロジェクトをどうデプロイするか、どうレビューするか、どうリリースするか。エージェントはセッションの最初からスキルの存在を知っていますが、作業がそれを必要としたときに初めて全文を読みます。

Claude Code のスキルは、長く CLAUDE.md を育ててきた人なら誰でも知っている問題を解決します。指示ファイルは少しずつ膨らみます。80行のデプロイ手順は週に1度しか必要ないのに、タイポを直すだけのセッションでも毎回コンテキストに居座ります。スキルはこのような手順を、常時のコンテキストから外し、必要なときだけ読み込む仕組みです。

スキルの構成要素

最小のスキルは、1つのフォルダと1つのファイルです。プロジェクトのスキルはリポジトリに、個人のスキルはユーザーのホームディレクトリに置きます。

.claude/skills/deploy/SKILL.md      # プロジェクトのスキル。git でチームと共有
~/.claude/skills/review/SKILL.md    # 個人のスキル。すべてのプロジェクトで利用可能

SKILL.md の隣には、テンプレート、スクリプト、参考資料などの補助ファイルを置けます。エージェントは、本文がそれらを参照していて必要になったときにだけ開きます。

.claude/skills/deploy/
├── SKILL.md           # メインの手順
├── checklist.md       # 詳細なチェックリスト。リンク先として読まれる
└── rollback.sh        # ロールバック用のスクリプト

フロントマター：name と description

ファイルの先頭には、--- で囲まれた YAML のブロックがあります。特に重要なのは2つのフィールドです。name は短いスキル名で、description は、そのスキルが何をし、いつ使うべきかの説明です。

---
name: deploy
description: サイトを FTP でホスティングにデプロイする。変更をサーバーに反映したいとき、サーバーとの差分を確認したいとき、デプロイをロールバックしたいときに使う。
---

# デプロイ

1. まず試し実行：`./deploy.sh -n`。
2. ファイル一覧を確認する。秘密情報やテスト用スクリプトが含まれていないこと。
3. アップロード：`./deploy.sh`。
4. 変更したページを開き、200 を返すことを確かめる。

ロールバックは、このフォルダの rollback.sh を参照。

フロントマターの下は通常の Markdown です。手順、コマンド、制約、隣接ファイルへのリンクを書きます。その作業を初めて担当する新しい同僚への説明書のつもりで書いてください。

エージェントがスキルを読み込むタイミング

セッションの初めには、利用可能な各スキルの名前と説明だけがコンテキストに入ります。スキルあたり数行なので、数十個あっても問題になりません。ユーザーの依頼や現在の作業ステップが説明と一致すると、エージェントはスキルを呼び出し、そこで初めて SKILL.md の全文がコンテキストに読み込まれます。

ここから実践的な原則が導かれます。スキルは説明によって起動します。 エージェントは、開くと決めるまでスキルの本文を見ることができません。description に「補助的なスキル」と書けば、いつ必要か分かりません。「サイトのデプロイ。ファイルをサーバーに反映したいとき、またはデプロイを取り消したいときに使う」と書けば、分かります。

自動的に選ばれるだけでなく、スキルはスラッシュで名前を指定して、手動で呼び出すこともできます（例：/deploy）。どの手順が必要か確実に分かっていて、エージェントが依頼と説明を照合してくれるのを期待したくないときに便利です。

スキルが起動するように description を書く

• 何をするか。動詞で、一文で書く。「サイトのデプロイ」「コミット前の変更レビュー」。
• いつ使うか。ユーザーが実際に依頼するときの言い回しを挙げる。「サーバーに上げて」「公開して」「元に戻して」。
• いつ使わないか。近いスキルと混同しやすいなら明記する。「ボットのデプロイには使わない。サイトだけ」。
• 「便利なスキル」「作業を助ける」のような一般的な言葉は避ける。そうした言葉には情報がありません。

段階的な開示

スキルは段階的な開示（progressive disclosure）の原則で作られています。情報は層に分けて与えられ、次の層は必要になったときにだけ読み込まれます。

これは、指示ファイルに長大な文章を書く代わりに、短い地図を常に手元に置き、詳細はリンク先に置くという考え方と同じです。違いは、スキルがこの読み込みを仕組みとして行う点です。エージェントが必要な文書を自分で開いてくれることを祈る必要がありません。さらに、第3層のスクリプトはコード全体をコンテキストに読み込まずに実行できます。

スキル・CLAUDE.md・スラッシュコマンドの違い

いずれの仕組みもエージェントに指示を伝えますが、タイミングとコンテキストへの負担が異なります。

選び方は単純です。ほぼすべての作業で必要な指示は CLAUDE.md に書きます。特定の種類の作業でだけ必要ならスキルにします。同じ長い依頼を毎回手で入力しているなら、手動で呼び出すコマンドかスキルの候補です。

厳格な禁止事項はスキルに移さないでください。スキルは読み込まれないことがあり、「秘密情報をコミットしない」というルールは常に有効でなければなりません。そうした不変の条件は CLAUDE.md に残し、可能な限りフック、アクセス権限、CI のチェックで仕組み化します。

Claude Code のスキルを作る手順

1. 繰り返す手順を見つける。 目安は、同じことを3回エージェントに説明した、または CLAUDE.md の中に、10件に1件の作業でしか必要ない節がある、という状況です。
2. フォルダを作る。 .claude/skills/<名前>/ の中に SKILL.md を作成します。
3. フロントマターを書く。 name と、いつスキルを使うかが明確な description を書きます。
4. 手順を書く。 具体的なコマンドと完了の基準を書きます。何を確認し、何を成功とみなすかを明記してください。
5. 長い部分は別ファイルへ。 補助ファイルに分け、本文からリンクします。
6. CLAUDE.md の重複を消す。 1行の案内だけを残します。「デプロイ：スキル deploy を参照」。
7. 確かめる。 新しいセッションで、スキル名を使わずに自分の言葉で依頼し、エージェントが読み込むかを見ます。読み込まなければ、説明を書き直してください。

スキルの例

デプロイのスキル

典型的な候補です。手順はめったに使われず、長く、危険で、失敗すると高くつきます。スキルには手順の順序（まず試し実行、次にアップロード）、アップロードしてはいけないもの、結果の確認方法、ロールバックの方法を書きます。コードを編集するたびに、エージェントがサーバーのことを頭に入れておく必要はありません。サーバーの話になったときだけ読み込めばよいのです。

レビューのスキル

---
name: review
description: コミット前の現在の変更をレビューする。差分の確認、修正のバグ検出、コミット準備を求められたときに使う。
---

# 変更のレビュー

1. 差分を取得：`git diff` と `git diff --staged`。
2. 変更された各ファイルについて確認する：
   - ユーザー入力は出力時にエスケープされているか。
   - SQL クエリはパラメータ化されているか。
   - デバッグ出力や一時ファイルが残っていないか。
3. プロジェクトのテストとリンターを実行（コマンドは CLAUDE.md にある）。
4. 報告：問題をファイルと行番号つきで、重大なものから軽微なものへ並べる。
   問題がなければ、そう書く。指摘をでっち上げない。

このスキルは「全体を見て問題がないか確認して」という曖昧な依頼を、毎回同じ項目で行う再現可能なチェックに変えます。

セッション終了のスキル

もう一つ役立つのは、作業の終わりの儀式です。ローカル環境を止め、一時ファイルを消し、進捗ログに完了した内容と残りを書き、詳しい説明つきでコミットします。これは、セッション間のコンテキストの喪失を直接防ぎます。次のセッションは推測ではなく、リポジトリの最新の状態から始まります。

よくある間違い

• 曖昧な description。 スキルはあるのに、エージェントが呼び出さない。具体的な起動条件を description に書き直して解決します。
• 長すぎるスキル。 古い400行の節を丸ごと SKILL.md に移した。コンテキストの肥大化が、少し遅れて戻ってきます。本文は短く保ち、詳細は隣のファイルに置いてください。
• CLAUDE.md との重複。 同じ手順が2か所に書かれ、時間とともにずれていく。正しい情報源は1つにしてください。
• スキル同士の競合。 似た説明の2つのスキルがあると、エージェントはどちらを選ぶかが偶然になります。「使う／使わない」を明確に分けてください。
• 古いコマンド。 スクリプトの名前を変えたのに、スキルは古い名前を参照したまま。スキルもプロジェクトのコードの一部です。手順と同じコミットで更新してください。

節をスキルに移すタイミング

定期的に CLAUDE.md を読み直し、各節について問いかけてください。通常の作業のどのくらいの割合で本当に必要か。ほぼ常に必要なら、そのままでよい。10件に1件なら、スキルの候補です。

2つ目のサインは長さです。1画面に収まらない節は、ほぼ確実に規則ではなく手順を書いています。手順は実行するときに通して読むほうが分かりやすく、セッション中ずっと頭の片隅に置く必要はありません。

3つ目のサインは、繰り返される説明です。同じ作業について同じ補足を何度も書いているなら、一度だけスキルに書いてください。1週間後に、手作業の修正が減ったかを見てください。それがスキルが機能している証拠です。

まとめ

Claude Code のスキルは、手順をプロジェクトのそばに保存し、毎セッションのコンテキストを消費せずに済ませる仕組みです。説明は常に見えていて、本文は必要なときに読み込まれ、補助ファイルはさらに後で読み込まれます。CLAUDE.md にはプロジェクトの地図と厳格なルールを残し、デプロイ、レビュー、リリースなど特定の種類の作業はスキルに移します。ファイル構成と段階的なコンテキスト開示の仕組みは、ハーネスエンジニアリングのコースで実践的に扱っています。