Claude Code Skills完全ガイド — SKILL.mdの構造と用途別パターン早見表

Claude Code Skillsは .claude/skills/<name>/SKILL.md を1つ置くだけで、Claudeに「専門知識パック」を追加できる仕組みです。手順書・チェックリスト・判断基準をCLAUDE.mdや毎回のプロンプトに直書きする運用から、ファイル化して呼び出す運用へ切り替えるための最小単位として広く使われます。

本記事ではSKILL.mdの構造、配置スコープ(エンタープライズ / 個人 / プロジェクト / プラグイン)、呼び出し方、用途別パターン早見表、よくあるつまずきまでをまとめます。具体的な書き方はClaude Code Skillsの書き方5パターンとSkillsの作り方と使い分けで深掘り解説しているので、本記事は「全体像 + 仕様 + 設計判断」に集中します。

Claude Code Skillsとは

• .claude/skills/<name>/SKILL.md を1つ置くだけでSkillが成立する最小構成
• frontmatterで name / description を指定、本文はMarkdownの手順書 / チェックリスト / 判断基準
• 呼び出し方は3通り:① ユーザーが /skill-name で明示起動 ② Claudeが文脈から自動判断で起動 ③ Skill tool経由でプログラム的に起動
• 配置スコープはエンタープライズ / 個人グローバル(~/.claude/skills/)/ プロジェクト固有(<project>/.claude/skills/)/ プラグイン提供(npmパッケージ)の4種類で、同名時はエンタープライズ > 個人 > プロジェクトの順に優先されます
• 遅延ロードされるため、CLAUDE.mdと違い「呼ばれたときだけ」コンテキストに乗る(トークン効率が良い)

CLAUDE.md(プロジェクト全体の常駐ルール)・Sub-agents(独立コンテキストでの並列実行)・MCP(外部システム連携)との使い分けについては、Claude Code Skillsの作り方と使い分けで詳しく扱っています。

SKILL.mdの最小構造

最小のSKILL.mdは次のような形です。frontmatterは全フィールドが任意で、description だけが推奨です(Claudeが自動起動を判断する手がかりになるため)。name を省略するとディレクトリ名が使われます。

---
name: commit-message-writer
description: コミットメッセージを変更内容から推定して生成する skill。日本語サブジェクト + 規約プレフィックス(add:/update:/fix:/...)で出力する。
---
 
# commit-message-writer Skill
 
## やること
 
1. `git diff --cached` で変更内容を取得
2. ファイル種別と差分内容からプレフィックスを推定
3. 50 字以内のサブジェクトを生成
 
## プレフィックス選択ルール
 
| 変更内容 | プレフィックス |
|---|---|
| 新機能・依存追加 | `add:` |
| 既存機能の更新 | `update:` |
| バグ修正 | `fix:` |
| ファイル / コード削除 | `remove:` |
| リファクタ(動作不変) | `refactor:` |
 
## 出力フォーマット
 
`<prefix>: <subject>` 1 行のみ。本文を提案しない。

frontmatterの主要キーは次のとおりです。

model指定でSkillだけモデルを切り替える

model を指定すると、そのSkillが動いている間だけモデルを切り替えられます。受け付ける値は /model と同じモデルID(claude-opus-4-7 など)、または inherit です。inherit を指定すると現在のセッションのモデルをそのまま引き継ぐ扱いになり、明示的に「セッションに合わせる」と書きたいときに使えます。重い判断を伴うSkillだけ上位モデルに上げる、といった使い分けをSkill単位で閉じ込められる点が利点です。

disable-model-invocationで副作用のあるSkillを手動起動に限定する

disable-model-invocation: true を付けると、そのSkillはClaudeの自動起動の対象から外れ、ユーザーが /name で明示的に呼んだときだけ動くようになります。デプロイやコミット、Slack送信のように副作用を伴うSkill(/deploy など)は、コードが整って見えたという理由でClaudeに勝手に起動されると困るため、このキーで起動タイミングを人の手に握っておく設計が向いています。後の用途別表で挙げた「繰り返すコマンド系作業」のうち、実行が不可逆なものはこのキーとあわせて設計すると安全側に倒せます。

配置スコープと優先順位

Skillsは次のスコープから配置できます。同名Skillが複数スコープにある場合、エンタープライズ > 個人 > プロジェクトの順で上書きされます(個人スコープがプロジェクトに優先)。プラグインSkillは plugin-name:skill-name の名前空間を持つため衝突しません。

「プロジェクト内をsource of truth、個人グローバルはテンプレート保管庫」とする設計が運用上安定しやすいです。理由は別マシンで git clone したときにSkillごと付いてくるため、AI単独運営でも自己完結します。

カスタムスラッシュコマンド(.claude/commands/<name>.md)は、現在はSkillに統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動きます。既存の commands/ 配下のファイルはそのまま動き続けますが、同名のコマンドとSkillが両方ある場合はSkillが優先されます。Skill側だけが、サポートファイルを置けるディレクトリ・自動起動の制御・関連時の自動読み込みといった追加機能を持つため、新規に作るなら commands/ ではなくSkill形式にしておくと拡張の余地が残ります。

3つの呼び出し方

Claude CodeはSkillsを3種類の起動経路で扱えます。

自動起動を成立させる鍵は description の質です。Claudeはdescriptionだけを読んで「これは今の文脈で使うべきか」を判断するため、用途・入出力・トリガー条件を1文で具体的に書きます。曖昧なdescriptionは自動起動が空振りし、ユーザーが毎回 /name で明示起動する運用になります。

用途別パターン早見表

実運用で「この用途にはSkillを作るべきか、作るならどんな構成にするか」の判断軸を、よくあるニーズと推奨構成の対応表でまとめます。

選び方の原則は次のとおりです。

1. 常駐するルールはCLAUDE.md、呼んだ時だけのルールはSkill:CLAUDE.mdは全プロンプトで読まれるので、滅多に使わない手順を入れると毎ターンのトークンが無駄になります
2. 外部システム接続はMCP、Claude内の手順はSkill:権限委譲・状態保持・API呼び出しはMCPの責務。Skillは「Claudeに手順書を渡す」役割
3. 重い分析はSub-agent、軽い手順はSkill:Sub-agentは独立コンテキストを持つので並列実行や巨大な調査向き。Skillはメインセッションのコンテキスト内で動く

CLAUDE.md / Sub-agents / MCPとの境界はどこで引くか

Skillをどこに置くかで迷う場面の多くは、実は「これはSkillの仕事ではない」という線引きの問題です。Claude Codeの拡張ポイントは、常駐ルールのCLAUDE.md、独立コンテキストで並列に走るSub-agents、外部システムと接続するMCPという3つのレイヤーに分かれ、Skillはそのどれとも重なりません。先につまずき表や用途別表で触れた判断軸を、ここでは「常駐するか」「コンテキストを分けるか」「外部に出るか」という3つの軸で1枚に集約します。

CLAUDE.mdは毎ターン読み込まれる常駐ルールです。そのため「いつ使うか分からないが必ず守ってほしい前提」を置く場所で、滅多に使わない長い手順を入れると毎回のトークンに乗り続けて無駄が出ます。逆にSkillは呼ばれたときだけ本文が読み込まれるので、長い手順書や参照資料はSkillに逃がし、CLAUDE.mdには「事実」と「常に効く短い規約」だけを残すと、両者の役割が自然に分かれます。判断の目安は「これは毎回必要な前提か、それとも特定の作業のときだけ必要な手順か」です。

Sub-agentsはメインとは別のコンテキストで動く点がSkillと決定的に違います。Skillはメインセッションの会話履歴を共有したまま手順書として効きますが、Sub-agentは独立した文脈を持つため、巨大な調査や並列実行、メインの文脈を汚したくない隔離作業に向きます。SkillとSub-agentは対立せず併用でき、Skillをorchestratorとして手順を書き、その中で重い処理をSub-agentに委譲する構成が組めます。Skill自体にcontext: forkを付けて、その本文をそのままSub-agentのプロンプトとして切り出す扱い方もできます。

MCPは唯一「Claudeの外」に責務を持つレイヤーです。APIの呼び出し、データソースへの接続、認証や状態の保持はMCPサーバー側が担い、Claudeにはツールとして見えます。Skillは外部接続そのものを引き受けず、「そのMCPツールをいつどう呼ぶか」という手順だけを書くのが役割分担です。外部システムと話す必要が出たときは、まずMCPに切り出せないかを先に考え、Skillはその使い方の説明に留めると、責務が混ざらずに済みます。

Skillから他レイヤを呼ぶ

Skill内からsub-agentを呼ぶことで、orchestratorパターンが組めます。本サイトClaude Mediaの記事生成では article-generator Skillが explore-sources / draft-writer の各sub-agentを順次呼ぶ構成を採用しており、Skill 1つでパイプライン全体を駆動できます。

## 実行ステップ
 
1. `explore-sources` agent で一次ソース収集
2. `draft-writer` agent で本文初稿
3. `fact-checker` agent で公式 docs 照合
4. `quality-judge` agent で 4 観点採点
5. 🟡 なら `rewriter` agent に差戻し(最大 3 回)
6. `seo-optimizer` agent で内部リンク追加
7. `scripts/normalize-ja-spaces.ts --apply` で正規化

Skill本文に手順を書いておけば、Claudeはそのとおりにsub-agent呼び出しを連鎖させます。各sub-agentの責務とインターフェースを明確にしておくのが、orchestratorパターンを安定運用するコツです。

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

Skillsの運用で踏みやすい落とし穴を6件集めました。

つまずき1:description が抽象的で自動起動が空振り

description: "コミットを書く" のような短い説明だと、Claudeが文脈から「今このSkillを呼ぶべき」と判断できず、ユーザーが毎回 /commit で明示起動する運用になります。「コミットメッセージを変更内容から推定し、日本語サブジェクト + プレフィックス(add:/update:/fix:/...)で1行出力する」のように、用途・入出力・トリガー条件を1文に込めます。

つまずき2:CLAUDE.mdとSkillにルールを二重で書く

同じ判断基準をCLAUDE.mdとSkill本文の両方に書くと、片方を更新したときに同期が取れません。判断基準は単一情報源(SSOT)を決め、Skill本文には「SSOTをReadする」とだけ書く形が安全です。本サイトでは media/.claude/guidelines/article-quality.md をSSOTにし、各Skill / agentはその参照だけを書いています。

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

「面倒だからBash全許可」と書いてしまうと、Skill動作中は危険コマンドも承認なしに実行されます。最小権限の原則で、本当に必要なコマンド系統だけ許可します。allowed-tools: ["Bash(git:*)"] のようにdeny / allowパターンで絞り込むのが基本です(詳細はClaude Code設定ファイル完全ガイドを参照)。

つまずき4:Skill内で巨大なドキュメントを丸ごと貼る

参照資料1万字をSKILL.mdに貼ると、呼び出すたびに1万字分のトークンを消費します。「Readで media/docs/strategy/*.md を都度読む」のように、外部ファイルへの参照に置き換えると遅延ロードの利点が活きます。

つまずき5:複数Skillが同名で衝突

commit という名前のSkillを個人グローバルとプロジェクト両方に置くと個人側が勝ち、プロジェクト固有のSkillが無視されることがあります。スコープを意識して名前を分けます。意図と違うSkillが呼ばれて困惑するケースが多いので、汎用名(commit / deploy)は個人スコープに残し、プロジェクト固有名(media-commit 等)を使うか、用途別に名前を分けます。

つまずき6:Skillがsub-agentを呼ぶときに引数が伝わらない

Skill本文に「draft-writer agentを呼ぶ」と書くだけでは、何のトピックを書かせるのかがsub-agentに伝わりません。Skill内で「draft-writer agentに、トピック・ソース・要件を渡して呼ぶ」のように、渡す引数を具体的に書いておくイメージで明示しておくと、引数渡しが安定します。

まとめ

Claude Code SkillsはSKILL.mdファイル1つで成立する最小単位で、CLAUDE.md / Sub-agents / MCPの中間に位置するレイヤーです。設計判断の軸は次の3つです。

1. 常駐するルールはCLAUDE.md、呼ばれた時だけはSkill
2. 外部システム連携はMCP、Claude内の手順はSkill
3. 重い分析はSub-agent、軽い手順はSkill

具体的な書き方はClaude Code Skillsの書き方5パターンで5つのテンプレを、設計思想はSkillsの作り方と使い分けで、Sub-agentとの連携パターンはClaude Code Sub-agent並列実行パターンで詳細を扱っています。

Skillは導入難度が低く、効果が長期間効く投資対効果の良い領域です。最初は「コミットメッセージを書く」「PR説明文を書く」のような短い手順書から始めて、運用しながら判断基準型 / 構造化テンプレ型に展開していく形が安定して続けやすいでしょう。