色違いの4つのブロックが浮かぶClaude Code Skillsを象徴する抽象図

Article

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

Claude CodeのSkills（SKILL.md）の作り方と使いどころを整理します。フロントマター仕様（description／allowed-tools／disable-model-invocation／context: fork）、配置スコープ4種、動的コンテキスト注入、CLAUDE.mdやサブエージェントとの役割分担、`/skills`での可視性制御まで、Skillsで作業を再利用したい中級者向けに公式仕様を踏まえて解説します。

This article is not published in this language yet, so the Japanese version is shown instead.

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

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

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

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

同じ指示や手順を会話に何度も貼っている：それはSkillに切り出す候補
CLAUDE.mdの一部が「事実」ではなく「手順」になっている：Skillに移すとCLAUDE.mdが短くなる
タスクが副作用を持ち、人間が明示的に呼びたい：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が起動判断に使う。`when_to_use`と合算で1,536文字で切られる
`name`	表示名。未指定ならディレクトリ名（小文字英数字とハイフン、64文字以内）
`disable-model-invocation`	`true`でユーザー明示起動だけ受け付ける（`/deploy`のような副作用のあるSkill向け）
`user-invocable`	`false`で`/`メニューから隠す。Claudeだけが使う背景知識Skill向け
`allowed-tools`	このSkillが有効な間、許可なしで使えるツール（例：`Bash(git add ) Bash(git commit )`）
`model` / `effort`	Skill実行中だけのモデル・effortレベル上書き
`context: fork`	サブエージェントの隔離コンテキストで実行（メイン会話に履歴を渡さない）
`agent`	`context: fork`時に使うサブエージェント種別（`Explore` / `Plan` / カスタム）
`paths`	このSkillが自動起動される対象ファイルパスの絞り込み（globパターン、複数可）
`arguments` / `argument-hint`	名前付き引数の宣言とオートコンプリート表示

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

配置スコープと優先順位

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

スコープ	パス	適用先
Enterprise（managed）	管理者設定	組織全員
Personal	`~/.claude/skills/<name>/SKILL.md`	自分の全プロジェクト
Project	`.claude/skills/<name>/SKILL.md`	このプロジェクトのみ
Plugin	`<plugin>/skills/<name>/SKILL.md`	プラグインを有効化した範囲

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

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

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

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

仕組み	ロードのタイミング	向く用途
`CLAUDE.md`	毎セッションの先頭で常時ロード	短く具体的な事実・禁止事項・確認コマンド
Skills	必要なときだけ全文ロード（descriptionは常時可視）	再利用できる手順・チェックリスト・参照ドキュメント
カスタムスラッシュコマンド	`/`から呼び出した瞬間	仕様上はSkillsと同等。既存`.claude/commands/`もそのまま動く
サブエージェント	メインから委譲した瞬間、別コンテキストで	並列調査・読み取り専用調査・コンテキストを汚さない処理
Hooks	強制（特定イベントごとに必ず実行）	lint・秘密情報チェックなど確定動作させたい処理

押さえどころは、「毎回読ませる必要があるか」と「人間が呼ぶか／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後に再起動するのが現実的な対処です。

起動の制御と可視性

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

frontmatter	ユーザー起動	Claude起動	コンテキスト挙動
既定	○	○	descriptionは常時可視、本文は起動時に追加
`disable-model-invocation: true`	○	✕	descriptionも非可視、本文はユーザー起動時のみ
`user-invocable: false`	✕	○	descriptionは常時可視、本文はClaude起動時のみ

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

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

値	Claudeへの提示	`/`メニュー表示
`"on"`	name + description	表示
`"name-only"`	nameのみ	表示
`"user-invocable-only"`	非表示	表示
`"off"`	非表示	非表示

allowed-toolsの注意点

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

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