Claude Code カスタムスキル開発の実装パターン
半年ほど Claude Code を業務で使っていると、同じ手順を毎回プロンプトに書くのが煩わしくなってきます。私の場合は「PR レビュー前に確認したい7項目」を毎回タイプしていて、ある時「これ、スキルにすればいいのか」と気づきました。Claude Code のスキルシステムは、まさにこの「いつもやっている手順」を /review、/deploy、/migrate のようなスラッシュコマンドとしてパッケージ化し、チームで共有するための仕組みです。
以下では、私が実際に作って使っている3つのスキルを例に、SKILL.md の構造、コンテキスト注入の設計、テスト・配布までの流れを解説します。
前提知識・環境構築
このチュートリアルを進めるには、以下の環境が必要です。
必須ツール:
- Claude Code CLI（v2.15 以降推奨）
- Node.js 18+ または Python 3.10+
- Git（バージョン管理用）
推奨知識:
- Claude Code の基本操作（
/help、/modelなどの組み込みコマンド） - YAML フロントマターの基本構文
- Markdown の記法
インストール確認は以下のコマンドで行えます。
# Claude Code のバージョン確認
claude --version
# スキルディレクトリの確認
ls -la .claude/skills/ 2>/dev/null || echo "スキルディレクトリ未作成"スキルディレクトリが存在しない場合は、プロジェクトルートで作成します。
mkdir -p .claude/skillsスキルの内部アーキテクチャ
Claude Code のスキルシステムは、以前の「カスタムコマンド」（.claude/commands/*.md）を拡張・統合したものです。現在はどちらのディレクトリに配置しても同じスラッシュコマンドとして認識されますが、スキルの方がより多くの機能をサポートしています。
ディレクトリ構造
スキルは以下の2つのスコープで配置できます。
# プロジェクトスコープ（チーム共有向け）
.claude/skills/
review/
SKILL.md # スキル定義（必須）
templates/ # テンプレートファイル（任意）
examples/ # サンプルコード（任意）
# ユーザースコープ（個人利用）
~/.claude/skills/
my-skill/
SKILL.md
プロジェクトスコープのスキルは Git で管理でき、チームメンバー全員が同じスキルを利用できます。ユーザースコープのスキルは個人の環境にのみ適用されます。
SKILL.md の構造
すべてのスキルは SKILL.md ファイルで定義されます。このファイルは YAML フロントマターと Markdown 本文で構成されます。
---
name: review # スラッシュコマンド名（/review で呼び出し）
description: "コードレビューを実行し、改善点を指摘する"
# --- 以下はオプション ---
user-invocable: true # ユーザーが直接呼び出し可能（デフォルト: true）
agent: "claude-code" # エージェントタイプ
allowed-tools: # 使用可能なツールを制限
- Read
- Glob
- Grep
context: # コンテキスト注入の設定
- type: file
path: ".eslintrc.json"
- type: shell
command: "git diff --staged --stat"
---
# コードレビュースキル
以下のルールに従ってコードレビューを実施してください。
1. セキュリティ脆弱性のチェック
2. パフォーマンスの問題点
3. コーディング規約への準拠
...フロントマターの全オプション
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
| name | string | ディレクトリ名 | スラッシュコマンド名 |
| description | string | — | スキルの説明（自動トリガー判定に使用） |
| user-invocable | boolean | true | ユーザーが直接呼び出せるか |
| agent | string | "claude-code" | 実行エージェントタイプ |
| allowed-tools | string[] | すべて | 使用可能なツールのリスト |
| context | object[] | — | コンテキスト注入の定義 |
| disable-model-invocation | boolean | false | LLM 呼び出しを無効化 |
実践1：インテリジェントなコードレビュースキル
最初のスキルとして、Git のステージング済み変更を分析し、カテゴリ別にフィードバックを返すレビュースキルを構築します。
ステップ1：ディレクトリとファイルの作成
mkdir -p .claude/skills/smart-reviewステップ2：SKILL.md の作成
---
name: smart-review
description: "ステージング済みの変更をインテリジェントにレビューする。セキュリティ、パフォーマンス、保守性の3軸で分析。"
allowed-tools:
- Read
- Glob
- Grep
- Bash
context:
- type: shell
command: "git diff --staged"
- type: shell
command: "git diff --staged --stat"
- type: file
path: ".claude/skills/smart-review/review-rules.md"
---
# スマートコードレビュー
あなたはシニアソフトウェアエンジニアとして、以下の3つの軸でコードレビューを実施します。
## レビュー軸
### 1. セキュリティ（Critical / Warning / Info）
- SQLインジェクション、XSS、CSRF の可能性
- ハードコードされた秘密情報（APIキー、パスワード）
- 不適切な入力バリデーション
- 安全でない暗号化手法
### 2. パフォーマンス（Warning / Info）
- N+1クエリの可能性
- 不要なループ内のI/O操作
- メモリリークの可能性
- 非効率なアルゴリズム（O(n²) 以上）
### 3. 保守性（Warning / Info）
- 関数の複雑度（サイクロマチック複雑度 > 10）
- マジックナンバー・マジックストリング
- 不十分なエラーハンドリング
- テストカバレッジの欠如
## 出力フォーマット
以下の形式で結果を報告してください。
レビュー結果サマリー
| カテゴリ | Critical | Warning | Info | |---------|----------|---------|------| | セキュリティ | X件 | X件 | X件 | | パフォーマンス | — | X件 | X件 | | 保守性 | — | X件 | X件 |
🔴 Critical Issues
（該当するものがあればファイル名・行番号とともに記述）
🟡 Warnings
（改善を推奨する項目）
🔵 Info
（任意の改善提案）
📝 総合コメント
（全体的な品質評価と改善の方向性）
変更が少ない場合（10行未満）でも、必ず全軸でチェックを実行してください。
問題がない場合は「問題なし」と明示してください。
ステップ3：補足ルールファイルの作成
<!-- .claude/skills/smart-review/review-rules.md -->
# プロジェクト固有のレビュールール
## 命名規約
- React コンポーネント: PascalCase
- 関数・変数: camelCase
- 定数: UPPER_SNAKE_CASE
- ファイル名: kebab-case
## 禁止パターン
- `any` 型の使用（TypeScript）
- `console.log` の本番コードへの残存
- `// TODO` コメントの放置（Issue 番号を付けること）
## 必須パターン
- すべての公開関数に JSDoc コメント
- エラーハンドリングは `try-catch` で明示的に
- 非同期処理は必ず `async/await` を使用ステップ4：実行テスト
# テスト用の変更をステージング
git add -p
# スキルを実行
claude /smart-reviewこのスキルのポイントは、context フィールドでシェルコマンドの出力を自動注入している点です。スキルが呼び出された瞬間に git diff --staged の結果がコンテキストとして渡されるため、ユーザーが差分を手動で貼り付ける必要がありません。
実践2：データベースマイグレーション生成スキル
次に、データベーススキーマの変更を検知し、マイグレーションファイルを自動生成するスキルを構築します。
SKILL.md
---
name: gen-migration
description: "データベーススキーマの変更からマイグレーションファイルを自動生成する"
allowed-tools:
- Read
- Write
- Glob
- Bash
context:
- type: shell
command: "ls -la migrations/ 2>/dev/null | tail -5"
- type: shell
command: "git diff --name-only HEAD | grep -E '(schema|model|entity)' || echo 'スキーマ変更なし'"
---
# データベースマイグレーション生成
## 手順
1. 変更されたスキーマファイルを特定する
2. 既存のマイグレーション履歴を確認する
3. 差分からマイグレーションSQLを生成する
4. ロールバック用の down マイグレーションも必ず生成する
## マイグレーションファイル命名規則
migrations/ YYYYMMDDHHMMSS_[説明的な名前].sql
例: `20260320100000_add_user_preferences_table.sql`
## 生成テンプレート
```sql
-- Migration: [説明]
-- Created: [日時]
-- Up Migration
BEGIN;
-- ここにスキーマ変更を記述
COMMIT;
-- Down Migration (Rollback)
BEGIN;
-- ここにロールバック処理を記述
COMMIT;
ルール
- すべての操作をトランザクション内で実行すること
DROP TABLEにはIF EXISTSを付けること- カラム追加時はデフォルト値を設定すること（ダウンタイムゼロ対応）
- インデックス作成は
CONCURRENTLYオプションを使用すること（PostgreSQL） - 破壊的変更（カラム削除等）は2段階に分けること:
- まずカラムを nullable にする
- 次のリリースで実際に削除する
### 実行例
```bash
# スキーマファイルを編集後
claude /gen-migration
# 期待される出力:
# migrations/20260320100000_add_user_preferences_table.sql が生成されました
# ロールバック用SQLも含まれています
実践3：Explore エージェントを活用したリサーチスキル
3つ目は、context: fork と Explore エージェントを組み合わせた高度なスキルです。コードベースを自動的にリサーチし、アーキテクチャドキュメントを生成します。
SKILL.md
---
name: arch-doc
description: "コードベースを分析し、アーキテクチャドキュメントを自動生成する"
agent: "explore"
context: fork
allowed-tools:
- Read
- Glob
- Grep
---
# アーキテクチャドキュメント生成
このスキルは Explore エージェントとして実行されます。コードベースを読み取り専用で分析し、以下の情報を収集してください。
## 収集する情報
### 1. プロジェクト構造
- ディレクトリ構成とその目的
- 主要なエントリーポイント
- ビルドシステムの構成
### 2. 依存関係マップ
- 外部パッケージの一覧と用途
- 内部モジュール間の依存関係
- 循環依存の有無
### 3. APIエンドポイント一覧
- ルーティング定義の場所
- 各エンドポイントの HTTP メソッドとパス
- 認証・認可の有無
### 4. データモデル
- データベーススキーマまたは型定義
- リレーションシップ
- バリデーションルール
## 出力フォーマット
Markdown 形式で以下の構造で出力してください。
```markdown
# [プロジェクト名] アーキテクチャドキュメント
## 概要
（プロジェクトの目的と技術スタックの要約）
## ディレクトリ構成
（ツリー形式で主要ディレクトリを説明）
## 主要コンポーネント
（各コンポーネントの責務と相互関係）
## API エンドポイント
（テーブル形式で一覧化）
## データモデル
（ER図的な記述またはテーブル形式）
## 依存関係
（主要な外部ライブラリとその用途）分析対象が大規模な場合は、主要なモジュールに絞って深く分析してください。
### `context: fork` の仕組み
`context: fork` を指定すると、スキルの内容がそのまま Explore エージェントのタスクとして実行されます。Explore エージェントは読み取り専用のツール（`Read`、`Glob`、`Grep`）に最適化されており、コードベースの調査に特化しています。
通常のスキルとの違いは以下の通りです。
| 特性 | 通常のスキル | fork スキル |
|---|---|---|
| 実行コンテキスト | メインセッション | 独立したサブエージェント |
| ファイル書き込み | 可能 | 不可（読み取り専用） |
| 実行速度 | 標準 | 高速（軽量エージェント） |
| 用途 | ファイル生成・編集 | 調査・分析・レポート |
## コンテキスト注入の高度なテクニック
コンテキスト注入はスキルの強力な機能の1つです。スキル実行時に外部データを自動的に取り込むことで、毎回の手動入力を省略できます。
### シェルコマンドによる動的コンテキスト
```yaml
context:
# 現在のブランチ情報
- type: shell
command: "git branch --show-current"
# 直近のコミットログ
- type: shell
command: "git log --oneline -5"
# テスト結果のサマリー
- type: shell
command: "npm test -- --reporter=dot 2>&1 | tail -5"
# 環境変数（秘密情報は含めないこと）
- type: shell
command: "echo NODE_ENV=$NODE_ENV"
ファイルによる静的コンテキスト
context:
# プロジェクトのコーディング規約
- type: file
path: "docs/coding-standards.md"
# API仕様書
- type: file
path: "openapi.yaml"
# チームのレビュー基準
- type: file
path: ".claude/skills/review/criteria.md"注意点
シェルコマンドのコンテキスト注入には重要な制約があります。
- 実行時間: コマンドはスキル起動時に同期的に実行されます。重い処理はスキルの起動を遅延させます
- セキュリティ: 秘密情報を出力するコマンドは絶対に含めないでください
- 冪等性: コマンドは副作用のない読み取り専用のものにしてください
- エラー処理: コマンドが失敗した場合、空文字列が注入されます
スキルのテストとデバッグ
手動テスト
最もシンプルなテスト方法は、スキルを直接呼び出してその出力を確認することです。
# スキルが認識されているか確認
claude /help
# スキルを実行（デバッグ出力付き）
claude --verbose /smart-reviewテストケースの作成
本格的なテストには、テスト用のリポジトリを作成し、既知の問題を含むコードで動作確認を行います。
# テスト用ディレクトリの作成
mkdir -p /tmp/skill-test && cd /tmp/skill-test
git init
# 意図的にセキュリティ問題を含むファイルを作成
cat > test.js << 'EOF'
const password = "hardcoded-secret-123";
const query = `SELECT * FROM users WHERE id = ${userId}`;
console.log(password);
EOF
git add test.js
# スキルを実行して結果を確認
claude /smart-review
# 期待: セキュリティの Critical が3件検出されるよくあるエラーと対処法
スキルが認識されない場合:
# ディレクトリ構造の確認
find .claude/skills -name "SKILL-md" -type f
# フロントマターの YAML 構文チェック
head -20 .claude/skills/my-skill/SKILL.mdYAML フロントマターが正しく --- で囲まれているか確認してください。インデントにタブ文字が混入していると解析に失敗します。
コンテキスト注入が空になる場合:
シェルコマンドの出力を直接ターミナルで確認してください。
# コンテキストコマンドの動作確認
git diff --staged --statコマンドが空の出力を返す場合、スキルに渡されるコンテキストも空になります。
allowed-tools で制限したツールが使えない場合:
ツール名は正確に指定する必要があります。read ではなく Read、bash ではなく Bash のように、先頭が大文字です。
パフォーマンスとセキュリティの考慮事項
パフォーマンス最適化
スキルの応答速度を改善するための指針です。
- コンテキストの最小化: 必要な情報のみを注入します。大きなファイルを丸ごと注入するとトークン消費が増え、応答が遅くなります
- allowed-tools の制限: 不要なツールを除外すると、Claude の判断コストが下がります
- fork エージェントの活用: 読み取り専用の調査タスクは
context: forkで Explore エージェントに委譲する方が高速です - シェルコマンドの高速化: パイプラインで必要な部分のみ抽出する（例:
| head -20、| grep -m 5）
セキュリティのベストプラクティス
- 秘密情報の排除:
.envファイルや API キーをコンテキストに含めない - 実行権限の制限: 破壊的な操作を行うスキルには
allowed-toolsで書き込み系ツールのみを許可する - 入力のバリデーション: ユーザー入力をシェルコマンドに渡す場合は、エスケープ処理を行う
- Git 管理: プロジェクトスコープのスキルは必ず Git で管理し、変更履歴を追跡する
スキルの配布と共有
チーム内での共有
プロジェクトスコープのスキルは .claude/skills/ ディレクトリに配置するだけで、リポジトリをクローンした全メンバーが利用できます。
# .gitignore にスキルが除外されていないか確認
grep -r "\.claude" .gitignore
# スキルをコミット
git add .claude/skills/
git commit -m "Add smart-review skill for team code reviews"スキルマーケットプレイスへの公開
Claude Code はスキルマーケットプレイスをサポートしており、作成したスキルを他のユーザーと共有できます。
# スキルのパッケージ化（.skill ファイルの作成）
cd .claude/skills/smart-review
zip -r smart-review.skill SKILL.md review-rules.mdマーケットプレイスに公開する際は、以下の点に注意してください。
descriptionフィールドを明確に記述する（検索でヒットしやすくなる）README.mdを追加して使い方を説明する- 必要な前提条件（ツール、言語、フレームワーク）を明記する
全体を振り返ってと次のステップ
ここではClaude Code のカスタムスキル開発について、アーキテクチャの理解から3つの実践的なスキルの構築、テスト手法、配布方法までを解説しました。
スキルは「指示書」であり「会話」ではありません。命令形で具体的な手順を記述し、出力フォーマットを明確に指定することが、高品質なスキル開発の鍵です。
さらに深く学びたい方は、以下の記事も参考にしてください。
- Claude Code Hooks で開発ワークフローを自動化する — Git コミット時やファイル保存時に自動でスキルを発動する方法
- Claude Code マルチエージェント高度活用術 — エージェントチームとサブエージェントの使い分け
- Claude Code Worktree 完全ガイド — 並列開発とスキルの組み合わせパターン
スキルとサブエージェントの境界線を考える際の整理に使えます。