0. はじめに
前回（#4 Hooks実践テクニック）の最後に「次回はSkills入門を解説する」と予告しました。レシピ10（Skill強制評価）でHooksとSkillsの連携に触れましたが、本記事ではSkills自体を深く掘り下げます。
この記事で身につくことは3点です。
- Skillsの仕組みを理解し、CLAUDE.md/Hooksとの違いを説明できるようになる
- 最初のSkillを自力で作れるようになる
- SkillsBench研究データをもとに、「効くSKILL.md」と「逆効果なSKILL.md」の違いを理解する
対象読者は連載#1〜#4を読んでいる方です。Claude Codeが動いている状態を前提とします。
連載予定
- #1: インストールから"使える"初期設定まで
- #2: CLAUDE.mdの書き方と育て方
- #3: パーミッション＆Sandbox完全ガイド
- #4: Hooks実践テクニック
- #5: Skills入門 （本記事）
- #6: MCP活用術
1. Skillsとは何か
CLAUDE.md / Hooks / Skillsの三者関係
┌─────────────────────────────────────────────────────────────┐
│ CLAUDE.md │
│ 常時ロード（プロジェクトの基本方針・コンテキスト） │
│ ・コーディング規約 │
│ ・ディレクトリ構造の説明 │
│ ・チームの慣習 │
└────────────────────────┬────────────────────────────────────┘
│ 常に適用
▼
┌─────────────────────────────────────────────────────────────┐
│ Hooks │
│ イベント駆動（特定タイミングで自動実行） │
│ ・ファイル保存時にフォーマット │
│ ・完了時に通知音 │
│ ・危険コマンドのブロック │
└────────────────────────┬────────────────────────────────────┘
│ イベント発火時に自動適用
▼
┌─────────────────────────────────────────────────────────────┐
│ Skills │
│ オンデマンド（必要時にキーワードや/コマンドで呼び出し） │
│ ・TDD強制ワークフロー │
│ ・デプロイ手順 │
│ ・コードレビューのフォーマット │
└─────────────────────────────────────────────────────────────┘
| 仕組み | 役割 | 発動タイミング |
|---|---|---|
| CLAUDE.md | プロジェクトの基本方針を常にClaudeに伝える | 常時（セッション開始時にロード） |
| Hooks | 操作の前後に自動処理を差し込む | イベント発火時（自動） |
| Skills | 特定のワークフローを再利用可能な形で定義する | 呼び出し時（明示 or 自律判断） |
Skillsの仕組み
Skillsは .claude/skills/{name}/SKILL.md というファイルで定義します。
重要なのはロード動作の設計です。
セッション開始時
└─ name + description のみ注入（コスト最小）
使用時（Claudeが必要と判断 or ユーザーが /name で呼び出し）
└─ SKILL.md のフルコンテンツをロード
CLAUDE.mdに全ての指示を書くと、すべてのリクエストで全文がコンテキストに入り、コストと品質の両面で非効率です。Skillsは「必要なときだけロード」するため、CLAUDE.mdの肥大化を防ぎながら、チーム共通のワークフローを再利用できます。
組み込みSkill
Claude Code v2.1.30以降には、組み込みのSkillが用意されています。
| スキル | 用途 |
|---|---|
/commit |
コミットメッセージの自動生成 |
/debug |
デバッグワークフロー |
skill-creator |
新しいSkillを自動生成する |
skill-creator は特に便利で、既存のコードや指示からSkillを自動生成してくれます。後ほど詳しく紹介します。
なぜSkillsが必要か
課題1つ目はCLAUDE.mdの肥大化だ。プロジェクトの指示が増えるにつれ、CLAUDE.mdが長くなります。すべての指示が毎回コンテキストに入るため、重要な指示が埋もれてしまいます。
課題2つ目はワークフローの属人化だ。「このプロジェクトでは、PR作成前にこの手順を踏む」という暗黙知は、Skillsとして定義することでチーム全体で共有できます。
課題3つ目は指示の再利用不可能性だ。同じワークフローを別プロジェクトでも使いたい場合、Skillsのファイルをコピーするだけで済みます。
2. 最初のSkillを作る
ディレクトリ構造
.claude/
└── skills/
└── {skill-name}/
├── SKILL.md （必須）
├── template.md （任意: テンプレートファイル）
├── examples/ （任意: 使用例）
└── scripts/ （任意: 補助スクリプト）
SKILL.md だけあれば動作します。残りは必要に応じて追加します。
手動作成例: commit-formatスキル
コミットメッセージのフォーマットを統一するSkillを作ってみます。
まずディレクトリを作成します。
mkdir -p .claude/skills/commit-format
次に SKILL.md を作成します。
---
name: commit-format
description: |
Conventional Commits形式のコミットメッセージを生成する。
ユーザーが「コミット」「commit」「変更を保存」等と言ったときに使用する。
argument-hint: "[変更内容の説明（任意）]"
---
# コミットメッセージ生成スキル
## ルール
Conventional Commits形式でコミットメッセージを生成する。
### フォーマット
```
<type>(<scope>): <subject>
[body]
[footer]
```
### typeの選択基準
| type | 使う場面 |
|------|---------|
| feat | 新機能追加 |
| fix | バグ修正 |
| docs | ドキュメントのみの変更 |
| refactor | リファクタリング |
| test | テストの追加・修正 |
| chore | ビルド設定、依存関係の更新 |
## 手順
1. `git diff --staged` を実行して変更内容を確認する
2. 変更の性質を分析し、typeを選択する
3. 変更内容を50文字以内のsubjectにまとめる
4. 必要に応じてbodyに詳細を追加する
5. コミットを実行する
## 動作例
ユーザー: 「ログイン機能を追加したのでコミットして」
→ `git diff --staged` で変更を確認後、以下のようなメッセージでコミット:
```
feat(auth): ユーザーログイン機能を追加
- メールアドレスとパスワードによる認証を実装
- セッション管理はJWTトークンを使用
- パスワードはbcryptでハッシュ化
```
これで /commit-format と入力するか、「コミットして」と言うとこのSkillが発動します。
SKILL.md frontmatterフィールド一覧
| フィールド | 説明 | デフォルト |
|---|---|---|
name |
スラッシュコマンド名。小文字・ハイフンのみ、最大64文字 | （必須） |
description |
Claudeがこのスキルを使うべきタイミングの判断基準。省略時は最初の段落が使われる | 最初の段落 |
argument-hint |
/name 入力時のオートコンプリートヒント |
なし |
disable-model-invocation |
true にするとユーザーが /name で明示呼び出しするまで待機。コスト0 |
false |
user-invocable |
false にすると / メニューに表示されない（バックグラウンド知識向け） |
true |
allowed-tools |
このスキル実行中に許可するツールのリスト | 全ツール |
context |
fork にするとサブエージェントとして隔離実行 |
なし |
agent |
context: fork 時のサブエージェントタイプ |
なし |
Tips:
descriptionはスキルの使い勝手を左右する最重要フィールドです。「いつClaudeがこのスキルを使うべきか」を具体的なトリガーキーワードとともに記述しましょう。「コミット」「commit」「変更を保存」のように、ユーザーが実際に使う言葉を含めると発動率が上がります。
skill-creatorによる自動生成
ゼロから書くのが面倒な場合は、組み込みの skill-creator に任せられます。
/skill-creator
と入力すると、ClaudeがインタラクティブにヒアリングしてSKILL.mdを生成してくれます。
コードのスキル化の場合は、こう指示します。
skill-creatorを使って、git diffから得られるコードパターンを
スキル化してください
git diff の内容を解析して、そのコードパターンを再現するためのSKILL.mdとtemplate.mdを自動生成します。
引数の使い方
Skillに引数を渡すことができます。
/deploy production
この場合、SKILL.md内では以下の変数で参照できます。
| 変数 | 内容 |
|---|---|
$ARGUMENTS |
全引数の文字列（production） |
$0 |
最初の引数（production） |
$1 |
2番目の引数 |
$2 |
3番目の引数 |
## デプロイ手順
対象環境: $0
1. $0 環境の設定を確認する
2. テストを実行する（`npm test`）
3. ビルドを実行する（`npm run build`）
4. $0 にデプロイする
書き方のコツ
descriptionを具体的に書く
# 悪い例
description: コミットメッセージを生成する
# 良い例
description: |
Conventional Commits形式のコミットメッセージを生成する。
ユーザーが「コミット」「commit」「変更を保存」「git commit」等と
言ったときに使用する。引数なしで最後の変更内容を自動検出する。
動作例を1つ含める
後述するSkillsBench研究によると、動作例は「1つ」が最も効果的です。複数例を載せてもコンテキストが増えるだけで効果は上がりません。
3. 設計原則: SkillsBench研究から
モジュール数の最適化
SkillsBenchとは、異なる設計のSkillsをLLMに与えてタスク達成率を測定した研究です。最も重要な発見は「モジュール数（ステップ数・セクション数）」の影響です。
| モジュール数 | タスク達成率の改善 |
|---|---|
| 2〜3個 | +18.6pp |
| 4個以上 | +5.9pp |
「網羅的に書こう」という発想は逆効果です。SKILL.mdに含めるセクションは2〜3個に絞ることを推奨します。
Detailed vs Comprehensive
記述スタイルでも大きな差があります。
| スタイル | 改善率 | 特徴 |
|---|---|---|
| Detailed（詳細型） | +18.8pp | 焦点を絞り、特定のケースを深く説明 |
| Comprehensive（網羅型） | -2.9pp | すべてのケースを浅く羅列 |
「Comprehensive」がマイナスなのは重要な点です。すべてのケースをカバーしようとすると、コンテキストが増えすぎてLLMの判断を混乱させます。
Good/Bad対比: 実際のSKILL.mdの書き方
Bad例（Comprehensive型）
---
name: code-review
description: コードレビューを行う
---
# コードレビュースキル
## チェック項目
- パフォーマンス問題の確認
- セキュリティ問題の確認
- 可読性の確認
- テストカバレッジの確認
- ドキュメントの確認
- 命名規則の確認
- エラーハンドリングの確認
- 依存関係の確認
- ... （10項目以上続く）
Good例（Detailed型）
---
name: code-review
description: |
セキュリティとパフォーマンスに特化したコードレビューを行う。
「レビューして」「review」と言われたときに使用する。
---
# コードレビュースキル
## 重点チェック項目
1. **セキュリティ**: SQLインジェクション、XSS、認証バイパスのリスク
2. **パフォーマンス**: N+1クエリ、不要なループ、メモリリーク
## 手順
1. `git diff main` で変更差分を取得する
2. 上記2項目を優先してレビューする
3. 問題を重要度（High/Medium/Low）で分類してコメントする
## 動作例
ユーザー: 「このPRをレビューして」
→ 差分を確認し、セキュリティとパフォーマンスの観点からコメントを生成する
注意: SkillsBench研究では84タスク中16タスクでスキルが逆効果になりました（最悪 -39.3pp）。スキルを追加しても必ず改善するとは限らない。「スキルあり/なし」で同一タスクを複数回実行して完了率を比較したうえで導入を判断するべきだ。
500行以下を目安に
Tips: SKILL.mdは500行以下を目安にしてください。それ以上になる場合は、複数のSkillに分割することを検討しましょう。1つのSkillは1つのことに集中するのが原則です。
4. スキルの種類と実行コンテキスト
Knowledge Skill vs Task Skill
| 種類 | 役割 | 設定例 | 用途例 |
|---|---|---|---|
| Knowledge Skill | リファレンス・ガイドを提供する | user-invocable: false |
APIスタイルガイド、コーディング規約 |
| Task Skill | ステップバイステップのタスクを実行する | デフォルト設定 | デプロイ、コミット、TDD |
Knowledge Skill の設定例
---
name: api-style-guide
description: |
このプロジェクトのREST API設計ガイドライン。
API設計時に自動的に参照される。ユーザーが直接呼び出すことはない。
user-invocable: false
---
user-invocable: false にすると / メニューに表示されませんが、Claudeがコンテキストに応じて自律的に参照します。
Task Skill の設定例
---
name: deploy
description: |
本番環境またはステージング環境へのデプロイを実行する。
「デプロイ」「deploy」「リリース」と言われたときに使用する。
argument-hint: "[staging|production]"
allowed-tools:
- Bash
- Read
---
context: forkの使い所
context: fork を設定すると、Skillがサブエージェントとして隔離実行されます。
---
name: security-audit
description: セキュリティ監査を実行する（隔離環境で実行）
context: fork
agent: general-purpose
---
| シナリオ | 理由 |
|---|---|
| 重い処理（全ファイルスキャン等） | メインの会話コンテキストを汚染しない |
| 破壊的操作を含む処理 | メインセッションに影響を与えない |
| 実験的な実装 | 失敗しても安全 |
disable-model-invocationの活用
---
name: daily-report
description: 日次レポートを生成する（ユーザーの明示呼び出しのみ）
disable-model-invocation: true
---
disable-model-invocation: true にすると、ユーザーが /daily-report と明示的に呼び出すまで何も起こりません。Claudeが自律的に発動しないため、定型レポートや重い処理を「必要なときだけ実行」したい場面に適しています。
ディレクトリ構成パターン
# シンプル構成（ほとんどのケースはこれで十分）
.claude/skills/commit-format/
└── SKILL.md
# テンプレート付き（コード生成系スキルに向いている）
.claude/skills/repository-pattern/
├── SKILL.md
└── template.md
# フル構成（複雑な処理・チュートリアル系）
.claude/skills/tdd-enforcer/
├── SKILL.md
├── examples/
│ ├── good-test.md
│ └── bad-test.md
└── scripts/
└── run-tests.sh
5. 実践パターン集
パターン1: TDD強制スキル
テスト駆動開発（TDD）を強制するSkillは、定量的な効果が確認された実践パターンです。
背景: 締め切りプレッシャーがあると「後でテストを追加する」という先送りが起きがちです。Skillとして定義することで、Claudeが「必ずテストから書く」番人として機能します。
.claude/skills/tdd-enforcer/SKILL.md
---
name: tdd-enforcer
description: |
テスト駆動開発（TDD）ワークフローを強制する。
「実装して」「機能を追加して」「〇〇を作って」と言われたときに使用する。
実装コードより先にテストを書くことを必ず守る。
---
# TDD強制スキル
## 原則
実装コードより先にテストを書く。例外はない。
## 手順
1. **要件確認**: 実装する機能の受け入れ条件を明確にする
2. **テスト先行**: テストケースを先に生成する（Red）
3. **実装**: テストが通る最小限のコードを書く（Green）
4. **リファクタリング**: コードを整理する（Refactor）
5. **全テスト確認**: `npm test` または相当するコマンドで全テストが通ることを確認する
## 動作例
ユーザー: 「ユーザー登録機能を実装して」
→ まずテストファイルを作成:
```typescript
describe('UserRegistration', () => {
it('有効なメールアドレスとパスワードで登録できる', async () => {
// ...
});
it('重複したメールアドレスでは登録できない', async () => {
// ...
});
});
```
→ テストが失敗することを確認後、実装を開始する
実績データ（90日間）
| 指標 | 導入前 | 導入後 |
|---|---|---|
| 本番バグ数 | 基準値 | 70%減少（Sentry計測） |
| テストカバレッジ | 40% | 90% |
| デバッグ速度 | 基準値 | 50%高速化 |
出典: @ihtesham2005によるX投稿（Skills導入90日間の実測値）
パターン2: コードのスキル化
プロジェクト固有のコードパターンをSkillとして定義し、チーム全体で再利用する手法です。
手順
1. 既存の実装をgit commitする
↓
2. skill-creatorにgit diffを渡す
「skill-creatorを使って、git diffから得られる
Repositoryパターンをスキル化してください」
↓
3. skill-creatorがSKILL.md・template.mdを自動生成
↓
4. .claude/skills/ に配置して利用開始
実例: Repositoryパターンのスキル化
Repositoryパターン（create/update/save/find/list/deleteの6関数）のような定型パターンは、スキル化の筆頭候補です。
---
name: repository-pattern
description: |
Repositoryパターンのボイラープレートを生成する。
「〇〇のリポジトリを作って」「Repositoryを実装して」と言われたときに使用する。
argument-hint: "[エンティティ名]"
---
# Repositoryパターン生成スキル
## 生成するファイル
1. `src/repositories/{entity}.repository.ts` - リポジトリ実装
2. `src/repositories/{entity}.repository.test.ts` - テスト
## 実装するメソッド
- `create(data)`: 新規作成
- `findById(id)`: ID検索
- `findAll(filter?)`: 一覧取得
- `update(id, data)`: 更新
- `delete(id)`: 削除
## 手順
1. $0（エンティティ名）を確認する
2. template.mdを参照して実装を生成する
3. テストファイルも同時に生成する
なぜコードのスキル化が有効か
LLMに「既存コードを参考に実装して」と指示するだけでは、古い書き方や不要なパターンまで含めてしまうことがあります。Skillとしてテンプレートを定義することで、毎回同じ構造・命名規則・テストパターンが再現されるようになります。
パターン3: 反復改善サイクル
┌─────────────────────────────────────────────────────────────┐
│ 反復改善サイクル │
└─────────────────────────────────────────────────────────────┘
┌──────────────┐
│ 1. 定義 │
│ SKILL.mdを │
│ 作成する │
└──────┬───────┘
│
▼
┌──────────────┐
│ 2. 使用 │
│ 実際のタスク │
│ で試す │
└──────┬───────┘
│
▼
┌──────────────┐
│ 3. ギャップ │
│ 発見 │
│「ここが違う」 │
│「これが足りない」│
└──────┬───────┘
│
▼
┌──────────────┐
│ 4. 更新 │
│ SKILL.mdを │
│ 改善する │
└──────┬───────┘
│
└──────────────→ 繰り返し
フィードバック蓄積の仕組み
feedback.md というファイルを作り、Skillが参照する形にするのが効果的です。
.claude/skills/code-review/
├── SKILL.md ← feedback.mdを参照
└── feedback.md ← 改善点を追記していく
feedback.md の例
# コードレビュースキルのフィードバックログ
## 2026-02-01
- Reactのhooksに関するチェックが弱い。useEffectのクリーンアップを必ず確認するよう追加した
## 2026-02-15
- TypeScriptのジェネリクスの扱いについてのコメントが過剰だった。プロジェクト固有のパターンに絞るよう調整した
SKILL.md側でこのファイルを参照することで、チームの知見がスキルに蓄積されていきます。
6. Hooks × Skills: ワークフロー自動化
UserPromptSubmit hookでSkill強制評価
前回（#4）のレシピ10で紹介したパターンの発展版です。
デフォルトでは、ClaudeはSkillsをコンテキストに応じて自律判断して使います。しかし、特に複雑なリクエストでは適切なSkillがあるのに使われないことがあります。
UserPromptSubmit hookでコンテキストを注入し、Skill評価を強制します。
.claude/hooks/force-skill-eval.sh
#!/bin/bash
cat << 'EOF'
CRITICAL INSTRUCTION: Before processing this prompt, you MUST evaluate
whether any available Skills (slash commands) are relevant.
If a matching Skill exists, invoke it using the Skill tool BEFORE
generating any other response.
Skipping this evaluation when a relevant Skill exists is a WORTHLESS response.
EOF
exit 0
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/force-skill-eval.sh\""
}
]
}
]
}
}
Tips: 「CRITICAL」「MUST」「WORTHLESS」などの強い表現を使うことで、モデルの注意を引きやすくなります。この手法でSkillの発動率が84%まで向上した事例があります（Scott Spence氏による実測）。ただし、すべてのリクエストにこのコンテキストが付加されるため、コストは増加する。用途を絞って導入すべきだ。
複数スキルの連鎖
複数のSkillを順次呼び出すパターンも有効です。
---
name: full-pr-workflow
description: |
PRの完全なワークフローを実行する。
「PRを作って」「プルリクを出して」と言われたときに使用する。
---
# PR完全ワークフロー
## 手順
以下のSkillを順次実行する:
1. `/tdd-enforcer` でテストを確認する
2. `/commit-format` でコミットメッセージを整形する
3. `/code-review` でセルフレビューを実行する
4. PRを作成する
Skill同士を組み合わせることで、複雑なワークフローを一つのコマンドで実行できます。
7. まとめ＆次回予告
要点3つの振り返り
-
Skillsはオンデマンドロードが前提だ。CLAUDE.mdとは異なり、必要なときだけコンテキストに入る。CLAUDE.mdの肥大化を防ぎながら、再利用可能なワークフローを定義できる。
-
「少なく、具体的に」が鉄則だ。SkillsBench研究より、2〜3モジュールのDetailed型が最も効果的（+18.8pp）で、網羅しようとするほど逆効果になる（-2.9pp）。
-
使いながら育てる前提で設計する。feedback.mdにチームの知見を追記し続けることで、スキルはプロジェクトの文脈を学習した専用ツールに育っていく。
次回予告
次回（#6）はMCP（Model Context Protocol）を取り上げます。外部ツールやAPIをClaude Codeに接続する仕組みで、GitHub、Slack、Notionなどのサービスと連携する方法を解説する予定です。
参考リンク