Claude Code Skills完全ガイド — SKILL.mdの書き方・frontmatter・呼び出し制御まで

Claude Code Skillsとは、SKILL.md というMarkdownファイルを1つ置くだけで、Claudeに専門知識や定型手順を追加できる拡張機能です。ユーザーが /skill-name で明示的に呼び出すことも、Claudeが会話の文脈から関連すると判断したときに自動で読み込むこともできます。

カスタムスラッシュコマンドは現在Skillsに統合されており、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy コマンドを作る同じ仕組みです。本記事はSKILL.mdの作成手順、frontmatter全フィールド、4つの配置スコープ、呼び出し制御、引数と動的コンテキスト注入、サブエージェント実行までを公式docsの現行仕様に沿ってまとめます。

Claude Code Skillsとは

Skillsは「呼ばれたときだけコンテキストに載る手順書・知識パック」です。CLAUDE.mdが全ターンで読み込まれる常駐ルールなのに対し、Skillの本文は起動されるまでロードされないため、長い参照資料を持たせても普段のトークン消費はごくわずかで済みます。

Skillを作る目安は2つあります。同じ指示やチェックリストをチャットに何度も貼り付けているとき、そしてCLAUDE.mdのある節が「事実」ではなく「手順書」に育ってしまったときです。逆に、一度きりの相談や繰り返す見込みのない作業は、都度チャットに貼り付けるほうが手早く、わざわざSkill化するほどの価値はありません。

Claude CodeのSkillsは、複数のAIツール間で共通利用できるAgent Skillsオープン標準に準拠しています。その上でClaude Code独自の拡張として、起動主体の制御(後述の disable-model-invocation など)、サブエージェント実行(context: fork)、動的コンテキスト注入が使えます。

また、Claude Code本体には /code-review、/batch、/debug、/loop、/claude-api などのバンドルSkillが同梱されており、全セッションで利用できます(設定の disableBundledSkills で /doctor を除く全バンドルSkillを無効化可能)。固定ロジックの組み込みコマンドとは異なり、バンドルSkillはプロンプトベースでClaudeにツールを使わせる方式のため、自作Skillと同じ感覚で /skill-name として呼び出せます。書き方のテンプレ集はClaude Code Skillsの書き方5パターンで別途扱っているため、以降は仕様の全体像に集中します。

SKILL.mdの最小構造と作成手順

最小のSkillは「ディレクトリ1つ + SKILL.md 1ファイル」で成立します。ディレクトリ名がそのまま / で呼ぶコマンド名になり、frontmatterの description がClaudeの自動起動判断の材料になります。

個人用Skillを作る場合、まずディレクトリを作成します。

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

続いて ~/.claude/skills/summarize-changes/SKILL.md を保存します。次の例は、コミット前の変更差分を要約してリスクを指摘するSkillです。

---
description: 未コミットの変更を要約しリスクを指摘する。ユーザーが「何を変えた?」と
  聞いたとき、コミットメッセージを求めたとき、差分レビューを頼んだときに使う。
---
 
## 現在の変更
 
!`git diff HEAD`
 
## 指示
 
上記の変更を2〜3点の箇条書きで要約し、エラー処理の欠落・ハードコードされた値・
テスト更新漏れなどのリスクがあれば列挙する。差分が空なら「未コミットの変更は
ありません」と答える。

!`git diff HEAD` の行は動的コンテキスト注入(後述)で、Skill本文がClaudeに渡る前にコマンドが実行され、出力に置き換わります。テストは2通りで、「何を変えた?」のように description に合致する質問を投げてClaudeに自動起動させるか、/summarize-changes で直接呼び出します。

ディレクトリには SKILL.md 以外の補助ファイルも置けます。テンプレート、期待出力の例、Claudeが実行するスクリプトなどを同じディレクトリに置き、SKILL.md本文から「どのファイルに何があるか」を参照しておくと、必要なときだけ読み込まれます。

my-skill/
├── SKILL.md           # 本体の指示(必須)
├── reference.md       # 詳細リファレンス(必要時にロード)
├── examples/
│   └── sample.md      # 期待する出力例
└── scripts/
    └── validate.sh    # Claudeが実行するスクリプト

frontmatter全フィールド一覧

frontmatterの全フィールドは任意で、必須フィールドはありません。唯一 description だけが推奨で、省略するとMarkdown本文の最初の段落が説明として使われます。まず基本のフィールドから見ていきます。

起動と権限まわりの制御フィールドは次のとおりです。

実行環境を変えるフィールドもあります。

注意したいのは、name が「表示名」であってコマンド名ではない点です。/ の後に打つコマンド名は配置場所から決まります。.claude/skills/deploy-staging/SKILL.md なら /deploy-staging(ディレクトリ名)、.claude/commands/deploy.md なら /deploy(ファイル名)、プラグインの skills/ 配下なら /plugin-name:skill-name(プラグイン名前空間付き)です。frontmatterの name がコマンド名になるのは、プラグイン直下に SKILL.md を置いた場合だけという例外的な扱いになっています。

配置場所は4スコープ — 同名時の優先順位に注意

Skillsの配置場所は4種類で、置く場所が「誰が使えるか」を決めます。同名のSkillが複数スコープにあるときの優先順位は、エンタープライズ > 個人 > プロジェクトです。

なお .claude/commands/ のファイルとSkillが同名の場合は、Skill側が優先されます。既存のカスタムコマンド資産はそのまま動き続けるので、移行を急ぐ必要はありません。コマンド側の全体像はスラッシュコマンド一覧と使い方で扱っています。

運用面では次の3つの仕様を知っておくと迷いません。

1. ライブ変更検知: skillsディレクトリ配下の追加・編集・削除は、セッションを再起動せずその場で反映されます。再起動が必要なのは、セッション開始時に存在しなかったトップレベルのskillsディレクトリを新規作成した場合だけです。
2. 親・子ディレクトリの自動探索: 起動ディレクトリからリポジトリルートまでの各親ディレクトリの .claude/skills/ が読み込まれ、monorepoでは packages/frontend/.claude/skills/ のような入れ子のディレクトリも作業対象に応じて探索されます。
3. 追加ディレクトリからのロード: --add-dir フラグや /add-dir コマンドで追加したディレクトリの .claude/skills/ は自動でロードされます。一方、settings.jsonの permissions.additionalDirectories はファイルアクセス権限のみでSkillをロードしません。

呼び出し方3通りと起動主体の制御

Skillsの起動経路は、ユーザーの /skill-name 入力、Claudeの自動判断、Skillツール経由のプログラム的呼び出しの3通りです。既定ではユーザーとClaudeのどちらでも起動でき、frontmatterの2フィールドでこれを制限できます。

使い分けの軸は「副作用の有無」です。/deploy や /commit のような実行タイミングを人間が握りたいワークフローには disable-model-invocation: true を付けます。逆に、レガシーシステムの背景知識のように「Claudeには知っていてほしいが、ユーザーがコマンドとして打つ意味はない」知識には user-invocable: false が向いています。

Claude側の起動可否は権限ルールでも制御でき、denyルールに Skill を追加すると全Skillの自動起動を止められます。Skill(commit)(完全一致)や Skill(review-pr *)(引数付き前方一致)で個別の許可・拒否も書けます。

さらに、SKILL.md自体を編集したくない共有Skillには、settings.jsonの skillOverrides 設定で表示状態を上書きできます。値は4種類です。

/skills メニューでSkillを選んでSpaceキーを押すと状態が切り替わり、Enterで .claude/settings.local.json に保存されます。プラグイン提供のSkillはこの設定の対象外で、/plugin から管理します。

自動起動の精度を決めるのは description の質です。Claudeは description(と when_to_use)を読んで「今この文脈で使うべきか」を判断するため、ユーザーが実際に言いそうなキーワードを含め、主要ユースケースを文頭に置きます。description と when_to_use の合計は一覧表示時に1,536字で切り詰められるので、重要な情報ほど前に書く構成が安全です。

引数と文字列置換の仕組み

Skillは呼び出し時の引数を本文に埋め込めます。/fix-issue 123 のように起動すると、本文中の $ARGUMENTS が 123 に置き換わってからClaudeに渡る、という流れです。

位置引数はシェル流のクォートを解釈し、/my-skill "hello world" second なら $0 が hello world、$1 が second に展開されます。本文に $1.00 のような文字列をそのまま残したいときは \$1.00 とエスケープします。実用上とくに重要なのは ${CLAUDE_SKILL_DIR} で、同梱スクリプトを python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py のように呼べば、どのスコープに配置されても正しいパスで実行できます。

動的コンテキスト注入で実行時データを渡す

!`<command>` 構文を本文に書くと、Skill内容がClaudeに送られる前にシェルコマンドが実行され、その出力がプレースホルダを置き換えます。Claudeが受け取るのは「コマンド文字列」ではなく「実行結果のデータ」です。

## Pull Requestの文脈
- PRの差分: !`gh pr diff`
- PRのコメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`

これは前処理であってClaudeによる実行ではない、という点が挙動の理解に効きます。要点は3つです。

1. 置換は元ファイルに対して1回だけ走り、コマンド出力は平文として挿入されます。出力に含まれる !`...` が再展開されることはありません。
2. インライン形式は ! が行頭か空白の直後にあるときだけ認識されます。KEY=!`cmd` のように他の文字に続く場合は文字どおりのテキストとして残り、コマンドは実行されません。
3. 複数行のコマンドは ```! で始まるフェンスドコードブロックでまとめて書けます。

組織でこの挙動を止めたい場合は、設定の disableSkillShellExecution を true にします。ユーザー・プロジェクト・プラグイン・追加ディレクトリ由来のSkillでコマンド実行が無効化され、各コマンドは実行されずに「shell command execution disabled by policy」という文字列に置き換わります(バンドルSkillと管理者配布Skillは対象外)。

サブエージェントで実行する(context: fork)

frontmatterに context: fork を書くと、Skillはメイン会話から切り離された独立コンテキストのサブエージェントで実行されます。SKILL.mdの本文がそのままサブエージェントへのプロンプトになり、会話履歴へのアクセスはありません。

---
name: deep-research
description: トピックを詳しく調査する
context: fork
agent: Explore
---
 
$ARGUMENTSについて調査する:
 
1. GlobとGrepで関連ファイルを特定する
2. コードを読んで分析する
3. ファイル参照付きで発見を要約する

agent フィールドで実行環境(モデル・ツール・権限)を選びます。組み込みの Explore / Plan / general-purpose、または .claude/agents/ のカスタムサブエージェントを指定でき、省略時は general-purpose です。ExploreとPlanはコンテキストを小さく保つためCLAUDE.mdとgit statusを読み込まない仕様で、agent: Explore のSkillはSKILL.md本文とエージェント自身のシステムプロンプトだけで動きます。

注意点として、context: fork は明示的なタスクを持つSkillにだけ意味があります。「このAPI規約に従う」のようなガイドラインだけのSkillをforkすると、サブエージェントは実行すべきタスクのない指示を受け取り、意味のある出力なしに戻ってきます。

SkillsとSub-agentsの関係は双方向で、Skill側から context: fork でサブエージェントに乗る方向と、サブエージェント定義の skills フィールドでSkill全文を起動時に事前ロードする方向があります。サブエージェント側の設計はClaude Code Sub-agents完全ガイドで扱っています。

CLAUDE.md・Sub-agents・MCPとの使い分け

Skillsを設計するときの判断軸は「常駐か遅延か」「Claude内の手順か外部システムか」「メイン文脈か独立文脈か」の3つです。よくある運用ニーズと推奨構成を対応表にまとめます。

選び方の原則は次の3つに集約できます。

1. 常駐するルールはCLAUDE.md、呼んだときだけのルールはSkill。CLAUDE.mdは全プロンプトで読まれるため、たまにしか使わない手順を入れると毎ターンのトークンが無駄になります。CLAUDE.md側の設計はCLAUDE.mdの書き方10パターンが参考になります。
2. 外部システム接続はMCP、Claude内の手順はSkill。認証・状態保持・API呼び出しはMCPサーバーの責務で、Skillは「Claudeに手順書を渡す」役割に徹します。
3. 重い分析はサブエージェント、軽い手順はインラインのSkill。context: fork を使えばSkillのままサブエージェント実行に切り替えられるため、最初はインラインで作り、コンテキストを圧迫し始めたらforkに移す段階的な設計が取れます。

チームや組織への配布を考えるなら、プロジェクトの .claude/skills/ をgit管理する方法のほか、プラグインの skills/ ディレクトリに同梱して配る方法があります。プラグイン化するとhooksやMCPサーバーとセットで配布でき、詳細はプラグインとマーケットプレイス完全ガイドで解説しています。

コンテキスト消費の仕組み — 500行以内が目安

Skillsは遅延ロードですが、コストがゼロになるわけではありません。仕組みを知っておくと「Skillを増やしたら自動起動の精度が落ちた」という現象に対処できます。

通常セッションでは、全Skillの名前と description が常時コンテキストに載り、本文は起動時に初めてロードされます。この一覧に使える文字数の予算はモデルのコンテキストウィンドウの1%で、あふれると起動頻度の低いSkillの説明から削られます。/doctor を実行すると予算超過の有無と影響を受けているSkillを確認できます。予算は設定の skillListingBudgetFraction(例: 0.02 で2%)か環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で引き上げられます。

一度起動したSkill本文は、1つのメッセージとして会話に入りセッションの残り全体に留まります。後のターンでファイルが再読込されることはないため、タスク全体に効かせたい指示は「常時適用の指示」として書きます。自動コンパクション(会話の要約圧縮)が走るときは、各Skillの最新の呼び出しが先頭5,000トークンまで、全Skill合計25,000トークンの予算内で要約後に再添付されます。直近に呼んだSkillから優先して枠が埋まるため、多数のSkillを呼んだセッションでは古いSkillが脱落することがあります。

この仕組みから導かれる実践指針が、公式docsも示す「SKILL.mdは500行以内に保ち、詳細資料は補助ファイルへ移す」です。本文を簡潔にするほど、ロード後の毎ターンコストが下がります。

よくあるつまずきと回避策

Skills運用で踏みやすい落とし穴を9つ、現行仕様に基づく回避策とセットでまとめます。

つまずき1: descriptionが曖昧で自動起動が空振りする

description: "コミットを書く" のような短い説明では、Claudeが文脈との関連を判定できません。「未コミットの変更からコミットメッセージを推定して生成する。ユーザーがコミットを頼んだとき、差分の要約を求めたときに使う」のように、用途とトリガーフレーズを具体的に書きます。Skillが多い環境では1,536字の切り詰めも効いてくるため、主要ユースケースを文頭に置く構成が有効です。

つまずき2: nameを変えたのにコマンド名が変わらない

frontmatterの name は一覧の表示名で、/ の後に打つコマンド名はディレクトリ名(またはコマンドファイル名)から決まります。コマンド名を変えたいときはディレクトリ自体をリネームします。唯一の例外はプラグイン直下の SKILL.md で、この場合だけ name がコマンド名の由来になります。

つまずき3: 同名Skillで意図しない側が呼ばれる

優先順位はエンタープライズ > 個人 > プロジェクトで、個人の ~/.claude/skills/commit はプロジェクトの .claude/skills/commit を上書きします。チーム共有のSkillを確実に使わせたい名前は、個人スコープに同名Skillを残さないか、プロジェクト固有の名前(media-commit など)に分けると衝突を避けられます。

つまずき4: allowed-toolsを広く許可しすぎる

allowed-tools はSkill起動中、列挙したツールを承認なしで使えるようにする許可リストです。Bash(git add *) Bash(git commit *) のようにコマンド系統で絞るのが基本で、広い許可はSkillの自動起動と組み合わさったとき想定外の実行につながります。プロジェクトの .claude/skills/ にコミットされたSkillの allowed-tools はワークスペースの信頼ダイアログ承認後に有効になる仕様のため、リポジトリを信頼する前にSkillの中身を確認する運用が安全です。

つまずき5: 巨大な参照資料をSKILL.mdに直貼りする

1万字の資料を本文に貼ると、起動のたびに1万字分がコンテキストに乗り、セッション終了まで残り続けます。資料は reference.md などの補助ファイルに分離し、本文には「APIの詳細はreference.mdを参照」とだけ書けば、Claudeが必要なときだけ読みに行きます。

つまずき6: セッション途中でSkillが効かなくなったように見える

多くの場合、Skill内容はまだコンテキストに残っていて、モデルが他のアプローチを選んでいるだけです。description と指示文を強めて優先させ続けるか、確実に強制したい動作はHooksで決定論的に縛る選択肢があります。コンパクション後にSkillの全文が必要なら、再度 /skill-name で呼び直すと復元できます。

つまずき7: 副作用つきSkillにdisable-model-invocationを付け忘れる

/deploy や /commit のような副作用のあるSkillから disable-model-invocation: true が抜けていると、Claudeが「コードが完成したからデプロイしよう」のように自己判断で発動してしまうことがあります。実行タイミングを人間が握りたいSkillには例外なくこのフラグを付ける運用を徹底します。

つまずき8: descriptionを広く書きすぎて意図せず発動する

つまずき1とは逆に、description を広く書きすぎると無関係な文脈でも一致していると判定され、意図しないタイミングで発動して別の作業を妨げます。トリガーフレーズは具体的な言い回しに絞り、当てはまらせたくない文脈は disable-model-invocation や paths で境界を明示します。

つまずき9: CLAUDE.mdとSkillに同じ知識を重複させる

同じルール(たとえば「コミットメッセージは日本語で書く」)をCLAUDE.mdと /commit のSkill本文の両方に書くと、どちらか一方だけを更新したときに矛盾が生まれます。加えて、Skill本文の指示が古くなったまま放置されると、呼び出すたびに古い手順を強化し続けることになります。常時効く前提はCLAUDE.mdに一本化し、Skill側はCLAUDE.mdへのリンクで参照する形に倒すと、矛盾と陳腐化の両方を避けられます。

よくある質問

Claude Code Skillsとカスタムスラッシュコマンドの違いは?

両者は同じ仕組みに統合されており、どちらも /名前 のコマンドを作ります。Skills形式の利点は、補助ファイル用のディレクトリを持てること、起動主体をfrontmatterで制御できること、Claudeが文脈から自動ロードできることの3点です。

SKILL.mdに必須のfrontmatterフィールドはありますか?

ありません。全フィールドが任意で、frontmatterなしでも動きます。推奨されるのは description のみで、省略すると本文の最初の段落が説明として使われます。

Skillが自動起動しないときは何を確認すればよいですか?

確認順は4つです。①description にユーザーが自然に言いそうなキーワードが入っているか、②Claudeに「What skills are available?」と聞いてSkillが認識されているか、③/doctor で説明文の予算超過(切り詰め)が起きていないか、④disable-model-invocation: true が付いていないか。直接 /skill-name で起動できるなら、配置とファイル自体は正常です。

Skillsをチームや組織に配布するには?

プロジェクトの .claude/skills/ をバージョン管理にコミットする方法、プラグインの skills/ ディレクトリに同梱する方法、管理者設定(managed settings)で組織全体に配布する方法の3つがあります。プラグイン経由のSkillは名前空間が付くため、既存Skillと名前が衝突しません。

Skill実行中だけモデルや思考量を変えられますか?

frontmatterの model と effort で指定できます。model の上書きはそのターンの間だけ有効で、次のプロンプトからセッションのモデルに戻ります。effort は low〜max からセッション設定を上書きします(指定できるレベルはモデルに依存)。

まとめ

Claude Code SkillsはSKILL.mdファイル1つで成立する最小の拡張単位で、カスタムスラッシュコマンドを吸収した現在は「手動コマンド」から「自動起動する知識パック」までを1つの仕組みでカバーします。設計判断の軸は次の3つです。

1. 常駐するルールはCLAUDE.md、呼ばれたときだけはSkill
2. 外部システム連携はMCP、Claude内の手順はSkill
3. 独立コンテキストが要る作業は context: fork、軽い手順はインライン

最初の1本は「コミットメッセージを書く」「変更差分を要約する」のような短い手順書から始めて、引数・動的コンテキスト注入・context: fork へ段階的に広げていく形が運用として安定しやすいでしょう。