Claude Code Skills作成ガイド｜SKILL.md入門【2026】

Claude Code を使い込むと、「このリポジトリの API はこういう規約で書いて」「リリース前にこのチェックリストを順番に実行して」みたいな指示を、毎回ほぼ同じ文面で打ち込んでいることに気づきます。私も最初はその手の手順書をメモアプリに溜めておいて、必要なときに貼り付けていました。動くことは動くんですが、チームに共有できないし、CLAUDE.md に全部書くと「いつも読み込まれる固定コスト」になってコンテキストを圧迫する。正直、ここが地味に悩ましかった。

そこで使うのが Skills（スキル）です。Claude Code 公式ドキュメントは「同じ指示・チェックリスト・複数ステップの手順をチャットに貼り続けているとき、あるいは CLAUDE.md の一節が『事実』ではなく『手順』に育ってしまったとき」がスキルの出番だと明言しています。CLAUDE.md と決定的に違うのは、スキルの本文は使われたときだけ読み込まれる点です。だから長い参照資料を抱えても、呼び出すまではコストがほぼゼロ。この記事では、現行版（2026 年 6 月時点）の仕様を公式ドキュメントで裏取りしながら、実際に動く SKILL.md を例ベースで作っていきます。

Claude Code Skills とは何か（CLAUDE.md・コマンドとの違い）

まず立ち位置を整理します。Claude Code には「Claude に何かを覚えさせる/させる」手段がいくつかあり、用途で使い分けます。

仕組み	読み込みタイミング	向いている用途
CLAUDE.md	常時（毎ターン文脈に乗る）	変わらない事実・前提（技術スタック、命名規約の根幹など）
Skills（SKILL.md）	オンデマンド（呼び出し時のみ）	手順・チェックリスト・専門知識・定型作業
カスタムコマンド	呼び出し時のみ	1 枚で完結する定型コマンド（※現在は Skills に統合）

公式ドキュメントの表現を借りると、スキルは「SKILL.md ファイルを作ると Claude がそれを自分の道具箱に加える」もので、「関連するときに Claude が使うか、/skill-name で直接起動する」ものです。ポイントは オンデマンド読み込み。CLAUDE.md の内容は毎ターン文脈に乗りますが、スキルの本文は使われるまで読み込まれません。だから「滅多に使わないが長い手順書」はスキルにしておくのが正解で、これが CLAUDE.md との最大の違いです。

そしてもう 1 つ、2026 年版の重要な変更点。公式ドキュメントには次のように明記されています。

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working.
（出典：Claude Code 公式ドキュメント「Extend Claude with skills」）

つまり カスタムコマンドは Skills という仕組みに統合されましたが、従来の .claude/commands/*.md 方式は引き続き有効で、同じ frontmatter をサポートします。「これまで commands で書いてきたものを今すぐ書き直す必要はない」というのが結論です。スキル方式（SKILL.md + 専用ディレクトリ）は補助ファイルを同梱できたり、Claude が自動で読み込めたりといった追加機能があるため、複雑なものはスキル、1 枚で済む定型コマンドは .claude/commands/、という使い分けになります。なお Claude Code のスキルは Agent Skills というオープン標準に準拠しており、Claude Code はこれに呼び出し制御・サブエージェント実行・動的コンテキスト注入といった拡張を加えている、という位置づけです。

/SKILL.md は frontmatter（name/description）＋本文（手順・知識）＋補助ファイルで構成され、関連する時だけ読み込まれる（CLAUDE.mdは常時・スキルは必要時）。”>

SKILL.md の書き方（frontmatter と本文）

スキルの最小単位は「ディレクトリ + SKILL.md」です。SKILL.md は 2 つのパートでできています。1 つは --- で囲んだ YAML frontmatter（このスキルが何で、いつ使うかを Claude に伝える）、もう 1 つは 本文の Markdown（スキルが起動したときに Claude が従う指示）です。ディレクトリ名がそのまま入力するコマンド名になり、description が「いつ自動で読み込むか」の判断材料になります。

まずは公式の最小例。「未コミットの変更を要約してリスクを指摘する」スキルです。~/.claude/skills/summarize-changes/SKILL.md に保存します。

---
description: 未コミットの変更を要約し、危なそうな点を指摘する。何が変わったか聞かれたとき、コミットメッセージが欲しいとき、diffをレビューしたいときに使う。
---

## 現在の変更

!`git diff HEAD`

## 指示

上の変更を2〜3個の箇条書きで要約し、続けて気づいたリスク（エラーハンドリング漏れ・ハードコードされた値・更新が必要なテストなど）を列挙してください。diffが空なら「未コミットの変更はありません」と返します。

description しか frontmatter に書いていない点に注目してください。公式仕様では frontmatter のフィールドはすべて任意で、推奨されているのは description だけです。本文に出てくる !`git diff HEAD` は動的コンテキスト注入の記法で、Claude が本文を読む前に Claude Code 側がそのコマンドを実行し、出力でこの行を置き換えます。つまり Claude は「git diff を実行して」という指示ではなく、実際の差分テキストそのものを受け取ります。これにより、開いているファイルから推測するのではなく、実際の作業ツリーに基づいた応答になります。

本文には何を書いてもよいのですが、内容は大きく 2 タイプに分けて考えると整理しやすいです。

• リファレンス型：規約・パターン・スタイルガイド・ドメイン知識など、Claude が今の作業に適用する知識。会話のコンテキストと並んでインラインで効く（例：「この API はこう書く」）
• タスク型：デプロイ・コミット・コード生成など、特定のアクションの手順書。/skill-name で自分から起動したいことが多く、Claude に勝手に実行されたくない場合は disable-model-invocation: true を付ける

本文を書くときの鉄則は 簡潔に保つこと。公式ドキュメントによれば、いったんスキルが読み込まれるとその内容はそのセッションの間ずっとコンテキストに残り続ける（毎ターン再読込はされない）ため、1 行ごとが繰り返しのトークンコストになります。「なぜ・どうやって」を長々と説明するより「何をするか」を述べる――CLAUDE.md と同じ簡潔さの基準を当てはめます。本文が長くなりそうなら、後述の補助ファイルに切り出すのが定石です（公式の目安は SKILL.md を 500 行以内に）。

主な frontmatter キー（2026 年 6 月時点）

本文の前に置く YAML で、スキルの挙動を細かく制御できます。よく使うキーは次のとおりです（すべて任意。description のみ推奨）。

キー	役割
name	スキル一覧での表示名。省略時はディレクトリ名。入力するコマンド名はディレクトリ名で決まり、name では基本変わらない
description	何をする/いつ使うスキルか。Claude が自動起動の判断に使う。最重要キー。省略時は本文の最初の段落が使われる
when_to_use	起動トリガーとなる言い回しや例。description に追記される形で一覧に出る
argument-hint	オートコンプリート時に表示する引数ヒント（例：[issue-number]）
arguments	$name 置換用の名前付き位置引数。スペース区切り文字列か YAML リスト
disable-model-invocation	true で Claude による自動起動を禁止。手動 /name 専用にしたいワークフロー向け（デプロイ等）
user-invocable	false で / メニューから隠す。ユーザーが直接叩く意味のない背景知識向け
allowed-tools	このスキルが有効な間、許可なしで使えるツール。スペース/カンマ区切りか YAML リスト
model / effort	このスキルが有効な間に使うモデル/Effort レベルを上書き（その手番のみ。設定には保存されない）
context / agent	context: fork でサブエージェントの分離コンテキストで実行。agent でその種類を指定
paths	glob パターンで、該当ファイルを扱うときだけ自動起動するよう限定

引数を受け取りたいときは本文で $ARGUMENTS（全引数）や $ARGUMENTS[0]・$0（0 始まりの位置引数）を使います。たとえば Fix GitHub issue $ARGUMENTS ... と書いておけば、/fix-issue 123 の実行時に $ARGUMENTS が 123 に置き換わります。スキルに $ARGUMENTS が無い状態で引数付き起動すると、Claude Code が本文末尾に ARGUMENTS: <入力> を追記するので、入力自体は必ず Claude に届きます。

スキルの配置（プロジェクトと個人、その読み込みスコープ）

スキルをどこに置くかで「誰が使えるか」が決まります。公式の対応表は次のとおりです。

場所	パス	適用範囲
個人	~/.claude/skills/<skill-name>/SKILL.md	自分の全プロジェクト
プロジェクト	.claude/skills/<skill-name>/SKILL.md	そのプロジェクトのみ（コミットで共有）
エンタープライズ	managed settings 参照	組織内の全ユーザー
プラグイン	<plugin>/skills/<skill-name>/SKILL.md	プラグイン有効時

名前が衝突した場合の優先順位は、公式の表現で「enterprise が personal を、personal が project を上書きする」です（プラグインスキルは plugin-name:skill-name の名前空間を持つので衝突しません）。また、.claude/commands/ にあるファイルも同じように動きますが、スキルとコマンドが同名ならスキルが優先されます。チームで配布したいスキルはプロジェクトの .claude/skills/ に置いてコミットする、というのが基本運用です。

ディレクトリ構成は、SKILL.md をエントリポイントに、必要なら補助ファイルを並べる形です。

.claude/
└── skills/
    └── release-checklist/
        ├── SKILL.md          # メイン手順（必須・/release-checklist で起動）
        ├── reference.md      # 詳細なリリース基準（必要時のみ読み込み）
        └── scripts/
            └── check.sh      # Claudeが実行するスクリプト

実用上の注意点も押さえておきます。Claude Code はスキルディレクトリのファイル変更を監視していて、~/.claude/skills/ やプロジェクトの .claude/skills/ 配下の スキルの追加・編集・削除はセッション中に再起動なしで反映されます（公式の Live change detection）。ただし、セッション開始時に存在しなかった「トップレベルの skills ディレクトリ自体」を新規作成した場合だけは、監視対象に入れるため Claude Code の再起動が必要です。最初の 1 個を作るときは、ディレクトリを作った直後に一度 Claude Code を立ち上げ直すと確実です。

呼び出し制御（自分が呼ぶ／Claude が自動で使う）

デフォルトでは、あなたも Claude もどちらもスキルを起動できます。/skill-name と打てば自分で直接起動できますし、会話の内容が description に合致すれば Claude が自動でそのスキルを読み込みます。この 2 方向を、frontmatter の 2 つのフィールドで制限できます。

• disable-model-invocation: true：あなただけが起動できる。/commit / /deploy / /send-slack-message のように、副作用があったりタイミングを自分で握りたいワークフローに使う。「コードが完成して見えるから」と Claude に勝手にデプロイされては困るからです
• user-invocable: false：Claude だけが起動できる。legacy-system-context のような「古いシステムの仕組みを説明する背景知識」向け。Claude は必要なときに知っておくべきだが、ユーザーが /legacy-system-context と叩く意味はないからです

この 2 フィールドが「誰が起動できるか」と「いつコンテキストに読み込まれるか」にどう効くかを、公式の表でまとめます。

frontmatter	自分で起動	Claude が起動	コンテキストへの読み込み
（デフォルト）	可	可	description は常時／本文は起動時に読み込み
disable-model-invocation: true	可	不可	description は文脈に乗らない／本文は自分が起動したとき読み込み
user-invocable: false	不可	可	description は常時／本文は起動時に読み込み

つまり通常セッションでは、スキルの description だけが常にコンテキストに載っていて（Claude が「何が使えるか」を把握するため）、本文は起動されて初めて読み込まれます。これがオンデマンド読み込みの実体です。なお Claude が思ったように起動してくれないときは、description にユーザーが自然に言いそうなキーワードを含めるのが効きます。逆に起動しすぎるなら description をより具体的にするか、disable-model-invocation: true で手動専用にします。

もう 1 つ実務で効くのが allowed-tools です。これは「このスキルが有効な間、列挙したツールを許可確認なしで使ってよい」という事前承認で、ツールを制限するものではありません（許可リストに無いツールは通常どおりあなたの permission 設定に従います）。たとえばコミット用スキルなら次のように書いておくと、起動するたびに git コマンドの承認を求められずに済みます。

---
name: commit
description: 現在の変更をステージしてコミットする
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

現在の変更をConventional Commits形式でコミットしてください。
1. `git status` で変更を確認
2. 関連する変更をステージ
3. 適切な型（feat/fix/docs等）でコミットメッセージを作成

ただしプロジェクトの .claude/skills/ に入れたスキルの allowed-tools は、そのフォルダのworkspace trust（信頼）ダイアログを承認してから有効になります。スキルは自分自身に広いツール権限を与えられるので、知らないリポジトリを信頼する前にプロジェクトスキルの中身は必ず確認してください。

サブエージェント実行と補助ファイルの同梱

スキルを分離したコンテキスト（サブエージェント）で走らせたいときは、frontmatter に context: fork を付けます。スキルの本文がそのままサブエージェントを駆動するプロンプトになり、メイン会話の履歴にはアクセスしません。重い調査やコード生成を本流のコンテキストから切り離せるので、トークン管理の面で効きます。

公式の例は、リサーチを Explore エージェントで走らせるスキルです。

---
name: deep-research
description: トピックを徹底的に調査する
context: fork
agent: Explore
---

$ARGUMENTS について徹底的に調査してください。

1. Glob と Grep で関連ファイルを探す
2. コードを読んで分析する
3. 具体的なファイル参照付きで所見をまとめる

このスキルを起動すると、(1) 新しい分離コンテキストが作られ、(2) サブエージェントが本文をプロンプトとして受け取り、(3) agent フィールドが実行環境（モデル・ツール・権限）を決め、(4) 結果が要約されてメイン会話に返ります。agent には Explore / Plan / general-purpose といった組み込みエージェントや、.claude/agents/ の自作サブエージェントを指定できます（省略時は general-purpose）。注意点として、context: fork は「実行すべきタスク」が明示されたスキル向けです。「この API 規約を使って」のような指針だけのスキルを fork するとサブエージェントが動かす対象を持たないので、リファレンス型はインラインのまま使うのが正解です。

最後に補助ファイルの同梱。スキルはディレクトリに複数ファイルを含められるので、SKILL.md を要点に絞り、詳細な参照資料は別ファイルに逃がせます。大きな API 仕様や例集を毎回コンテキストに載せずに済むのが利点です。

my-skill/
├── SKILL.md       # 必須・概要とナビゲーション
├── reference.md   # 詳細なAPIドキュメント（必要時のみ読み込み）
├── examples.md    # 使用例（必要時のみ読み込み）
└── scripts/
    └── helper.py  # ユーティリティ（実行されるだけで読み込まれない）

補助ファイルは、SKILL.md から「何が書いてあって、いつ読むべきか」を参照しておくのがコツです。こう書いておけば、Claude は中身を読む必要が出たときだけ該当ファイルを開きます。

## 追加リソース

- API の詳細は [reference.md](reference.md) を参照
- 使用例は [examples.md](examples.md) を参照

スクリプトを同梱して実行させる場合、本文では ${CLAUDE_SKILL_DIR}（その SKILL.md があるディレクトリ）を使ってパスを書くと、個人・プロジェクト・プラグインのどこにインストールされても正しく解決されます。たとえば python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py . のように書けば、カレントディレクトリに依存せず同梱スクリプトを呼べます。重い処理はスクリプトに任せ、Claude はオーケストレーションに専念する――これが「単一プロンプトを超える」スキルの基本パターンです。

最初の 1 個を作る手順とハマりどころ

ここまでの内容を踏まえて、実際に手を動かす最短手順をまとめます。個人スキル（全プロジェクトで使える）として「リリース前チェックリスト」を作る想定です。

1. 個人スキル用ディレクトリを作る：mkdir -p ~/.claude/skills/release-checklist
2. ~/.claude/skills/release-checklist/SKILL.md を新規作成する
3. 先頭に --- で囲んだ frontmatter を書き、description に「いつ使うか」をユーザーが言いそうな言葉で記述する
4. 本文に、Claude に踏ませたいチェック手順を Markdown の番号付きリストで書く
5. 必要なら !`git log --oneline -10` のように動的コンテキスト注入で直近のコミットを差し込む
6. ファイルを保存する（既存セッションなら変更は再起動なしで反映。トップレベルの skills ディレクトリを新規作成した場合だけ Claude Code を起動し直す）
7. claude を起動し、/ を入力して /release-checklist が一覧に出ることを確認する
8. /release-checklist を実行し、想定どおり手順が走るか確認する。出なければ 「どんなスキルが使える?」と聞いて登録状況を確認する

つまずきやすいポイントを 3 つ、失敗例と正しい形で示しておきます。

• ❌ SKILL.md にだらだら背景を書く：本文はセッション中ずっとコンテキストに残るので、長文は毎ターンのトークンコストになる。⭕ 要点は SKILL.md に、詳細は reference.md 等の補助ファイルへ逃がす（目安 500 行以内）
• ❌ デプロイ系スキルに description だけ書いて放置：Claude が「準備できてそう」と判断して自動起動するリスクがある。⭕ 副作用のあるスキルには disable-model-invocation: true を付けて手動専用にする
• ❌ frontmatter の name でコマンド名を変えようとする：入力するコマンド名はディレクトリ名で決まる（name は一覧の表示名）。⭕ /deploy-staging にしたければディレクトリ名を deploy-staging にする

「自分が繰り返している手順をスキルにする」――これだけで、毎回のコピペが /コマンド 一発になり、チームにもコミットで配れます。まずは普段いちばん貼り付けている指示文を 1 つ、SKILL.md に移してみてください。

Skills を起点に Claude Code 運用を仕組み化する

スキルは単体でも便利ですが、Claude Code の他の仕組みと組み合わせると効きます。CLAUDE.md は「変わらない事実」を、Skills は「手順・専門知識」を担当し、カスタムコマンドは 1 枚で済む定型作業を引き受ける――この役割分担を意識すると、コンテキストを無駄に膨らませずに運用を仕組み化できます。各テーマの実装ガイドは以下も参考にしてください。

• Claude Code カスタムスラッシュコマンド作成ガイド（Skills に統合された .claude/commands/ 方式の詳解）
• CLAUDE.md 設計・運用ガイド（「事実」を CLAUDE.md、「手順」を Skills に振り分ける判断軸）
• Claude Code サブエージェント並列開発入門（context: fork でスキルをサブエージェント実行する応用）
• Claude Code 業務導入完全ガイド（チームでスキルを配布・標準化する全体像）

FAQ

Q. Skills と CLAUDE.md、どちらに書くべき?
変わらない「事実」（技術スタック、命名規約の根幹）は CLAUDE.md、繰り返す「手順」やチェックリスト・専門知識は Skills です。CLAUDE.md の一節が事実ではなく手順に育ってきたら、スキルに切り出すサイン。スキル本文は呼び出し時しか読み込まれないので、長い参照資料を持ってもコストになりません。

Q. これまで作った .claude/commands/ は捨てる必要がある?
ありません。カスタムコマンドは Skills に統合されましたが、既存の .claude/commands/*.md はそのまま動作し、同じ frontmatter をサポートします。補助ファイルの同梱や自動ロードが欲しくなったらスキルへ移行する、で十分です。

Q. スキルを Claude に勝手に使われたくない。
frontmatter に disable-model-invocation: true を付けると、あなたが /name で起動したときだけ動き、Claude による自動起動を止められます。逆に / メニューから隠して背景知識として Claude にだけ使わせたいなら user-invocable: false を使います。

Q. チームで共有するには?
プロジェクトの .claude/skills/ に置いてバージョン管理にコミットすれば、リポジトリを開いた全員が同じスキルを使えます。組織全体に配るなら managed settings（エンタープライズ）、他の拡張とまとめて配布するならプラグインの skills/ ディレクトリという選択肢もあります。

まとめ

Claude Code の Skills は、「毎回コピペしている手順書」を SKILL.md 1 ファイルに移すだけで作れます。CLAUDE.md と違って本文はオンデマンド読み込みなので、長い手順や専門知識を抱えてもコンテキストを圧迫しません。description を丁寧に書けば Claude が自動で使い、/skill-name で自分からも呼べる。disable-model-invocation や allowed-tools、context: fork、補助ファイルの同梱まで使いこなせば、個人の作業効率化からチームの運用標準化まで一気に広がります。

今日のアクション

1. いちばん頻繁に貼り付けている指示文を 1 つ選び、~/.claude/skills/<name>/SKILL.md に description + 手順として書き写す
2. /skill-name で起動できることを確認し、副作用のあるものには disable-model-invocation: true を付ける
3. チームで使うものはプロジェクトの .claude/skills/ に移してコミットし、全員で共有する

Uravation では、Claude Code を業務で使いこなすための個別指導・導入支援を行っています。スキルやサブエージェントを含む実践的なワークフロー設計に関心がある方は、業務導入完全ガイドもあわせてご覧ください。

---

著者：佐藤傑（さとう・すぐる）。株式会社Uravation 代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。

出典

• Claude Code 公式ドキュメント「Extend Claude with skills」（SKILL.md・frontmatter・呼び出し制御・補助ファイル・サブエージェント実行の一次情報。2026年6月時点）
• Claude Code 公式ドキュメント「Subagents」（context: fork とサブエージェントへのスキル事前読み込みの仕様）
• Claude Code 公式ドキュメント「Commands」（組み込みコマンドとバンドルスキルの一覧・位置づけ）
• Agent Skills（オープン標準）（Claude Code のスキルが準拠する標準仕様）

関連記事（Claude Code 実践ガイド）

• まとめ：Claude Code 実践テクニック完全ガイド（12スキル）
• Plan Mode実践ガイド｜安全に大きな変更を進める
• レガシーコード移行・大規模リファクタ実践ガイド
• Agent Teams｜複数AIで協調開発
• プラグイン活用ガイド｜マーケットプレイス

あわせて読みたい

• ▸ 【2026年7月】Claude 5コンテキスト新ルール×CLAUDE.md実践
• ▸ 【2026年】Claude Opus 5をClaude Codeで使う移行実務
• ▸ AIソフトウェア工場はなぜ失敗するか｜Claude Code並列運用の3つの律速
• ▸ 【2026年最新】Claude Codeのシークレット管理｜秘密情報を守る7原則
• ▸ 【2026年最新】Claude Code×Kubernetes運用術｜実践7選