Progressive Disclosure

プログレッシブ・ディスクロージャーとは何ですか？すべての内容を1つの文書に詰め込むこととどう違いますか？

プログレッシブ・ディスクロージャーとは、説明文書の内容を階層的に整理することを指す。最上層は簡潔なメインファイル（Skill.mdなど）であり、そこには最も基本的な使い方と、他の拡張ファイルを指す「道標」であるリンクだけが置かれる。本当に詳細な内容（高度な機能、完全なAPIリファレンス、大量の例など）はそれぞれ独立したファイルに置かれ、Claudeはその特定の情報が実際に必要になったときにのみ、対応する拡張ファイルを読み込む。

すべての内容を1つの文書に詰め込むこととの最大の違いは、「いつコンテキストを消費するか」にある。すべての詳細を1つのメインファイルに書き込んでしまうと、現在のタスクにそれが必要かどうかに関わらず、読み込まれた時点でその内容すべてがコンテキスト空間を消費してしまう。一方プログレッシブ・ディスクロージャーでは、拡張ファイルは実際に読み込まれるまで一切トークンを消費せず、メインファイルの簡潔な概要だけが先にコンテキストに入り、本当に詳細が必要になったときに初めて対応するファイルを読み込む。

プログレッシブ・ディスクロージャーはなぜ必要とされ、どんな問題を解決するのですか？

コンテキストウィンドウは共有リソースである。あるSkillの内容は、システムプロンプト、会話履歴、他のSkillのメタデータ、ユーザーの実際のリクエストと同じ限られた空間を共有しなければならない。すべてのSkillが完全な詳細内容（APIリファレンス、大量の例、高度な機能の説明）をすべてメインファイルに詰め込んでしまうと、ユーザーが同時に複数のSkillをトリガーする可能性がある場合や、単一のSkillの内容自体が非常に大きい場合、コンテキスト空間はすぐに枯渇し、本来現在のタスクを処理するために使われるべき空間を圧迫してしまう。

プログレッシブ・ディスクロージャーが解決するのは、まさにこのリソース配分の問題である。これは「内容が存在すること」と「内容がコンテキストを消費すること」を切り離す。1つのSkillは非常に完全で詳細な参考資料をパッケージ化することができ、それが読み込まれない限り、その資料は一切トークンを消費しない。これは、書き手が「内容が十分に完全であるか」と「コンテキストを消費しすぎないか」の間でトレードオフをする必要がないことを意味し、両方を同時に満たすことができる。なぜなら、完全性は拡張ファイルが担い、簡潔さはメインファイルが担うからである。

プログレッシブ・ディスクロージャーは実際にどのように機能し、一般的な整理方法にはどんなものがありますか？

最も基本的な仕組みとして、Claudeは最初、すべてのSkillの名前と説明（メタデータ）だけを事前に読み込んでおく。完全なSKILL.mdの内容は、そのSkillが実際に現在のタスクに関連していると判断されたときに初めて読み込まれ、Skill.md内で参照されている他の拡張ファイルは、Claudeがその情報を本当に必要としたときにのみ別途読み込まれる。この仕組みは、ファイルシステムへのアクセス能力を持つ実行環境の中で、Claudeがコマンドラインのような形で必要に応じてファイルを読み込むことに依拠している。

一般的な整理方法には3種類ある。1つ目は「概要ガイドとリファレンス」であり、メインファイルはクイックスタートのやり方を示し、高度な機能や完全なAPIリファレンスはそれぞれ独立した拡張ファイルに分ける。2つ目は「分野別に分類する」方法であり、複数のテーマにまたがるSkillに適している。例えば財務、営業、製品ごとに独立した参考ファイルを作成すれば、ユーザーが営業に関する質問をしたときには営業関連のファイルだけが読み込まれ、財務や製品の内容が一緒に読み込まれることはない。3つ目は「条件付きの詳細」であり、メインファイルはまず基本的なやり方を示し、ユーザーのニーズが本当に高度なシナリオ（改訂履歴の追跡や複雑なフォーマットの処理が必要な場合など）に関わる場合にのみ、対応する拡張ファイルにリンクする。いずれの方法であっても、共通する実務上の推奨事項がある。拡張ファイルの参照階層は、メインファイルから直接1階層だけリンクするようにし、拡張ファイルの中でさらに深い階層のファイルにリンクしないようにすることである。なぜなら、Claudeが深くネストされた参照を読み込む際、一部の内容だけをプレビューする形で読み込んでしまい、かえって不完全な情報を得てしまう可能性があるためである。

プログレッシブ・ディスクロージャーは私にとって実際どんな意味があり、Skillを書く際にどの内容をメインファイルに置き、どの内容を拡張ファイルに置くべきかをどう判断すればよいですか？

簡単な判断基準は次の通りである。ある内容が「このSkillが発動するたびにほぼ必ず使われる」基本的な使い方であれば、メインファイルに入れる。「特定の状況でのみ使われる」高度な機能、完全なリファレンス、大量の例であれば、独立した拡張ファイルに分割し、メインファイルにはそれを指す一文とリンクだけを残す。実務上、公式の推奨ではメインファイルの本文をできるだけ500行以内に収めることが推奨されており、この分量に近づいてきたら、内容の一部を分割することを検討すべきサインである。

もう1つの実用的な判断方法は、自分自身にこう問いかけることである。「もしユーザーの今回のタスクにある内容が全く必要ないとしたら、その内容を完全に読み込まないようにする方法はあるか？」答えが「ない、なぜならそれはメインファイルと一緒に書かれているから」であれば、その内容は分割する価値がある。すでに独立したファイルになっており、必要なときにのみ読み込まれるのであれば、その部分はすでにプログレッシブ・ディスクロージャーが本来もたらすべき効果を実現できている。長めの拡張ファイル（100行を超えるもの）については、ファイルの冒頭に目次を追加しておくと、Claudeが一部の内容しかプレビューしなくても、そのファイルが全体としてどんな範囲をカバーしているかを把握できる。