Claude Code Skills設計 — オンデマンド知識でコンテキストを節約

CLAUDE.mdに全ての設定やドメイン知識を書き込むと、コンテキストウィンドウが圧迫され、エージェントのパフォーマンスが低下する。Claude Code Skillsは、必要な時だけ読み込まれるオンデマンドの知識モジュールとして機能し、コンテキスト効率を大幅に改善する。本記事では、Skillsの設計原則からSKILL.mdの書き方、呼び出しパターンの最適化まで実践的に解説する。

Skillsとは何か

Skillsは、Claude Codeのコンテキストを拡張するモジュラーな知識ユニットである。通常のCLAUDE.mdが常にコンテキストに読み込まれるのに対し、Skillsは特定の条件やユーザーの指示でオンデマンドに読み込まれる。

CLAUDE.mdとSkillsの使い分け

項目	CLAUDE.md	Skills
読み込みタイミング	常時	オンデマンド
コンテキスト消費	常に消費	必要時のみ
用途	基本設定、共通ルール	ドメイン知識、専門手順
更新頻度	低い	中〜高い
サイズ目安	500行以下推奨	制限なし

SKILL.mdの基本構造

各Skillは .claude/skills/<skill-name>/ ディレクトリに配置する。SKILL.md がスキルの本体であり、メタデータと知識本文で構成される。

---
name: "code-review"
description: "コードレビューの実行手順と品質基準"
trigger: "when the user asks to review code or mentions code review"
---

# コードレビュースキル

## レビュー手順

1. 変更ファイルの一覧を確認する
2. 各ファイルの変更内容を読む
3. 以下の観点でレビューする:
   - セキュリティリスク
   - パフォーマンス問題
   - 可読性・保守性
   - テストカバレッジ

## 品質基準

- Critical: セキュリティ脆弱性、データ損失リスク
- Warning: パフォーマンス劣化、エラーハンドリング不足
- Info: コーディングスタイル、命名規則

メタデータフィールドの詳細

interface SkillMetadata {
  name: string;           // スキルの一意識別子
  description: string;    // スキルの説明（検索に使用）
  trigger: string;        // 自動呼び出し条件（自然言語）
  tags?: string[];        // 分類タグ
  priority?: number;      // 複数スキルが一致した場合の優先度
  "disable-model-invocation"?: boolean;  // AI自動呼び出しを無効化
}

自動呼び出しと手動呼び出し

Skillsには2つの呼び出しパターンがある。

自動呼び出し（trigger）

trigger フィールドに記述した条件に一致する入力があると、AIが自動的にスキルを読み込む。

---
trigger: "when working with database migrations or schema changes"
---

この設定では、ユーザーが「データベースのマイグレーションを作成して」と入力すると、自動的にこのスキルが読み込まれる。

手動呼び出し（スラッシュコマンド）

ユーザーがスラッシュコマンド（/skill-name）で明示的にスキルを呼び出すパターン。予測可能で確実な呼び出しが可能。

# スラッシュコマンドでスキルを呼び出し
claude> /code-review src/api/routes.ts を確認して

# スキル一覧の確認
claude> /skills

disable-model-invocationの使い分け

disable-model-invocation: true を設定すると、AIによる自動呼び出しが無効化され、手動呼び出しのみになる。

---
name: "deploy"
description: "本番デプロイの手順"
trigger: "when deploying to production"
disable-model-invocation: true
---

使い分けの指針

// 自動呼び出しに適するスキル
const autoInvokeSkills = [
  "code-review",      // コードレビュー依頼時に自動読み込み
  "testing",          // テスト作成時に自動読み込み
  "documentation",    // ドキュメント生成時に自動読み込み
];

// 手動呼び出しに適するスキル（disable-model-invocation: true）
const manualOnlySkills = [
  "deploy",           // デプロイは意図的に実行すべき
  "database-reset",   // 破壊的操作は手動トリガーのみ
  "secret-rotation",  // 機密操作は手動トリガーのみ
];

スキルの組み合わせパターン

複数のスキルを組み合わせて、複雑なワークフローを実現する設計パターン。

チェインパターン

1つのタスクで複数のスキルを順番に適用する。

// スキルチェインの定義
interface SkillChain {
  name: string;
  steps: Array<{
    skill: string;
    inputFrom?: string;
    outputTo?: string;
  }>;
}

const prReviewChain: SkillChain = {
  name: "comprehensive-pr-review",
  steps: [
    { skill: "code-review", outputTo: "codeIssues" },
    { skill: "security-review", outputTo: "securityIssues" },
    { skill: "performance-review", outputTo: "perfIssues" },
    {
      skill: "review-summary",
      inputFrom: "codeIssues,securityIssues,perfIssues",
    },
  ],
};

コンテキスト分離パターン

スキル間でコンテキストを分離し、各スキルが独立して動作するようにする。

class SkillContext {
  private contexts: Map<string, Record<string, unknown>> = new Map();

  setContext(skillName: string, data: Record<string, unknown>): void {
    this.contexts.set(skillName, data);
  }

  getContext(skillName: string): Record<string, unknown> | undefined {
    return this.contexts.get(skillName);
  }

  mergeContexts(skillNames: string[]): Record<string, unknown> {
    const merged: Record<string, unknown> = {};
    for (const name of skillNames) {
      const ctx = this.contexts.get(name);
      if (ctx) {
        Object.assign(merged, { [name]: ctx });
      }
    }
    return merged;
  }
}

コンテキスト効率の最適化

Skillsの最大の利点はコンテキスト効率の改善である。以下の指標で効果を測定する。

測定方法

interface ContextMetrics {
  baselineTokens: number;      // CLAUDE.md読み込み時のトークン数
  skillTokens: number;         // スキル読み込み時の追加トークン数
  totalContextUsed: number;    // 使用した総コンテキスト量
  contextUtilization: number;  // 有効活用率（使用量/読み込み量）
}

function measureContextEfficiency(
  withoutSkills: number,   // スキルなしの場合のCLAUDE.mdトークン数
  withSkills: number,      // スキル分離後のCLAUDE.mdトークン数
  skillsLoaded: number     // 実際に読み込まれたスキルのトークン数
): { savingsPercent: number; description: string } {
  const totalBefore = withoutSkills;
  const totalAfter = withSkills + skillsLoaded;
  const savings = ((totalBefore - totalAfter) / totalBefore) * 100;

  return {
    savingsPercent: Math.round(savings),
    description: savings > 0
      ? "コンテキスト使用量が" + Math.round(savings) + "%削減"
      : "スキルの分離効果なし（すべてのスキルが常時読み込まれている可能性）",
  };
}

スキル設計のアンチパターン

アンチパターン	問題点	解決策
巨大スキル	コンテキスト圧迫	500行以下に分割
重複コンテンツ	矛盾リスク	共通部分をCLAUDE.mdに
過剰なtrigger	不要な読み込み	条件を具体的に
依存関係の暗黙化	読み込み漏れ	明示的な依存宣言
バージョン管理なし	変更追跡不可	gitで管理

ベストプラクティス

1. CLAUDE.mdは薄く保つ: 共通ルールと基本設定のみ。ドメイン知識はSkillsに分離する
2. triggerは具体的に書く: 曖昧なtriggerは不要な読み込みを招く
3. disable-model-invocationを活用する: 破壊的操作に関するスキルは手動呼び出しのみにする
4. 定期的に使用状況を確認する: 読み込まれていないスキルはtriggerの見直しが必要

関連記事

• CLAUDE.md ベストプラクティス - CLAUDE.mdの最適な構成と管理
• AIエージェントのメモリ管理 - コンテキスト管理の総合ガイド
• AIエージェントのコンテキスト注入 - 動的なコンテキスト管理手法
• Claude Codeコンテキスト管理 - コンテキストウィンドウの効率化