Claude Code Skills入門｜SKILL.mdの書き方
Claude Code Skills とは
Claude Code Skills は、エージェントに 再利用可能な手順・チェックリスト・ドメイン知識 を渡すための拡張機構です。各 Skill はディレクトリ内の SKILL.md をエントリポイントとし、YAML frontmatter の description と本文の Markdown 指示で Claude の振る舞いを定義します。チャットに毎回同じ長文を貼る代わりに /skill-name で明示呼び出ししたり、説明文に合致する依頼で 自動ロード させたりできます。
公式 Extend Claude with skills によると、Skills は Agent Skills オープン標準 に準拠しつつ、Claude Code では invocation 制御・サブエージェント実行・動的コンテキスト注入 などを追加しています。また custom commands は Skills に統合 され、.claude/commands/deploy.md も .claude/skills/deploy/SKILL.md も同じ /deploy として動作します（Skill 側が同名時に優先）。
本記事は SKILL.md の書き方と配置ルールに焦点を当てます。リポジトリ内の具体的な Skill 中身の転載は行いません。MCP や隠し機能との組み合わせは関連記事を参照してください。
前提環境
| 項目 | 内容 |
|---|---|
| Claude Code | 最新版推奨（bundled skills の一部は v2.1.145+ 等の下限あり） |
| 配置場所 | ~/.claude/skills/（personal）または .claude/skills/（project） |
| ファイル | 各 Skill は ディレクトリ + SKILL.md（単一ファイルだけでは不可） |
| 旧 commands | .claude/commands/ は引き続き動作（移行期間中） |
Skills の変更は、セッション中の ~/.claude/skills/ やプロジェクト .claude/skills/ については 再起動なしで反映 される（live change detection）一方、プラグインとして hooks 等を含む Skill フォルダでは /reload-plugins が必要な場合があります（公式ドキュメント記載）。
SKILL.md の最小構成
ディレクトリ名 = コマンド名
mkdir -p ~/.claude/skills/summarize-changes
上記例では /summarize-changes として呼び出せます。
frontmatter と本文
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.
description は最重要フィールド です。Claude が Skill を 自動選択 するかどうかは、ここに書いた用途説明に大きく依存します。曖昧な「便利ツール」より、「未コミット diff の要約とリスク指摘」など トリガー条件を英語で具体的に 書くのが公式の推奨パターンです。
/skill-name による明示呼び出し
プロンプトまたは Claude Code の入力欄で / を入力するとコマンドメニューが開き、登録済み Skill が一覧されます。直接タイプする例:
/summarize-changes
bundled skills として /doctor、/code-review、/debug、/loop 等が同梱されています（commands reference で Skill 列付き一覧）。/verify や /code-review は v2.1.215 以降 ユーザー明示呼び出しのみ になる等、バージョンで挙動が変わる Skill もあるため、claude --version または /status で確認してください。
配置場所：personal / project / plugin
| レベル | パス | 適用範囲 |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | 自分の全プロジェクト |
| Project | .claude/skills/<name>/SKILL.md | そのリポジトリのみ |
| Enterprise | 管理設定による | 組織全体 |
| Plugin | <plugin>/skills/<name>/SKILL.md | プラグイン有効範囲 |
同名 Skill が複数レベルにある場合、enterprise > personal > project の優先順位で上書きします。プロジェクト Skill は bundled skill と同名ならプロジェクト側が優先（例: 自作 code-review が bundled /code-review を置き換え）。
モノレポでは ネストした .claude/skills/ もサポートされます。packages/frontend/.claude/skills/ に置いた Skill は、そのパッケージ配下のファイル作業時に apps/web:deploy のような qualified name で利用可能（v2.1.203+）。ルートの /deploy とネスト Skill の使い分けは公式の monorepo 節を参照してください。
commands から skills への統合
以前の .claude/commands/*.md は引き続き動作しますが、新規作成は Skills 形式を推奨 します。Skill の方が次を追加できます。
- supporting files（
scripts/、references/、template.md等） - frontmatter による 自動 / 手動 invocation 制御
- 動的注入（行頭の
!+ コマンドをバッククォートで囲む記法）
移行例: .claude/commands/deploy.md → .claude/skills/deploy/SKILL.md に同内容を移し、必要なら scripts/deploy.sh を同ディレクトリに置く。
動的コンテキスト注入
SKILL.md 本文では、次のように 行頭の ! の直後に、バッククォートで囲んだシェルコマンド を書けます。Skill ロード時にそのコマンドが実行され、出力で行が置換されます。上記 git diff HEAD 例では、Skill 本文が届く前に 実際の diff がインライン化されるため、Claude は推測ではなく 実行結果に基づいて 要約できます。
!`git diff HEAD`
---
description: Show CI status for the current branch.
---
## Latest CI
!`gh run list --branch $(git branch --show-current) --limit 5`
注意: 注入コマンドは Skill 利用のたびに実行されます。重い処理や秘密情報を stdout に出すコマンドは避け、必要なら .env ではなく Credential Manager 等の安全な経路を検討してください（プロジェクトの秘密情報ルールに従う）。
scripts / references ディレクトリ
Skill フォルダの典型構造（公式例）:
my-skill/
├── SKILL.md # 必須エントリポイント
├── template.md # Claude が埋めるテンプレート
├── references/
│ └── api-notes.md # 参照ドキュメント（必要時のみ読み込み）
└── scripts/
└── validate.sh # Skill 手順から呼ぶ補助スクリプト
SKILL.md 本文から「scripts/validate.sh を実行して結果を確認せよ」と指示することで、手順と実行物を同梱 できます。長大な API 仕様は references に分離し、Skill 本文は いつ・何をするか に集中させると token 効率が良くなります。
いつ Skill 化すべきか
公式が Skill 作成を勧める典型パターン:
- 同じ指示をチャットに何度も貼っている
- CLAUDE.md の一節が手順書化 して肥大化している（事実より手順は Skill 向き）
- プロジェクト固有のチェックリスト（PR 前レビュー、リリース手順、コーディング規約の適用確認）
- 動的データが必要（diff、CI 結果、バージョン番号）→ 動的注入記法が有効
- チームで共有したい手順 →
.claude/skills/をリポジトリにコミット
逆に Skill 化が過剰な例:
- 1行で済むエイリアス的指示
- すでに bundled
/code-reviewで足りる汎用レビュー（上書き目的がなければ不要） - 毎回全く異なる ad hoc 依頼
CLAUDE.md は「常に効く事実・方針」、Skill は「必要なときだけ読む手順」 と役割分担するのが公式の設計思想です。Skill 本文は利用時まで読み込まれないため、長文参考資料を CLAUDE.md に置くより Skill + references の方がセッション全体のコンテキストを圧迫しにくい、と説明されています。
bundled skills との関係
同梱 Skill（/run、/verify、/run-skill-generator 等）は プロジェクトの起動方法を学習 する用途で連携します。/run-skill-generator を一度走らせると .claude/skills/run-<project>/ にレシピが記録され、以降 /run や /verify が README 推測ではなく 記録済み手順 に従う、という流れです（v2.1.145+）。
disableBundledSkills 設定で bundled をまとめて無効化できますが、/doctor は v2.1.205+ では例外的に残る等、例外があるため設定前に skills ドキュメント を確認してください。
作成・テストの実践フロー
- 用途を1文で定義（誰が・いつ・何のために使うか）
descriptionを英語で具体化（自動 invocation の精度が上がる）- SKILL.md + 必要な scripts/references を配置
/skill-nameで明示テスト → 続けて description に合う自然言語依頼で 自動ロード を確認- チーム共有なら PR で
.claude/skills/をレビュー
テスト例:
What did I change?
/review-staged
よくあるつまずき
| 症状 | 原因 | 対処 |
|---|---|---|
/my-skill が出ない | ディレクトリ名と SKILL.md 欠落 | skills/my-skill/SKILL.md 構造を確認 |
| 自動で使われない | description が曖昧 | トリガー条件を具体化 |
| 動的注入の出力が空 | コマンド失敗・cwd 不一致 | リポジトリルートで手動実行して確認 |
| 変更が反映されない | 新規 top-level skills dir | セッション再起動（公式の live detection 例外） |
| commands と競合 | 同名 Skill 優先 | 意図的なら Skill に一本化 |
FAQ
Q. SKILL.md だけの単一ファイル配置はできますか。
いいえ。公式構造は <name>/SKILL.md です。ディレクトリ名が /name になります。
Q. 日本語の description でもよいですか。 動作はしますが、公式サンプルは英語 description です。自動 invocation の精度を優先するなら英語推奨です。
Q. personal と project、どちらに置くべきですか。
個人の好みの手順は ~/.claude/skills/、チーム共有の手順は .claude/skills/ をリポジトリにコミットします。
Q. MCP サーバーと Skill の違いは何ですか。 MCP は 外部ツール・データ接続（ブラウザ、Figma、DB 等）。Skill は Claude への手順・プロンプト拡張 です。併用が一般的です（MCP 入門）。
Q. 既存の .claude/commands/ はすぐ移行必須ですか。
必須ではありません。公式は「commands は引き続き動作、新規は skills 推奨」としています。
Q. リポジトリの Skill 中身を記事に載せてよいですか。 プロジェクト固有の Skill はライセンス・秘密情報に注意。本記事は一般パターンのみ扱い、具体 Skill の転載はしません。
関連記事
Skill 仕様の正本は code.claude.com/docs/en/skills です。bundled skills のバージョン要件はリリースノートとセットで確認してください。
関連サービス
最終確認日: 2026-07-23