「すべての情報を最初に提供すれば、AIはより賢く動作する」
多くの開発者がこう考えます。
私もそうでした。
しかし、これは根本的な誤解だったのです。
最近のRedditで、ある開発者がAgent Skillsについて興味深い体験を共有していました。
彼の失敗と成功から、私たちは重要な教訓を学べます。
今回は、その体験をもとに、AIのコンテキストエンジニアリングについて考察してみましょう。
大量の情報がもたらす問題
2025年10月、AnthropicはAgent Skillsという新機能をリリースしました。
これは、Claudeに特定のスキルを教え込むための仕組みです。
この開発者は、各スキルファイルに1000行を超える情報を詰め込みました。
Cloudflare用に1131行。
Chrome DevTools用に1200行。
さらに36個のスキルで合計15000行にも達したそうです。
当初はGitHubで400以上のスターを獲得しました。
順調に見えたのです。
しかし、実際に複数のスキルを同時に使おうとすると問題が発生しました。
5～7個のスキルを読み込むだけで、コンテキストウィンドウに5000～7000行もの情報が流れ込むことになったのです。
結果はどうなったか。
起動時間は500ミリ秒以上かかりました。
本当に必要な情報の割合は全体の10%程度。
残りの90%は無駄な情報だったのです。
根本的な誤解
問題の本質は何だったのでしょうか。
それは「Agent Skillsをドキュメントとして扱っていた」ことでした。
スキルはドキュメントではありません。
特定のタスクを実行するための能力なのです。
たとえばDevOpsスキル。
これは「Cloudflareの全機能の説明書」ではありません。
「サーバーレス関数をデプロイする能力」として扱うべきものでした。
この開発者は皮肉なことに、自分自身が作成したskill-creatorスキルに「プログレッシブディスクロージャー（段階的開示）」の原則を記載していました。
書いたのに、その真の意味を理解していなかったというのです。
解決策：3層アーキテクチャ
2週間の苦労の末、週末のリファクタリングで問題は解決しました。
新しいアーキテクチャは3つの層で構成されます。
第1層：メタデータ
YAMLフロントマターのみ。
約100語程度。
Claudeがそのスキルが関連するかどうかを判断するための最小限の情報だけを含みます。
第2層：エントリーポイント
最大200行程度。
概要、クイックスタート、ナビゲーションマップを提供。
詳細な内容はリファレンスファイルへ誘導します。
第3層：リファレンスファイル
各ファイル200～300行。
必要な時だけ読み込まれる詳細なドキュメント。
単一のトピックに焦点を当てたモジュール構造です。
驚くべき改善結果
リファクタリングの結果は劇的でした。
claude-codeスキルを例にとると、870行の単一ファイルから181行のメインファイルと13個のリファレンスファイルに分割。
トークン効率は4.8倍向上しました。
全体では：
- 初期読み込みが85%削減
- 起動時間が500ミリ秒から100ミリ秒以下に短縮
- 関連情報の割合が10%から90%に向上
さらに重要な変化もありました。
36個の個別スキルを20個のワークフローグループに統合。
たとえば、Cloudflare、Docker、Google Cloudを別々のスキルとして扱うのではありません。
「DevOps」という一つのワークフロー能力としてまとめたのです。
なぜ200行なのか
200行という制限は恣意的なものではありません。
LLMが効率的にスキャンして次に何を読むべきか判断できる量の上限なのです。
この制限を守ることで、Claudeは素早く以下の判断ができます：
- スキルが提供する内容の理解
- 必要なリファレンスファイルの特定
- その特定ファイルのみの読み込み
結果として、1131行の雑多な情報ではなく、400～700行の高度に関連性のある情報だけを扱うことになります。
プログレッシブディスクロージャーの本質
段階的開示が機能する理由は、実際の開発ワークフローに合致しているからです。
開発者が問題を解決するとき、まず全体像を把握します。
次に具体的な手順を確認します。
そして最後に実装の詳細を調べます。
この自然な流れをスキルの構造に反映させることで、AIもより効率的に動作できるのです。
- メタデータを確認 → このスキルは現在のタスクに関連するか？
- エントリーポイントを読む → どんなワークフローパターンが使えるか？
- 特定のリファレンスを読む → 現在のステップの実装詳細は？
各ステップは小さく、焦点を絞り、目的が明確です。
教訓：コンテキストエンジニアリングの本質
この経験から学べる重要な教訓があります。
コンテキストエンジニアリングは「より多くの情報を読み込む」ことではありません。
「適切な情報を適切なタイミングで読み込む」ことなのです。
また、スキルとドキュメントの違いを理解することも重要です。
ドキュメントは受動的な参照資料です。
一方、スキルは能動的なワークフロー知識です。
この違いを理解しないと、効果的なAgent Skillsは作れません。
さらに、メトリクスは嘘をつきません。
4.8倍のトークン効率改善は単なる数字の改善ではありません。
「時々動く」と「確実に動く」の違いなのです。
実装上の注意点
もしあなたがAgent Skillsを作成するなら、以下の点に注意してください。
まず、コールドスタートをテストすること。
コンテキストをクリアしてスキルを起動し、測定してください。
500行以上が最初に読み込まれるなら、それは間違ったアプローチです。
次に、リファレンスファイルを軽視しないこと。
リファレンスは「オプションの追加ドキュメント」ではありません。
実際の作業が行われる場所です。
SKILL.mdファイルは単なる地図に過ぎません。
最後に、ワークフロー中心の設計を心がけること。
ツール別ではなく、開発タスク別にスキルを整理してください。
まとめ
Agent Skillsはまだ新しい機能です。
失敗するのは当然でしょう。
重要なのは、その失敗から学ぶことです。
この開発者の経験は、私たち全員にとって貴重な教訓となります。
情報の量より質。すべてを提供するより、必要なものを必要な時に。
これがAIと効果的に協働する鍵なのです。
プログレッシブディスクロージャーの原則を理解し、適用することで、より効率的で実用的なAgent Skillsを作成できるでしょう。
2週間の混乱と1週末のリファクタリング。
その差は、この原則を理解しているかどうかにかかっています。
AIの能力を最大限に引き出すには、人間側の設計思想が重要です。
この事例は、その重要性を改めて教えてくれました。
