必要なときだけ読み込むドメイン知識

「全部 system prompt に詰め込む」の落とし穴

skill が20個ある。それぞれ内容が充実している：pdf-processing（PDF の読み方）、code-review（review のチェックリスト）、git-workflow（よく使う git のパターン）……直感的なアプローチ：全部 system prompt に連結して、モデルがいつでも参照できるようにする。

結果：

• 毎回の呼び出しで15〜30K の入力 token を消費する（問いがどの skill も使わない内容でも）。
• モデルの注意力が希薄化する——長い system prompt に書かれたルールへの従順さは低下する。
• 一つの skill を修正するたびに、過去の会話のキャッシュがすべて無効化される。

s05 のアプローチは2層に分割することだ。

2層アーキテクチャ

Layer 1 · 安い：system prompt には skill の名前と一行説明だけ（各約100 token）。20個の skill = 2K token、許容範囲だ。

# システムプロンプト内の skill 一覧
Skills available:
  - pdf: Process PDF files. Extract text, tables, metadata.
  - code-review: Systematic code review checklist.
  - git-workflow: Common git branching and rebase patterns.

Layer 2 · オンデマンド：モデルが特定の skill を使いたいとき、load_skill(name="pdf") を呼ぶ。完全な skill 本文（5〜10K token になることもある）が tool_result としてコンテキストに入ってくる。使われない skill は一 token も読み込まれない。

# tool_result に完全な skill が返る
<skill name="pdf">
  Step 1: Use pdfplumber for extraction...
  Step 2: Handle OCR fallback when needed...
  Step 3: Structure output as Markdown table...
</skill>

token コストの比較

実際のシナリオで確認しよう。skill が20個あり、各本文の平均は3000 token とする。ユーザーが何かを質問したとき（例：「ログインエンドポイントのバグを直して」）——この質問はおそらくどの skill も使わない。

SKILL.md のフォーマット

skill ファイルは YAML frontmatter + 本文の形式をとる：

---
name: pdf
description: Process PDF files. Extract text, tables, metadata.
tags: document,parsing
---

Step 1: Use pdfplumber for extraction. Handle multi-column layouts...
Step 2: For scanned PDFs, fall back to OCR via tesseract...

frontmatter が Layer 1 に使われ（name/description/tags）、本文が Layer 2 に使われる。このスタイルは静的サイトジェネレーター（Jekyll、Hugo）から着想を得ており、知っている人にはすぐわかる書き方だ。