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

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

本記事ではSKILL.mdの構造、3スコープ(プロジェクト / 個人 / プラグイン)、呼び出し方、用途別パターン早見表、よくあるつまずきまでを完全網羅します。具体的な書き方は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経由でプログラム的に起動
• 配置スコープは3種類:プロジェクト固有(<project>/.claude/skills/)/ 個人グローバル(~/.claude/skills/)/ プラグイン提供(npmパッケージ)
• 遅延ロードされるため、CLAUDE.mdと違い「呼ばれたときだけ」コンテキストに乗る(トークン効率が良い)

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

SKILL.mdの最小構造

最小のSKILL.mdは次のような形です。frontmatterの name と description だけが必須で、本文は自由に書けます。

---
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の主要キーは次のとおりです。

3つの配置スコープと優先順位

Skillsは次の3スコープから配置できます。優先順位はプロジェクト > 個人 > プラグインで、同名Skillがあった場合はプロジェクト側が勝ちます。

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

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はメインセッションのコンテキスト内で動く

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が呼ばれて困惑するケースが多いので、汎用名(commit / deploy)は個人スコープに残し、プロジェクト固有名(media-commit 等)を使うか、用途別に名前を分けます。

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

Skill本文に「draft-writer agentを呼ぶ」と書くだけでは、何のトピックを書かせるのかがsub-agentに伝わりません。Skill内で「Agent({ subagent_type: "draft-writer", prompt: "<トピック> + <ソース> + <要件>" }) のように呼ぶ」と明示しておくと、引数渡しが安定します。

まとめ

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説明文を書く」のような短い手順書から始めて、運用しながら判断基準型 / 構造化テンプレ型に展開していく形が安定して続けやすいでしょう。