Claude CodeのSkillsとは？SKILL.mdの書き方とCLAUDE.md／サブエージェントとの使い分け

Claude CodeのSkillsは、何度も使う指示・チェックリスト・手順を1つのSKILL.mdにまとめて、必要なときだけ読み込ませる仕組みです。本記事は、Skillsの位置づけ、SKILL.mdの作り方、配置スコープ、起動制御、そしてCLAUDE.md・カスタムスラッシュコマンド・サブエージェントとの使い分けを整理します。

結論：「毎セッション読ませる」べきでないものをSkillsへ

Skillsを入れる前に押さえるべき点は1つです。CLAUDE.mdは毎セッション全文がロードされ続けるが、Skillsはオンデマンドでだけロードされるということです。これにより、長いリファレンスや特定タスクの手順を「使うときだけ呼び出す」運用が成立します。

Skillsを作る判断基準は次のとおりです。

1. 同じ指示や手順を会話に何度も貼っている：それはSkillに切り出す候補
2. CLAUDE.mdの一部が「事実」ではなく「手順」になっている：Skillに移すとCLAUDE.mdが短くなる
3. タスクが副作用を持ち、人間が明示的に呼びたい：disable-model-invocation: trueのSkillで/skill-nameから起動する

「Claude CodeのHooksで開発ワークフローを自動化する方法」が「強制」、「Claude Codeのカスタムスラッシュコマンドで作業を効率化する方法」が「呼び出し」、Skillsが「再利用できる手順とリファレンス」と覚えると整理しやすくなります。公式上もコマンドはSkillsに統合されており、.claude/commands/<name>.mdと.claude/skills/<name>/SKILL.mdは同じ/nameを作るのと公式が明記しています。

SKILL.mdの最小構成

Skillはディレクトリ単位で管理し、SKILL.mdがエントリポイントになります。最小構成は次の通りです。

my-skill/
├── SKILL.md           # 必須：手順とフロントマター
├── reference.md       # 任意：詳細リファレンス
└── scripts/
    └── helper.py      # 任意：実行スクリプト

SKILL.mdの最小例は次のとおりです。

---
description: 未コミットの変更を要約し、見逃しやすいリスクを指摘する
---

## 現在の変更

!`git diff HEAD`

## 指示

上の差分を2〜3行で要約し、エラーハンドリング不足・ハードコード・テスト追従漏れの観点でリスクを列挙する。差分が空ならその旨を返す。

ポイントは2つです。

• descriptionは、Claudeが「いつこのSkillを使うべきか」を判断する材料になる。検索意図に近い言葉で書く
• !`git diff HEAD`は動的コンテキスト注入。Skillが起動する直前にこのコマンドが実行され、出力に置換されてClaudeへ渡される

このSkillを~/.claude/skills/summarize-changes/SKILL.mdに置けば、ユーザーは/summarize-changesで明示起動でき、Claudeも「何を変えた？」のような問いに自動でこのSkillを選びます。

フロントマター主要フィールド

SKILL.md先頭のYAMLフロントマターで、Skillの挙動を細かく制御できます。全フィールドは公式のskillsドキュメントに整理されていますが、よく使うものを抜き出します。

descriptionは実質的に「Claudeに見せる広告文」です。「変更を要約する／コミットメッセージを下書きする／差分のリスクを指摘する」のように、想定される問いに含まれる単語を入れておくと自動起動の精度が上がります。

配置スコープと優先順位

Skillはどこに置くかで「誰が使えるか」が決まります。公式は4つのスコープを定義しています。

同名Skillが複数スコープにあるときはEnterprise → Personal → Projectの順で上書きされます。プラグインSkillはplugin-name:skill-nameの名前空間を持つので、衝突しません。

プロジェクトSkillは、起動ディレクトリから親ディレクトリのリポジトリルートまで.claude/skills/を自動探索します。さらに、サブディレクトリでファイルを触ったときに、そのサブツリーの.claude/skills/もオンデマンドでロードされる、というモノレポ向けの挙動も公式に明記されています。

CLAUDE.md・コマンド・サブエージェントとの使い分け

役割分担が混乱しやすいので、判断基準を表で整理します。

押さえどころは、「毎回読ませる必要があるか」と「人間が呼ぶか／Claudeが呼ぶか」の2軸です。CLAUDE.mdは前者、Skillsは後者だけが必要なときに使います。disable-model-invocation: trueを設定すれば、Skillの本文は人間が/nameを打つまで読み込まれず、descriptionすらClaudeのコンテキストから外せます。

CLAUDE.md本体の書き方は「CLAUDE.mdテンプレート完全版：開発ルール・禁止事項・確認コマンドをまとめる」、サブエージェントの仕組みは「Claude Codeのサブエージェントとは？使いどころと注意点」が土台になります。

動的コンテキスト注入と引数渡し

Skillsの強みの1つは、Skill本文がClaudeに渡る前にシェルコマンドの結果を埋め込める点です。

---
name: pr-summary
description: 指定したPRの差分・コメント・変更ファイルを要約する
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PRコンテキスト
- 差分: !`gh pr diff`
- コメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`

## 指示
このPRを300字で要約する。

!`<command>`の部分は、Skill起動直前に実行され、出力に置換されてClaudeに渡ります。Claudeはコマンド自体は見ず、最終結果だけを受け取ります。複数行コマンドは```!で始まるコードブロックに書けます。

引数も渡せます。$ARGUMENTSで全引数、$0 / $1で個別位置参照、arguments: [issue, branch]と宣言すれば$issue / $branchで名前参照できます。/fix-issue 123と呼べば、Skill内の$ARGUMENTSが123に置き換わる、というシンプルな仕組みです。

context: forkでサブエージェント実行

公式が新しく整理したパターンに、context: forkがあります。Skill本文を別コンテキストのサブエージェントに渡し、メイン会話に履歴が残らない形で実行できます。

---
name: deep-research
description: 指定トピックをコードベース内で調査する
context: fork
agent: Explore
---

「$ARGUMENTS」について次の手順で調査する。

1. Glob / Grepで関連ファイルを洗い出す
2. 該当箇所を読んで意図を要約する
3. ファイルパス付きで結論を返す

agent: Exploreを指定すると、読み取り専用ツール中心の組み込みExploreサブエージェントで実行されます。ExploreとPlanはCLAUDE.mdやgit statusを読まない仕様なので、Skill本文だけが入った最小コンテキストで動きます。これがclaude-code-context-design系の「コンテキスト圧迫を避ける」狙いに直結します。

ただし公式が警告している通り、context: forkは明示的なタスクを書いたSkillにだけ意味があります。「APIのコンベンションを使う」のような前提だけのSkillをforkしても、サブエージェントは指示なしで戻ってきます。

ライフサイクルとトークンコスト

Skillが起動されると、レンダリング済みのSKILL.mdは会話に1つのメッセージとして入り、そのセッションが続く限り残ります。Claude Codeは後続ターンでSkillファイルを読み直さないので、毎ターン適用したい指示は「常時ルール」として書きます。

オートコンパクションが走ると、各Skillの最新呼び出しが要約の後ろに再アタッチされます。各Skillは先頭5,000トークンまで、再アタッチ合計は25,000トークンまでで、新しく呼ばれた順に予算を埋めるため、古いSkillは押し出される可能性があります。

「Skillが効いていない気がする」ときは、内容は残っているがモデルが別のツールを選んでいるケースが多いです。descriptionを強くする、hooksで確定的に縛る、もしくは/clear後に再起動するのが現実的な対処です。

起動の制御と可視性

公式ドキュメントには、起動可否と可視性をきれいに分離した表があります。

副作用のあるSkill（/deploy／/send-slack-message／/commit）はdisable-model-invocation: trueにしておくと、Claudeが「準備が整ったから」と勝手にデプロイしてしまうリスクを潰せます。

組織やプロジェクトで提供されたSkillを自分の判断でON/OFFしたい場合は、settings.jsonのskillOverridesを使います。/skillsメニュー上でSpaceで状態を切り替え、Enterで.claude/settings.local.jsonに保存されます。

allowed-toolsの注意点

allowed-toolsはSkillが有効な間、ツール承認をスキップする仕組みです。Skillが自分自身に幅広いツール許可を与えられるため、プロジェクト同梱Skillは信頼前に必ず内容を読むことが公式の注意として明記されています。プロジェクト同梱.claude/skills/のallowed-toolsが効くのは、ワークスペース信頼ダイアログを許可した後です。

Skillが特定ツールを使えないようにしたい場合は、Skill側で絞るのではなく、「Claude Codeを使うときのセキュリティチェックリスト」で扱った/permissionsのdenyルールを使います。Skillのallowed-toolsは許可付与であって制限ではない、という点を混同しないでください。

やってはいけないこと

公式の解説と運用経験から、Skillsでハマりやすい5パターンを挙げます。

1. CLAUDE.mdに書くべき短い事実をSkillに分けてしまう：起動されるまでロードされないので、毎回必要な内容なら逆効果
2. Skillに長いリファレンスを直書きする：本文は500行以内に抑え、詳細はreference.mdに分離して必要なときだけ読ませる（公式の推奨）
3. allowed-toolsにBash(*)のような広い許可を入れる：Skill自体が攻撃面になる
4. disable-model-invocationなしの/deployを作る：Claudeが「準備OK」と判断して勝手にデプロイし得る
5. 同じ機能のSkillを場所違いに重複して置く：スコープの上書き順序を把握していないと、思った定義が使われない

Skills設計チェックリスト

• 「毎セッション必要」でないことを確認し、CLAUDE.mdから切り出した
• descriptionに検索意図の単語を入れた（またはdisable-model-invocation: trueにした）
• 本文は500行以内、詳細は別ファイルに分離した
• allowed-toolsは最小権限で書いた
• 副作用のあるSkillはdisable-model-invocation: trueにした
• スコープ（Personal／Project／Plugin／Enterprise）を意図通りに選んだ
• 必要に応じてcontext: forkとagent: Exploreでコンテキストを隔離した
• /skillsメニューやskillOverridesで組織提供Skillの可視性を整えた

次に読むおすすめ記事：

• 「CLAUDE.mdテンプレート完全版：開発ルール・禁止事項・確認コマンドをまとめる」：Skillsの隣でロードされ続けるCLAUDE.mdの書き方
• 「Claude Codeのカスタムスラッシュコマンドで作業を効率化する方法」：Skillsと同等扱いになったコマンド機能の整理
• 「Claude Codeのサブエージェントとは？使いどころと注意点」：context: forkが委譲する先のサブエージェントの仕組み