Claude Code Skills実践ガイド — YAML frontmatter全解説から自動起動・サブエージェント連携まで

Claude Codeで毎回同じ指示を書いていませんか？ 「コンポーネントを作るときはこのテンプレートに従って」「レビューではこの観点をチェックして」——こうした繰り返しは、Skillsを使えばMarkdownファイル1つで解決できます。

本記事では、YAML frontmatterの全フィールド解説から、descriptionによる自動起動の仕組み、Hooks・カスタムサブエージェントとの使い分けまで、Claude Codeカスタマイズの中核機能を実践コード付きで解説します。

Skillsとは何か — commandsとの統合と現行アーキテクチャ

commands → skills統合の経緯

かつてClaude Codeには .claude/commands/ というカスタムスラッシュコマンドの仕組みがありました。v2.1.3でこれが .claude/skills/ に統合され、frontmatterによる細かな実行制御が可能になりました。同名のファイルが両方に存在する場合、skillsが優先されます。

ディレクトリ構成と優先順位

スキルの配置場所は2つあります。

# プロジェクト固有（チームで共有される）
.claude/skills/deploy/SKILL.md
.claude/skills/deploy/template.tsx    # supporting file

# ユーザーグローバル（個人の全プロジェクトで使える）
~/.claude/skills/review/SKILL.md

ディレクトリ名がそのままスラッシュコマンド名になります。上の例なら /deploy で呼び出せます。SKILL.md と同じディレクトリに置いたファイルはsupporting filesとして自動的に読み込まれるため、テンプレートファイルを同梱できます。

user-invocable: true で /コマンド名 として手動呼び出し可能に、false にするとAIが自動判断で起動する専用スキルになります。

YAML frontmatter全フィールド解説

基本フィールド

---
name: コードレビュー
description: "PRの差分をレビューし、問題点を指摘する"
when_to_use: "ユーザーが「レビューして」「PRチェック」と言った時"
argument-hint: "<PR番号またはブランチ名>"
user-invocable: true
---

description と when_to_use の合計は1,536文字で切り詰められます。自動起動の精度に直結するため、簡潔かつ具体的に書くことが重要です。

実行制御

---
name: 安全な調査スキル
description: "コードベースを読み取り専用で調査する"
allowed-tools:
  - Read
  - Grep
  - Glob
disable-model-invocation: false
model: sonnet
---

高度な制御

---
name: アーキテクチャ設計
description: "設計方針を検討し、実装計画を立てる"
agent: Plan
context: fork
---

context: fork を指定すると、親とは別のコンテキストでサブエージェントとして実行されます。agent フィールドには Explore（コード探索特化）、Plan（設計特化）、general-purpose、またはカスタムエージェント名を指定できます。

自動起動の仕組み — descriptionだけでAIが判断する

user-invocable: false のスキルは、ユーザーの発言内容と description を照合してAIが自動的に起動判断します。

---
name: テスト規約注入
description: "Use when the user creates or modifies test files (*.test.ts, *.spec.ts)"
when_to_use: "テストファイルを新規作成する時、既存テストを修正する時"
user-invocable: false
---

テストは以下の規約に従って書いてください:
- describeブロックでグループ化
- AAA（Arrange-Act-Assert）パターンを使用
- モックは最小限に

正直、最初は「descriptionを書くだけで本当に起動するのか？」と半信半疑でしたが、条件を具体的に書けば想像以上に正確に発火します。

description予算に注意

全スキルの description 合計には予算があります。コンテキストウィンドウの1%（フォールバック値は8,000文字）が上限で、これを超えると切り詰められます。環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で調整可能です。スキル数が増えてきたら、不要なスキルの description を削るか、類似スキルを統合しましょう。

実践パターン3選

パターン1: supporting filesによるテンプレート駆動

SKILL.mdと同ディレクトリに置いたファイルが自動読み込みされます。

.claude/skills/component/
├── SKILL.md
└── template.tsx

# SKILL.md
---
name: Reactコンポーネント生成
description: "プロジェクト規約に沿ったReactコンポーネントを生成する"
argument-hint: "<コンポーネント名>"
user-invocable: true
---

$ARGUMENTS[0] という名前のコンポーネントを作成してください。
template.tsx の構造に従い、既存コンポーネントとの整合性を保つこと。

既存コンポーネント一覧:
!`ls src/components/`

パターン2: シェルコマンド動的注入

!`command` 構文でシェルコマンドの実行結果をプロンプトに注入できます。これは地味に便利です。

直近のコミット:
!`git log --oneline -5`

現在のブランチ:
!`git branch --show-current`

利用可能な変数は $ARGUMENTS（全引数）、$ARGUMENTS[0] / $0（0始まり）などがあります。

パターン3: 複数スキルのパイプライン連携

スキルの本文中で別のスキルを /スキル名 で呼び出す指示を書くことで、パイプライン的に連携できます。

---
name: ship
description: "テスト→レビュー→デプロイの一連のフローを実行する"
user-invocable: true
---

以下の順序で実行してください:
1. /test を実行してすべてのテストが通ることを確認
2. /review で差分をセルフレビュー
3. 問題がなければ /deploy を実行

Skills・Hooks・カスタムサブエージェント 使い分け判断フロー

Claude Codeには3つの拡張機構があります。

迷ったらこのフローで判断:

繰り返している指示がある？ → Yes → Skills
   ↓ No
ツール実行時に自動で何か検証したい？ → Yes → Hooks
   ↓ No
専門知識を分離して別人格で処理させたい？ → Yes → カスタムサブエージェント

組み合わせも強力です。たとえば、Skillがサブエージェントを agent フィールドで呼び出し、Hookでその実行ログを記録する——といったフルスタック構成も可能です。

よくあるハマりポイントと対策

YAMLパースエラー: description にコロン : を含む場合はクォートで囲む必要があります。description: Use when: deploying は失敗し、description: "Use when: deploying" が正解です。

スキルが自動起動しない: description が曖昧すぎるか、予算オーバーで切り詰められている可能性があります。when_to_use で発火条件を具体化し、不要なスキルを整理しましょう。

supporting filesが読まれない: SKILL.mdと同階層のファイルのみが対象です。サブディレクトリ内のファイルは読み込まれません。

allowed-toolsの指定ミス: ツール名は正確に指定する必要があります（Bash, Read, Edit, Grep, Glob, Agent, Write など）。大文字小文字も区別されます。

context: fork時の注意: 親コンテキストの変数や状態は引き継がれません。必要な情報はスキルの本文内で明示的に渡す設計にしてください。

Skillsは「繰り返す指示をファイル化する」という単純な出発点から、frontmatter制御・自動起動・テンプレート駆動・サブエージェント連携まで、Claude Codeの拡張性の中核を担う機能です。Hooks（自動検証）とカスタムサブエージェント（専門知識の分離）と組み合わせることで、チーム全体の開発ワークフローを標準化できます。

まずは日常的に繰り返している指示を1つ、SKILL.mdに切り出すところから始めてみてください。