Claude Code Skill 実践ガイド｜作成・チーム配布・安全運用【2026】

「Claude Code を使っていて、毎回同じ指示を繰り返していませんか？」コードレビューの手順、テストの実行方法、コミットメッセージのルール——プロジェクトごとに決まったワークフローがあるのに、毎回口頭で説明するのは非効率です。Claude Code Skills を使えば、こうした定型ワークフローを /skill-name の一言で実行できます。

筆者自身も複数の Skills を作成・運用中で、月100回程度のレビュー依頼が毎回5秒で片付くようになりました。大げさな時間短縮というより、「毎回同じ長文プロンプトを入力する煩雑さから解放される」感覚に近いです。GitHub 経由でチームに配れば、メンバーが各自カスタマイズして育ててくれるエコシステムが生まれます。普段エンジニアではない業務メンバーに Skill を紹介すると、決まって「こんなに強力な機能があるのか」と驚かれるほどの破壊力を持っています。書き方で迷ったら AI に下書きさせて最終確認を人が行うのが、筆者のおすすめフローです。

この記事では、公式ガイドやコミュニティ記事ではまだ整理されていない観点を含めて解説します: Custom Commands からの移行判断・CLAUDE.md との使い分け・Cursor / Windsurf のルールファイルとの比較・2026年2月に公開されたセキュリティ研究者の PoC・SDK 経由で allowed-tools が効かない既知 Issue など、運用で実際に踏む論点を筆者の実体験ベースで整理しました。ちなみに公式リポジトリ anthropics/skills は 2026年4月時点で 113,000 スターを超えており、Skills エコシステムは急拡大しています。

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

Skills の基本概念

Claude Code Skills は、Claude Code に「やり方」を教えるための仕組みです。プロジェクト内の .claude/skills/<skill-name>/SKILL.md にマークダウンで手順を記述するだけで、再利用可能なワークフローを定義できます。

ユーザーは /skill-name で手動呼び出しできるほか、Claude がタスク内容を分析して自動的に関連する Skill を読み込むこともできます。起動時にはフロントマター（名前・説明）だけが読み込まれ、実際に必要になった段階で本文が展開される「プログレッシブディスクロージャー」方式を採用しています。これにより、大量の Skill を登録してもコンテキストウィンドウを圧迫しません。

Kitchen Analogy — MCP は厨房、Skills はレシピ

Skills の本質を理解するのに便利な例えが「Kitchen Analogy」です。MCP（Model Context Protocol）が厨房（包丁・鍋・食材などのツール）を提供するのに対し、Skills はレシピ（手順書）を提供します。MCP で使える道具が揃っていても、どう組み合わせて料理するかはレシピ次第です。公式ガイドも「MCP は Claude に何ができるかを定義し、Skills は Claude にどうやるかを教える」と説明しています。

プログレッシブディスクロージャー — 3段階ロードの実態

Skills の設計を一言で表すなら「プログレッシブディスクロージャー（段階的開示）」です。すべての Skill の本文を最初からロードするとコンテキストウィンドウが即座に溢れますが、Skills は3段階に分けて必要なものだけを読み込みます。

※「Level 1 が約100トークン」という数値は公式ガイドに厳密な明記があるわけではなく、description の長さに応じた実測ベースの目安です。また、Subagent の preloaded skills は例外で、起動時に SKILL.md 本文がまるごと注入されます。通常セッションでは「description のみ常時ロード、本文は invoke 時」と理解しておけば運用上は十分です。

ディレクトリ構造 — 必須は SKILL.md だけ

Skill フォルダの標準構造は以下のとおりです。SKILL.md だけが必須で、他は任意です。

.claude/skills/review/
├── SKILL.md              # 必須: 手順書本体（YAMLフロントマター + Markdown）
├── scripts/              # 任意: 実行可能スクリプト（Python / Bash / Node など）
│   ├── lint.py
│   └── check-deps.sh
├── references/           # 任意: 追加ドキュメント（Claude が参照するだけ）
│   ├── style-guide.md
│   └── security-checklist.md
└── assets/               # 任意: テンプレート・フォント・画像など
    ├── report-template.html
    └── logo.svg

references/ のファイルは Claude が自動では読みません。SKILL.md 本文で「security-checklist.md を読んでから実行せよ」と明示する必要があります。scripts/ のスクリプトは Bash ツール経由で実行可能で、決定的な処理（ファイル変換・スキーマ検証など）を LLM に任せずスクリプトに任せることで結果の再現性が上がります。

設計原則 — Composability と Portability

公式ガイドは Skills の設計原則として以下の2つを挙げています。

• Composability（組み合わせ可能性）: 複数の Skill を同時ロードして協調動作させられます。「自分の Skill が他のすべての Skill を抑え込む」ような排他的設計は避け、他の Skill と共存する前提で書きましょう
• Portability（可搬性）: 同じ Skill が Claude.ai・Claude Code・Claude API で同一に動作します。一度書けば複数の実行環境で再利用可能です（環境依存のスクリプトを除く）

Skills vs MCP vs Subagents — 混同しがちな3者の違い

Skills は MCP や Subagents と混同されがちですが、役割は明確に異なります。

この3つは排他ではなく組み合わせ可能です。たとえば Sentry 社が公開している「sentry-code-review」は、Skill が PR レビューのワークフローを定義し、MCP が実際のエラーデータを Sentry から取得するという合わせ技で実現されています。

Skills vs Custom Commands — どちらを使うべき？

Claude Code には以前から Custom Commands（.claude/commands/）という仕組みがありました。Skills はその後継として登場し、より多機能な設計になっています。両者の違いを見てみましょう。

結論: 新規作成は Skills を使いましょう。既存の Custom Commands は移行不要です。互換性が維持されているため、動作に支障はありません。ただし、テンプレート同梱やモデル指定など Skills 固有の機能が必要になったら、そのタイミングで移行すれば十分です。

Skills の配置場所と優先度

Skills は3つのレベルに配置でき、それぞれスコープが異なります。

• プロジェクト: .claude/skills/ — Git リポジトリに含めてチーム全体に共有。プロジェクト固有のワークフローに最適
• グローバル: ~/.claude/skills/ — 個人のホームディレクトリに配置。すべてのプロジェクトで利用可能
• 組織（Enterprise）: 管理者がプロビジョニング — 全ユーザーに一括配布。個人では上書き不可

同名の Skill が複数のレベルに存在する場合、Enterprise > グローバル > プロジェクト の優先度で解決されます。

SKILL.md の書き方 — フロントマターと本文

基本構成

SKILL.md は YAML フロントマターと本文で構成されます。以下は最もシンプルなコードレビュー Skill の例です。

---
name: review
description: コードレビューを実行し、バグ・セキュリティ・パフォーマンスの問題を指摘する
user-invocable: true
allowed-tools: Read, Grep, Glob
---

## 手順
1. 変更されたファイルを特定する
2. 各ファイルについて以下を確認:
   - バグの可能性
   - セキュリティリスク
   - パフォーマンスの問題
3. 問題があれば修正案を提示する

このファイルを .claude/skills/review/SKILL.md に保存するだけで、/review コマンドが使えるようになります。

フロントマター全項目リファレンス

フロントマターで指定できるすべての項目を一覧にまとめました。

本文の書き方のコツ

SKILL.md の本文は Claude への行動指示書です。効果的な Skill を書くために、以下のポイントを押さえましょう。

• 500トークン以下に収める: 本文が長すぎるとコンテキストウィンドウを圧迫し、パフォーマンスが低下します。自動呼び出し用の Skill は 300トークン以下が理想です
• 手順は番号付きリストで明確に: Claude が「次に何をすべきか」を迷わないよう、ステップバイステップで記述します
• 曖昧な表現を避ける:「適切に処理する」ではなく「エラーの場合は stderr にメッセージを出力し、終了コード 1 で終了する」のように具体的に書きます
• 支援ファイルを活用する: テンプレート、サンプルコード、設定ファイルなどは SKILL.md と同じディレクトリに配置できます。本文から ./template.html のように参照可能です

自動呼び出し（Auto-Invocation）の仕組み

プログレッシブディスクロージャー

Claude Code は Skills を効率的に管理するために「プログレッシブディスクロージャー」方式を採用しています。すべての Skill の本文を最初からロードするのではなく、段階的に展開していきます。

1. 起動時: すべての Skill のフロントマター（name + description）だけをロード。Skill 1つあたり約100トークン程度のコスト
2. 会話中: ユーザーの指示を受けて、Claude が各 Skill の description を読んで関連性を評価
3. 関連ありと判断: SKILL.md の本文（手順部分）を全文ロードして実行

この仕組みにより、description の書き方が自動呼び出しの精度を大きく左右します。description は「この Skill が何をするか」を具体的かつ簡潔に記述しましょう。

自動呼び出しの制御

Skills の呼び出し方法は、フロントマターの設定で3パターンに制御できます。

特に disable-model-invocation: true は、デプロイやコミットなど副作用のある操作に重要です。Claude が勝手にデプロイを始めることを防ぎます。

description バジェットと注意点

Skills の description はコンテキストウィンドウの一部を占有します。この「description バジェット」には上限があり、注意が必要です。

• デフォルトバジェット: コンテキストウィンドウの約 1%（フォールバック: 8,000文字）
• 1件あたりの上限: 各 description は 250 文字で打ち切られるため、長文の description は後半が無視される
• 多数の Skill を登録すると: description バジェットを超過し、一部の Skill が読み込まれなくなる
• 対策: 環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 で上限を引き上げ可能

description は「pushy」に書く — Claude はデフォルトで発動しない

自動呼び出しを狙うなら、description の書き方が最も重要です。公式ガイドと Towards Data Science 誌の実装解説記事の両方が指摘する最重要ポイントは、Claude はデフォルトで Skill をトリガーしないという事実です。「この Skill を使ってほしい」と Claude に自然に認識させるには、description を「押しが強い（pushy）」文言にする必要があります。

name: data-helper
description: データ処理用のヘルパー

name: sales-data-analyzer
description: 売上CSVを受け取り、KPIツリー分解・優先度付きインサイト抽出・アクションプラン生成を行う。「売上分析」「レビュー」「KPI」に関するリクエストで必ず使用する。

筆者の実運用でも、自動呼び出しには過度に期待せず、明示的に /skill-name で呼び出すスタイルを基本にしています。自動呼び出しを狙う場合は「こういう指示が来たら AI はこの Skill を発動すると想像するか？」を頭の中でシミュレーションしながら description を書くのがコツです。description を書き換えると自動呼び出しの挙動が変わる経験は誰もがしますが、明示呼び出しを主軸にしておけば description の良し悪しに振り回されずに済みます。

SKILL.md の長さ上限 — 500行超えたら分割

SKILL.md の本文には明確な上限はありませんが、実用上の目安として以下のガイドラインが知られています。

• 公式推奨: SKILL.md 本文は 5,000 words 以下（約15,000トークン相当）
• 実務推奨: 500行以下を目安に。超える場合は references/ ディレクトリに知識ベースを退避し、SKILL.md 本文では「references/style-guide.md を参照せよ」と指示する
• 自動呼び出し重視の場合: 300トークン以下に収めるとパフォーマンス最適

長い SKILL.md は Claude の指示追従精度を下げます。手順がぼやけたら分割の合図です。

AI に下書きさせて人が仕上げる — 筆者の作成ワークフロー

SKILL.md をゼロから書くのはハードルが高いですが、筆者は常に AI に下書きさせ、人が最終確認・修正するワークフローで回しています。具体的には「コードレビュー用の Skill を作りたい。対象は Python で、security と performance を重点的にチェックしたい」のようにざっくり要件を伝え、AI に SKILL.md の初稿を書いてもらいます。

ただし曖昧な指示のまま任せきりにすると、想定と違う挙動の Skill が出来上がります。初稿をレビューする際は以下の観点を意識しましょう。

• description が pushy になっているか — 自動呼び出しを想定する場合は特に重要
• allowed-tools が絞り込まれているか — AI は Read/Write/Bash を全許可しがちなので、必要最小限に絞る
• 手順が具体的で決定的か — 「適切に処理する」のような曖昧表現を排除する
• 副作用のある操作には disable-model-invocation: true が付いているか

教訓としては、「AI に任せて確認しないと想定通りに動かない」ことが多いので、最後に人が必ず目を通すことで Skill の精度が大きく上がります。

実践例 — すぐ使える Skill 5 選

ここからは、すぐにプロジェクトに導入できる実践的な Skill を5つ紹介します。それぞれフロントマターの例付きです。

実装パターン A / B / C — どのパターンで作るか

Towards Data Science 誌の実装解説記事では、Skills を3つのパターンに分類しています。この分類は「自分のユースケースはどのパターンに該当するか」を判断するのに便利です。

補足: Pattern C は便宜上「MCP 連携」と「context: fork によるサブエージェント実行」をひとまとめにしていますが、厳密には別軸です。実行手段（LLM のみ / スクリプト / MCP）と実行コンテキスト（同一エージェント / 独立サブエージェント）を分けて考えると設計判断がブレません。また、Skills と Subagents は双方向に組み合わせ可能です — Skill に context: fork を指定してサブエージェントとして動かすことも、サブエージェント側で Skills を preload することもできます。

たとえば、Sentry 社が公開している sentry-code-review Skill は Pattern C の典型例です。SKILL.md が PR レビューのワークフロー（変更点の特定 → 関連エラーの確認 → レビューコメント生成）を定義し、Sentry MCP サーバーが実際のエラーログ・スタックトレースを取得します。Skill と MCP がそれぞれ「手順」と「データ取得」に責任を分離している点がポイントです。

---
name: review
description: コードレビューを実行する
allowed-tools: Read, Grep, Glob
---

---
name: tdd
description: TDDサイクルで機能を実装する
model: sonnet
---

---
name: commit
description: Conventional Commits形式でコミット
disable-model-invocation: true
---

---
name: translate
description: i18nファイルの多言語翻訳
model: opus
---

---
name: coding-standards
description: プロジェクトのコーディング規約
user-invocable: false
---

Skill のテストとイテレーション — 作って終わりにしない

Skill は書いたら終わりではなく、実運用のなかで description と手順を磨き込むイテレーションが必要です。テストフェーズを飛ばすと、本番で「想定した挙動にならない」Skill になりがちです。

手動テスト — 想定される入力で叩き続ける

筆者は Skill を作ったら、まず手動で実行して期待する結果が出るかを確認します。ここで重要なのは、「クリーンすぎるプロンプト」ではなく「実ユーザーが実際に打つプロンプト」でテストすることです。

• タイポ・省略を混ぜる: 「コードレビューして」ではなく「このファイルざっとみて」のようなラフな依頼でも発動するか
• ファイル名の省略: 「src/api.ts をレビュー」ではなく「API のやつ見て」でも動くか
• 文脈の曖昧さ: 「いい感じにして」のような雑な依頼で暴走しないか

想定される入力に対して AI が Skill の発動を「想像できる」ように、description の文言を調整していきます。トリガー率が悪いと感じたら description に該当ユースケースのキーワードを追加するのが効果的です。

skill-creator — Anthropic 公式の Skill 生成ツール

Anthropic は Skills を効率的に作成・テストするための公式ツール「skill-creator」を提供しています。skill-creator は以下を自動化します。

• テストプロンプトを 60/40 で train/test 分割し、どの表現で発動するかを計測
• description を複数パターン生成し、トリガー率の高いものを自動選択
• 初めての Skill 作成を 15〜30 分で完了できるワークフロー支援

公式ガイドによれば、skill-creator を使うことで「description がトリガーされない」問題の大半は解消されます。手作業で Bad/Good を比較するのが面倒なら、まず skill-creator を試すのが近道です。

イテレーションループ — 書く → 叩く → 測る → 直す

Skill の改善サイクルは以下の流れで回します。

1. 書く: AI に下書きさせて人が最終確認
2. 叩く: 想定される実ユーザーのプロンプトで手動テスト（5〜10通り）
3. 測る: トリガー率・期待通りの出力率・誤作動率を観察
4. 直す: description のキーワード追加、SKILL.md 手順の具体化、allowed-tools の見直し

チーム・組織での運用

プロジェクト Skills（Git 共有）

Skills の最大の強みの一つが、Git リポジトリを通じたチーム共有です。.claude/skills/ ディレクトリをリポジトリに含めるだけで、チーム全員が同じ Skill を使えるようになります。

筆者自身も開発フローやチームルールを Skill 化し、GitHub 経由で配布しています。特にメンバーが普段やっている手作業や、暗黙のうちに共有されているルールを Skill に落とし込むと効果が大きいです。配布後の反応も良好で、メンバーが各自のユースケースに合わせて Skill をカスタマイズして育てていくエコシステムが生まれました。「配ったら終わり」ではなく「配った後に育つ」のがチーム共有の醍醐味です。

• PR レビューで品質管理: Skills の変更も通常のコードと同様に PR レビューを通して管理。意図しない変更を防止できます
• ワークフローの標準化: コードレビュー、テスト実行、デプロイなどのチーム共通ワークフローを Skill として定義。属人化を排除し、誰が実行しても同じ品質を保てます
• オンボーディングの効率化: 新メンバーは /review や /test を使うだけで、チームのベストプラクティスに沿った作業ができます

配布チャネルの選択肢 — GitHub 以外にも複数ある

配布方法は GitHub だけではありません。チーム・組織の規模やプランに応じて、以下の選択肢があります。

Plugin Marketplace からインストール

Anthropic 公式のマーケットプレイスからは、以下のコマンドで既製の Skill バンドルを導入できます。

# マーケットプレイスを追加
/plugin marketplace add anthropics/skills

# Document Skills（docx/pdf/pptx/xlsx 操作）をインストール
/plugin install document-skills@anthropic-agent-skills

# Example Skills（フロントエンド設計、デザイン等）をインストール
/plugin install example-skills@anthropic-agent-skills

導入前に SKILL.md の中身を確認する習慣はつけておきましょう（セキュリティの観点から第三者 Skill は要注意です）。

Team / Enterprise プランでの一括配布

組織規模での運用には Team / Enterprise プランのプロビジョニング機能が有効です。筆者も Team プラン以上を利用できる環境では、GitHub 配布と組織設定配布を併用しています。GitHub は開発リポジトリ単位の Skill、組織配布は全社共通の規約・セキュリティチェックと、用途を使い分けると管理が整理されます。

• 組織管理画面から Skills をプロビジョニング: 全ユーザーに自動配布され、個人での上書き可否はプランに準拠。組織のポリシーを確実に適用できます
• コーディング規約の強制: user-invocable: false のバックグラウンド Skill として配布すれば、Claude が自動的に組織の規約に従ったコードを生成します
• セキュリティチェックの強制: セキュリティレビュー Skill を全ユーザーに配布し、コード生成時のセキュリティ品質を底上げできます

プレシップチェックリスト — 配布前に必ず確認

セキュリティ上の注意

トラブルシューティング — よくある問題と対処法

Skill が認識されない

自動呼び出しが発動しない

allowed-tools が効かない

よくある質問 — Claude Code Skills について