analysis_claude_code/docs/v4-スキル機構.md

# v4: スキル機構

**コアの洞察: スキルはツールではなく、知識パッケージ。**

## 知識の外部化: トレーニングから編集へ

スキルは深いパラダイムシフトを体現する：**知識の外部化**。

### 従来のアプローチ: パラメータに内在化された知識

従来のAIシステムはすべての知識をモデルパラメータに保存。アクセス、変更、再利用できない。

モデルに新しいスキルを学ばせたい？必要なこと：
1. 大量の訓練データを収集
2. 分散訓練クラスタをセットアップ
3. 複雑なパラメータファインチューニング（LoRA、フルファインチューニングなど）
4. 新しいモデルバージョンをデプロイ

### 新しいパラダイム: ドキュメントとして外部化された知識

コード実行パラダイムがすべてを変える。

```
┌──────────────────────────────────────────────────────────────────────┐
│                     知識ストレージ階層                                │
│                                                                      │
│  モデルパラメータ → コンテキストウィンドウ → ファイルシステム → スキルライブラリ │
│    (内在化)           (ランタイム)           (永続)          (構造化)      │
│                                                                      │
│  ←────── トレーニング必要 ──────→  ←─── 自然言語で編集 ────→            │
│    クラスタ、データ、専門知識必要        誰でも変更可能                    │
└──────────────────────────────────────────────────────────────────────┘
```

**重要なブレークスルー**:
- **以前**: モデル動作の変更 = パラメータの変更 = トレーニング必要 = GPUクラスタ + 訓練データ + ML専門知識
- **今**: モデル動作の変更 = SKILL.mdの編集 = テキストファイルの編集 = 誰でもできる

## 問題

v3でタスク分解のためのサブエージェントを得た。しかしより深い問題がある：**モデルはドメイン固有のタスクをどのように処理するか知っているのか？**

- PDFを処理？`pdftotext` vs `PyMuPDF`を知る必要がある
- MCPサーバーを構築？プロトコル仕様とベストプラクティスが必要
- コードレビュー？体系的なチェックリストが必要

この知識はツールではない—**専門知識**だ。スキルはモデルがオンデマンドでドメイン知識を読み込むことで解決。

## 重要な概念

### ツール vs スキル

| 概念 | 何か | 例 |
|------|------|-----|
| **ツール** | モデルが何をCAN DO | bash, read_file, write_file |
| **スキル** | モデルがどうKNOW TO DO | PDF処理、MCP構築 |

ツールは能力。スキルは知識。

### SKILL.md標準

```
skills/
├── pdf/
│   └── SKILL.md          # 必須
├── mcp-builder/
│   ├── SKILL.md
│   └── references/       # オプション
└── code-review/
    ├── SKILL.md
    └── scripts/          # オプション
```

**SKILL.mdフォーマット**: YAMLフロントマター + Markdownボディ

```markdown
---
name: pdf
description: PDFファイルを処理。PDF読み込み、作成、マージ時に使用。
---

# PDF処理スキル

## PDFの読み込み

高速抽出にはpdftotext使用：
\`\`\`bash
pdftotext input.pdf -
\`\`\`
...
```

## 実装（約100行追加）

### SkillLoaderクラス

```python
class SkillLoader:
    def __init__(self, skills_dir: Path):
        self.skills = {}
        self.load_skills()

    def parse_skill_md(self, path: Path) -> dict:
        """YAMLフロントマター + Markdownボディをパース。"""
        content = path.read_text()
        match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)$', content, re.DOTALL)
        # {name, description, body, path, dir}を返す

    def get_descriptions(self) -> str:
        """システムプロンプト用のメタデータを生成。"""
        return "\n".join(f"- {name}: {skill['description']}"
                        for name, skill in self.skills.items())

    def get_skill_content(self, name: str) -> str:
        """コンテキスト注入用のフルコンテンツを取得。"""
        return f"# Skill: {name}\n\n{skill['body']}"
```

### Skillツール

```python
SKILL_TOOL = {
    "name": "Skill",
    "description": "専門知識を得るためにスキルを読み込む。",
    "input_schema": {
        "properties": {"skill": {"type": "string"}},
        "required": ["skill"]
    }
}
```

### メッセージ注入（キャッシュ保持）

重要な洞察: スキルコンテンツは**tool_result**（userメッセージの一部）に入る、システムプロンプトではない：

```python
def run_skill(skill_name: str) -> str:
    content = SKILLS.get_skill_content(skill_name)
    return f"""<skill-loaded name="{skill_name}">
{content}
</skill-loaded>

上記のスキルの指示に従ってください。"""
```

**重要な洞察**:
- スキルコンテンツは新しいメッセージとして**末尾に追加**
- 前のすべて（システムプロンプト + すべての以前のメッセージ）はキャッシュされ再利用
- 新しく追加されたスキルコンテンツのみ計算が必要—**プレフィックス全体がキャッシュヒット**

## キャッシュ経済学

### キャッシュを無視するコスト

多くの開発者がLangGraph、LangChain、AutoGenで習慣的に：
- システムプロンプトに動的状態を注入
- メッセージ履歴を編集・圧縮
- スライディングウィンドウで会話を切り詰め

**これらの操作はキャッシュを無効化し、コストを7-50倍に爆発させる。**

典型的な50ラウンドのSWEタスク：
- **キャッシュ破壊**: $14.06（毎ラウンドシステムプロンプトを変更）
- **キャッシュ最適化**: $1.85（追記のみ）
- **節約**: 86.9%

### アンチパターン

| アンチパターン | 効果 | コスト乗数 |
|--------------|------|-----------|
| 動的システムプロンプト | 100%キャッシュミス | **20-50倍** |
| メッセージ圧縮 | 置換点から無効化 | **5-15倍** |
| スライディングウィンドウ | 100%キャッシュミス | **30-50倍** |
| メッセージ編集 | 編集点から無効化 | **10-30倍** |

## スキル設計ガイドライン

1. **単一責任**: 1スキル = 1ドメイン
2. **自己完結**: 外部参照を最小化
3. **アクション指向**: 指示、説明ではなく
4. **構造化**: セクションは素早い参照用

## より深い洞察

> **知識はドキュメントになり、誰でも教師になれる。**

従来のファインチューニングは**オフライン学習**: データ収集 -> 訓練 -> デプロイ -> 使用。
スキルは**オンライン学習**を可能に: ランタイムでオンデマンド知識を読み込み、即座に有効。

---

**スキルは外部化された専門知識。**

[← v3](./v3-サブエージェント.md) | [READMEに戻る](../README_ja.md)