Claude Code Skills実践ガイド — SKILL.mdの設計からサブエージェント連携・チーム共有まで

2026年3月、Claude CodeのSlash CommandsがSkillsシステムに統合された。単なるリネームではない。フロントマターによる自動起動制御、サブエージェント委譲、effort調整、パス制限——Skillsは「プロンプトのスニペット」から「宣言的な自動化ユニット」へと進化した。本記事では、移行手順から設計パターン、チーム運用戦略まで、Skillsを使い倒すための実装知識を網羅する。

Slash Commands → Skills：何が変わったのか

統合の背景とAgent Skills標準（agentskills.io）

v2.1.3でSlash CommandsはSkillsシステムに統合された。.claude/commands/は後方互換で引き続き動作するが、新機能はskills/のみに追加される。

この統合の背景には、agentskills.io準拠のAgent Skills標準がある。Cursor、Gemini CLIなど他のAIコーディングツールとのクロス互換が視野に入ったことで、ツール固有のコマンド形式ではなく、標準化されたスキル定義が求められるようになった。

注意すべきはv2.1.89の破壊的変更だ。commands/のサブディレクトリ内ファイル（commands/subdir/*.md）が検出されなくなる。サブディレクトリでコマンドを整理していたチームにとっては、これが移行の実質的な期限となる。

.claude/commands/ から .claude/skills/ への移行手順

移行自体はシンプルで、サブディレクトリ作成とSKILL.mdへのリネーム、フロントマター追加で完了する。既存のプロンプト本文はそのまま使える。

- .claude/commands/review.md
+ .claude/skills/review/SKILL.md

移行後のファイルにフロントマターを追加する:

---
name: review
description: PRの差分をレビューし、改善点を指摘する
user-invocable: true
---

以下のPR差分をレビューしてください。
コードの品質、セキュリティ、パフォーマンスの観点から改善点を指摘してください。

$ARGUMENTS

フロントマターがない状態でも動作はするが、後述するdescription予算や自動起動制御の恩恵を受けるには追加が必須だ。

SKILL.mdフロントマター完全リファレンス

主要フィールド：name / description / user-invocable

すべてのフロントマターフィールドはオプションだが、実運用上は設定を推奨する。

descriptionには重要な制約がある。全スキル合計のdescription予算はコンテキストウィンドウの1%（フォールバック8,000文字）に制限される。1つのスキルでdescriptionを長く書きすぎると、他のスキルが認識されなくなる。環境変数SLASH_COMMAND_TOOL_CHAR_BUDGETで調整は可能だが、まずは250文字以内に収める習慣をつけたい。

自動起動制御：description / paths / disable-model-invocation

---
name: lint-fix
description: ESLintエラーを自動修正する。src配下のTypeScriptファイルでlintエラーが検出された場合に使用する。
user-invocable: true
disable-model-invocation: true
paths:
  - src/**/*.ts
  - src/**/*.tsx
---

disable-model-invocation: trueを付けると、ユーザーが明示的に/lint-fixと呼び出した場合のみ実行される。これを付け忘れると、モデルが「このスキルが適切だ」と判断したタイミングで勝手に起動する。正直、最初はこれに気づかず混乱した。

pathsはYAMLリスト形式で、特定ディレクトリ配下でのみスキルを有効化できる。モノレポで特に有用だ。モデルはdescriptionの内容をもとにスキルの適用場面を判断するため、どのような状況で使うべきかをdescription内に記述しておくとよい。

実行制御：allowed-tools / model / effort / context

---
name: quick-explain
description: 指定されたコードの概要を簡潔に説明する
user-invocable: true
effort: low
allowed-tools:
  - Read
  - Grep
  - Glob
context: fork
---

effortはlow / medium / high / max（maxはOpus 4.6のみ）から選択でき、軽量タスクにlowを指定するとトークン節約に直結する。

context: forkを指定するとサブエージェントプロセスで実行され、メインの会話コンテキストに結果だけが返る。調査系のスキルで特に効果的だ。

実装パターン集：5つのユースケース

パターン1：引数付きスキル（argument-hint + $ARGUMENTS）

---
name: explain
description: 指定ファイルのコードを解説する
user-invocable: true
argument-hint: <file-path>
effort: medium
---

$ARGUMENTS のコードを読み、以下の観点で解説してください:
- 全体のアーキテクチャ
- 主要な関数の役割
- 依存関係

$ARGUMENTSはスキル本文内で展開される。/explain src/index.tsと実行すれば、$ARGUMENTSがsrc/index.tsに置換される。argument-hintはUIのプレースホルダー表示用で、実行には影響しない。

パターン2：シェルコマンド埋め込み（!command構文）

---
name: changelog
description: 直近のコミットからCHANGELOG草稿を生成する
user-invocable: true
---

以下の直近コミットログを元に、CHANGELOG.mdの草稿を生成してください:

!`git log --oneline -20`

現在のCHANGELOG.mdの内容:
!`cat CHANGELOG.md`

!バッククォート構文でシェルコマンドの出力を動的に埋め込める。スキル実行時にリアルタイムの情報を取得でき、静的なプロンプトでは実現できない柔軟性が得られる。

パターン3：サブエージェント委譲（context: fork）

---
name: review-with-test
description: コードレビュー後にテストを実行して結果を統合報告する
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Agent
---

以下の手順でレビューを実施してください:

1. $ARGUMENTS の差分を確認し、コードレビューを行う
2. Agentツールでテスト実行エージェントを起動し、関連テストを実行する
3. レビュー結果とテスト結果を統合して報告する

context: forkでサブエージェントとして実行されるため、メインの会話コンテキストを汚さない。レビューのような重い処理をスキルに委譲する典型的なパターンだ。

パターン4：${CLAUDESKILLDIR}でスキルローカルリソース参照

---
name: generate-component
description: テンプレートからReactコンポーネントを生成する
user-invocable: true
argument-hint: <ComponentName>
---

以下のテンプレートに従って $ARGUMENTS コンポーネントを生成してください:

!`cat ${CLAUDE_SKILL_DIR}/templates/component.tsx.tmpl`
!`cat ${CLAUDE_SKILL_DIR}/templates/component.test.tsx.tmpl`

${CLAUDE_SKILL_DIR}で、SKILL.mdファイルと同階層のテンプレートやデータファイルを相対参照できる。スキルとリソースをセットで管理できるのは地味に便利だ。

パターン5：allowed-toolsでスキルの権限を制限

---
name: analyze
description: コードベースを分析して構造レポートを出力する
user-invocable: true
allowed-tools:
  - Read
  - Grep
  - Glob
---

コードベースを分析し、以下のレポートを生成してください:
- ディレクトリ構造の概要
- 主要モジュール間の依存関係
- コード行数の統計

allowed-toolsでスキルが使えるツールを明示的に制限することで、分析専用スキルが意図せずファイルを変更するリスクを排除できる。

チーム開発での.claude/skills/ディレクトリ戦略

リポジトリスキル vs ユーザースキル vs プロジェクトスキルの使い分け

チームで統一すべきスキルはリポジトリスキルとしてgit管理する。コードレビュー基準、コミットメッセージ規約、テスト生成テンプレートなど、チーム全体で一貫性を持たせたいものが該当する。逆に、個人のワークフローに依存するスキルはユーザースキルに留める。

命名規則とディレクトリ構成のベストプラクティス

.claude/skills/
├── review-pr/
│   └── SKILL.md              # PRレビュー
├── generate-test/
│   └── SKILL.md              # テスト生成
├── check-deploy/
│   └── SKILL.md              # デプロイ前チェック
├── generate-component/
│   ├── SKILL.md              # コンポーネント生成
│   └── templates/            # ${CLAUDE_SKILL_DIR}で参照
│       ├── component.tsx.tmpl
│       └── component.test.tsx.tmpl
└── analyze-deps/
    └── SKILL.md              # 依存関係分析

命名は動詞-名詞形（review-pr、generate-test）のディレクトリ名を推奨する。各スキルのエントリーポイントはSKILL.mdという固定ファイル名になる。MCPサーバー由来のスキルとは完全修飾名（namespace:skill-name）で自動的に区別される。

ハマりポイントと解決策

移行時の落とし穴

サブディレクトリ問題: v2.1.89以降、commands/subdir/配下のファイルは検出されない。skills/のサブディレクトリ+SKILL.md形式に移行する。

# 移行コマンド例
mkdir -p .claude/skills/review
mv .claude/commands/review.md .claude/skills/review/SKILL.md

pathsの設定範囲: pathsを狭く設定しすぎると、モノレポ内の別パッケージでスキルが動作しない。ワイルドカードを適切に活用する。

フロントマター設計のアンチパターン

description予算超過: descriptionが長すぎると以下のような問題が発生する。

Warning: Skill descriptions exceed budget (8000 chars).
Some skills may not be recognized. Reduce description lengths.

対処法は単純で、各スキルのdescriptionを250文字以内に収めること。「何をするか」だけを端的に書き、「どうやるか」はスキル本文に委ねる。

disable-model-invocationの付け忘れ: 破壊的な操作を含むスキル（デプロイ、データ削除など）には必ずdisable-model-invocation: trueを付ける。付け忘れるとモデルの判断で自動起動される可能性がある。

context: forkでのファイル編集: context: forkで起動したサブエージェント内でのファイル編集は、メインエージェントのワーキングツリーに反映されない場合がある。ファイル変更を伴うスキルではcontext: forkを避けるか、結果をメインエージェントに返して編集させる設計にする。

Skillsは単なるプロンプトテンプレートではなく、フロントマターで宣言的に制御される自動化ユニットだ。移行は今すぐ始められるし、始めるべきだ。v2.1.89のサブディレクトリ検出廃止を踏まえると、猶予は多くない。

まずは既存のcommands/をskills/のサブディレクトリ+SKILL.md形式に移し、descriptionとpathsを追加するところから始めてほしい。そこから先は、サブエージェント委譲やeffort調整で、チームの開発ワークフローに合わせた自動化を段階的に積み上げていける。