第4章：SKILLSアプローチ ― AIに専門知識を与える

はじめに：なぜSKILLSが生まれたのか

前章で学んだワークフローを実践していると、ある問題にぶつかることがあります。

「毎回、同じような説明を繰り返している気がする...」

たとえば、あなたのプロジェクトでは常に特定のコーディング規約を守る必要があるとします。TypeScriptではanyを使わずunknownを使う、Reactコンポーネントは特定のディレクトリ構造に従う、APIレスポンスは必ず特定の形式で返す、といった具合です。

これらのルールを、タスクごとにClaudeに説明するのは面倒ですし、説明し忘れると意図しないコードが生成されてしまいます。

SKILLSは、この問題を解決するためにAnthropicが2025年に導入した機能です。

SKILLSを一言で説明すると、Claude Codeに「専門知識」を教え込む仕組みです。あなたのプロジェクト固有のルール、設計パターン、ベストプラクティスをファイルとして記述しておけば、Claudeは必要なときにそれを参照し、適切なコードを生成してくれます。

SKILLSの基本概念

SKILLSとは何か

SKILLSは、指示（Instructions）、スクリプト（Scripts）、リソース（Resources）の集合体です。

従来のCLAUDE.mdファイルが「プロジェクト全体に適用される一般的な指示」だとすれば、SKILLSは「特定のタスクや領域に特化した専門知識」を提供します。

たとえば：

• CLAUDE.md: 「このプロジェクトはTypeScriptを使っている」「mainブランチへの直接プッシュは禁止」
• SKILLS: 「React Queryを使ったデータフェッチの正しいパターン」「このプロジェクトのエラーハンドリング設計」「テストの書き方とカバレッジ基準」

CLAUDE.mdがすべてのセッションで常に参照されるのに対し、SKILLSは必要なときだけ参照されます。これが「段階的開示（Progressive Disclosure）」という設計思想です。

段階的開示（Progressive Disclosure）

SKILLSの最も重要な設計思想は段階的開示です。

Claude Codeにはコンテキストウィンドウという制約があります。これは、Claudeが一度に「覚えていられる」情報量の上限です。この制約があるため、すべての情報を最初から読み込ませると、肝心なときに情報が溢れてしまいます。

SKILLSは、この問題を3層構造で解決します：

第1層：インデックス（常に読み込み）

• 全スキルの「名前」と「説明」だけを読み込む
• 1スキルあたり約100トークンと軽量
• Claudeは「どんなスキルがあるか」を把握

第2層：本文（必要時に読み込み）

• タスクに関連するスキルが選択されたとき、SKILL.md本文を読み込む
• 具体的な指示、サンプルコード、ガイドラインが含まれる

第3層：追加リソース（必要時に参照）

• スクリプトファイル、テンプレート、参照用コードなど
• SKILL.mdから参照される補助ファイル

この設計により、コンテキストウィンドウを効率的に使いながら、必要な専門知識を必要なときに提供できます。

SKILL.mdファイルの書き方

ファイルの構造

SKILL.mdファイルは、YAML Frontmatterと本文の2つの部分で構成されます。

---
name: react-query-patterns
description: React Queryを使ったデータフェッチのベストプラクティス。API呼び出し、キャッシュ戦略、エラーハンドリングのパターンを提供。
allowed-tools: Read, Write, Edit, Grep, Glob
model: claude-sonnet-4-20250514
---

# React Query パターン

## When to Use
このスキルは以下の場合に使用してください：
- 新しいAPI呼び出しを実装するとき
- データキャッシュの設計を検討するとき
- React Queryに関連するバグを修正するとき

## Core Patterns

### クエリの基本形
[サンプルコードと説明]

### ミューテーションの基本形
[サンプルコードと説明]

## Anti-Patterns

### やってはいけないこと
[アンチパターンの例と理由]

## Guidelines
- キャッシュキーは必ず定数で定義する
- エラーハンドリングはグローバルに設定する
- 楽観的更新は慎重に使用する

YAML Frontmatterの詳細

Frontmatterには、スキルのメタデータを記述します。

必須フィールド：

オプションフィールド：

descriptionは最も重要なフィールドです。なぜなら、Claudeはこのdescriptionを読んで「このタスクにどのスキルが必要か」を判断するからです。曖昧な説明では、適切なタイミングでスキルが発動しません。

良いdescriptionの例：

description: Reactコンポーネントのユニットテストとインテグレーションテストの書き方。Jest + React Testing Libraryを使用。テストファイルの命名規則、モックの作り方、非同期処理のテスト方法を含む。

悪いdescriptionの例：

description: テストについて

本文の構成

本文は、自由形式のMarkdownで記述しますが、以下のセクションを含めることをお勧めします：

1. When to Use（使用タイミング）

スキルが適用される条件を明確に列挙します。Claudeはこのセクションを読んで、スキルを適用すべきかどうかを判断します。

## When to Use
- ユーザー認証に関する機能を実装するとき
- JWTトークンの生成・検証を行うとき
- OAuth連携を実装するとき
- セッション管理のコードを書くとき

2. Core Patterns（基本パターン）

このスキルで最も重要な実装パターンを示します。サンプルコードを含め、コピー&ペーストで使える形式にするのがベストです。

## Core Patterns

### JWT認証ミドルウェア

\`\`\`typescript
import { NextFunction, Request, Response } from 'express';
import jwt from 'jsonwebtoken';

export const authMiddleware = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  const token = req.cookies.accessToken;
  
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};
\`\`\`

このパターンを使用するときは：
- 環境変数`JWT_SECRET`が設定されていることを確認
- `req.user`の型定義を`express.d.ts`に追加
- HTTPOnly Cookieからトークンを取得（XSS対策）

3. Anti-Patterns（アンチパターン）

やってはいけないことを明示します。Claudeは「何をすべきか」だけでなく「何をすべきでないか」も知る必要があります。

## Anti-Patterns

### ❌ トークンをLocalStorageに保存しない

\`\`\`typescript
// 悪い例 - XSS攻撃に脆弱
localStorage.setItem('token', token);
\`\`\`

理由：LocalStorageはJavaScriptからアクセス可能なため、XSS攻撃でトークンが盗まれる可能性がある。

### ❌ シークレットをハードコードしない

\`\`\`typescript
// 悪い例 - シークレットがコードに含まれる
const secret = 'my-super-secret-key';
\`\`\`

理由：Gitにコミットされ、漏洩のリスクがある。

4. Guidelines（ガイドライン）

一般的な指針を箇条書きで記述します。

## Guidelines
- トークンの有効期限は15分以内に設定する
- Refresh Tokenは別のCookieに保存する
- ログアウト時はサーバー側でもトークンを無効化する
- 本番環境ではCookieにSecure属性を付ける
- CSRF対策としてSameSite属性を設定する

スキルの設置場所と有効範囲

ディレクトリ構造

スキルは2つの場所に設置できます：

グローバルスキル（全プロジェクト共通）

~/.claude/skills/
├── typescript-patterns/
│   └── SKILL.md
├── git-workflow/
│   └── SKILL.md
└── code-review/
    └── SKILL.md

グローバルスキルは、あなたが関わるすべてのプロジェクトで利用できます。言語やフレームワークに依存しない、一般的なスキルを配置するのに適しています。

プロジェクトスキル（プロジェクト固有）

my-project/
└── .claude/
    └── skills/
        ├── api-design/
        │   └── SKILL.md
        ├── database-patterns/
        │   └── SKILL.md
        └── testing-strategy/
            └── SKILL.md

プロジェクトスキルは、そのプロジェクト内でのみ有効です。プロジェクト固有の設計パターンやビジネスロジックのルールを記述します。

スキルの優先順位

同じ名前のスキルがグローバルとプロジェクトの両方にある場合、プロジェクトスキルが優先されます。

これにより、グローバルな基本ルールをプロジェクト固有の要件で上書きできます。たとえば、グローバルに「一般的なTypeScriptのパターン」を定義し、特定のプロジェクトで「このプロジェクト独自のTypeScriptルール」で上書きする、といった使い方ができます。

SKILLSと他ツールの類似機能

条件付きルール：AIツール間の収束

Claude CodeのSKILLSと同様に、**「ディレクトリやファイルパターンに応じて異なるルールを適用する」**という仕組みは、他の主要AIコーディングツールでも採用されています。

各ツールのアプローチ比較

Claude Code: 説明ベースの自動判定

---
description: API設計のベストプラクティス。RESTful API、認証、バリデーション
---

特徴: Claudeが作業内容を理解し、関連するSKILLを自動的に読み込む。明示的なパス指定は不要。

メリット: 柔軟で汎用的。新しいディレクトリを追加しても設定変更不要。

デメリット: 意図しないSKILLが読み込まれる可能性（稀）。

Cursor: Globパターンでの明示的指定

---
description: API Security Rules
globs: ["src/app/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

特徴: Globパターンで適用対象を明示的に指定。第5章で解説した.claude/rules/（条件付きルール）に近い。

メリット: 確実に狙った場所にのみ適用される。予測可能。

デメリット: 新しいディレクトリを追加するたびに設定が必要。

参考: Cursor Rules Documentation - .mdc形式の詳細ガイド

Gemini Code Assist: 階層的コンテキスト

my-project/
├── GEMINI.md              # プロジェクト全体のルール
├── src/
│   ├── GEMINI.md          # srcディレクトリのルール
│   └── api/
│       └── GEMINI.md      # API固有のルール

特徴: ディレクトリ階層に沿ってGEMINI.mdを配置。より具体的なルールが優先される。

メリット: ディレクトリ構造とルールが一致し、直感的。

デメリット: 多数のGEMINI.mdが散在すると管理が煩雑。

参考: Google: Gemini Code Assist agent mode

GitHub Copilot: 実験的な条件付きルール

<!-- .github/instructions/api-rules.instructions.md -->
# API Rules

This instruction applies to files in src/api/
...

特徴: ファイル名とコメントでスコープを指定（2025年時点では実験的機能）。

メリット: GitHubネイティブな配置（.github/）。

デメリット: 他ツールに比べて機能が限定的（今後の進化に期待）。

参考: GitHub Copilot: Agent-specific instructions

どのアプローチを選ぶべきか

筆者の推奨: 現時点ではClaude CodeのSKILLSが最もバランスが良いと考えています。理由は以下の通りです：

1. 自動判定の賢さ: Globパターンを書かなくても、Claudeが文脈を理解して適切なSKILLを読み込む
2. 拡張性: プロジェクトが成長しても、SKILLの追加だけで対応できる（設定ファイルの肥大化を避けられる）
3. 他ツールとの共存: .claude/skills/は他ツールと干渉しないため、Cursorの.cursor/rules/やGeminiのGEMINI.mdと併用可能

ただし、複数のAIツールを併用する場合は、以下のハイブリッドアプローチが現実的です：

my-project/
├── CLAUDE.md              # 基本ルール（Claude/Copilot/Gemini共通）
├── .claude/skills/        # Claude固有の詳細スキル
├── .cursor/rules/         # Cursor用の条件付きルール
└── GEMINI.md              # Gemini用のプロジェクト指示（CLAUDE.mdへのシンボリックリンクも可）

参考リソース

• Cursor Rules Community Collection - 879個の.mdcルール集
• Cursor Rules Generator - .cursorrules / .mdcの自動生成ツール
• AGENTS.md公式サイト - オープンなAI指示ファイル標準

実践：スキルの作成ワークフロー

ステップ1：必要なスキルを特定する

まず、「繰り返し説明していること」を洗い出します。

開発を進める中で、以下のような状況がないか確認してください：

• 「またこのパターンを説明しないといけない...」
• 「前にも同じミスを指摘した気がする...」
• 「このプロジェクトの特殊なルールを毎回伝えるのが面倒...」

これらがスキル化の候補です。

ステップ2：スキルの骨格を作る

Claudeにスキルの骨格を作らせることもできます：

あなた：このプロジェクトのエラーハンドリングパターンを
       スキルとして文書化したい。
       
       現在のコードベースを分析して、
       一貫したエラーハンドリングのパターンを見つけて、
       SKILL.mdのドラフトを作ってくれ。

Claudeは既存のコードを分析し、パターンを抽出してSKILL.mdを生成してくれます。ただし、生成された内容は必ず人間がレビューし、必要に応じて修正してください。

ステップ3：段階的に改善する

スキルは一度作ったら終わりではありません。使っていく中で「これも追加した方がいい」「この説明は分かりにくい」といった改善点が見つかるはずです。

スキルファイルもプロジェクトのコードと同様に、Gitで管理し、継続的に改善していきましょう。

ステップ4：スキルをテストする

スキルが正しく機能するか、実際にタスクを投げてテストします：

あなた：新しいAPIエンドポイントを実装してほしい。
       /api/users/:id/profile を作ってくれ。
       
       [Claudeがスキルを適用して実装]

あなた：今の実装で、エラーハンドリングのスキルは
       正しく適用されてる？確認してくれ。

スキルが期待通りに適用されていない場合は、descriptionやWhen to Useセクションを見直してください。

高度なスキルの活用

複数ファイルで構成されるスキル

複雑なスキルは、SKILL.mdに加えて補助ファイルを持つことができます：

.claude/skills/api-design/
├── SKILL.md
├── templates/
│   ├── controller.ts.template
│   ├── service.ts.template
│   └── repository.ts.template
├── examples/
│   ├── simple-crud.ts
│   └── complex-transaction.ts
└── scripts/
    └── generate-api.sh

SKILL.mdから補助ファイルを参照する例：

## Templates

新しいAPIエンドポイントを作成するときは、
以下のテンプレートを使用してください：

- Controller: `templates/controller.ts.template`
- Service: `templates/service.ts.template`
- Repository: `templates/repository.ts.template`

## Examples

実装例は `examples/` ディレクトリを参照してください。

スキル間の連携

スキルは独立していますが、相互に参照することもできます：

## Related Skills

このスキルを使う前に、以下のスキルも確認してください：
- `database-patterns`: データベースアクセスのパターン
- `error-handling`: エラーハンドリングの規約

このスキルの後で、以下のスキルを使用してください：
- `testing-strategy`: 実装したAPIのテスト方法

条件付きスキル適用

特定の条件でのみ適用されるスキルも作れます：

## When to Use

このスキルは以下の条件をすべて満たす場合にのみ使用してください：
- 外部APIとの連携を実装するとき
- かつ、そのAPIがレート制限を持つとき
- かつ、リトライロジックが必要なとき

単純なAPI呼び出しには使用しないでください。

よくある質問とトラブルシューティング

Q: スキルが適用されない

考えられる原因：

1. descriptionが曖昧で、Claudeが関連性を判断できない
2. When to Useセクションがタスクと合致していない
3. スキルファイルの場所が間違っている

解決策：

• descriptionをより具体的に書き直す
• タスク指示に「〇〇スキルを参照して」と明示的に指示する
• claude skills listコマンドでスキルが認識されているか確認

Q: スキル同士が矛盾する

考えられる原因： 複数のスキルに相反する指示が含まれている

解決策：

• スキルの適用範囲を明確に分離する
• 優先順位を明示的に記述する
• 必要なら統合して1つのスキルにする

Q: スキルが長すぎてコンテキストを圧迫する

考えられる原因： 1つのスキルに情報を詰め込みすぎている

解決策：

• スキルを複数に分割する
• 詳細な例は別ファイルに分離し、SKILL.mdからは参照のみ
• 本当に必要な情報だけをSKILL.mdに残す

実践例：Vercel公式SKILLSに学ぶ

本章で学んだSKILLSの設計原則が、実際のプロダクション環境でどのように活用されているか、興味はありませんか？

Vercel Engineeringチームは、React/Next.jsのパフォーマンス最適化に関する45のルールを、SKILLSとして公開しています。このスキルは、本章で解説した原則を忠実に実装した優れた実践例です。

Vercelスキルの特徴：

• 8カテゴリに分類された45のルール
• CRITICAL/HIGH/MEDIUM/LOWの優先度設計
• 個別ルールをrules/ディレクトリに分離（段階的開示）
• 悪い例と良い例の明確な対比

詳しくは関連記事「Vercel公式SKILLSを導入してみた」をご覧ください。インストール方法から具体的なルールの解説まで、実践的な内容を紹介しています。

まとめ：SKILLSの価値

SKILLSシステムの本質的な価値は、あなたの暗黙知を形式知に変えることです。

優秀な開発者の頭の中には、長年の経験から得た「こういうときはこうする」という知識が詰まっています。しかし、その知識は言語化されていないことが多く、新しいメンバーに伝えるのは難しいものです。

SKILLSは、その暗黙知をMarkdownファイルとして記述することで、Claudeという「常に学び続けるジュニアエンジニア」に伝えることができます。そして一度記述すれば、何度でも再利用できます。

次の章では、SKILLSと組み合わせて使うHooks機能と保守性・スケーラビリティについて詳しく見ていきます。品質を自動で担保する仕組みを学びましょう。