skill-progressive-disclosure-design

スキルの段階的開示の設計

方向性を推奨する各セクションには、明確なメリットとデメリットを記載します。このスキルにおける判断は、ルールではなくトレードオフです。このスキルを使うモデルは、ルールを盲目的に適用するのではなく、トレードオフを踏まえてユーザー固有の状況を判断する必要があります。

トリガーと開示：まず分けて考える

ファイルを分割するかどうかを決める前に、混同されていることが多い2つの問題を切り分ける必要があります。

トリガーとは、Claude がスキルを実行するかどうかです。これは YAML の description だけで決まります。ファイルの分割はトリガーに影響しません。「スキルが安定してトリガーされない」という問題であれば、ファイルを分割せず、description を修正してください（skill-creator スキルの run_loop.py を使用します）。

段階的開示とは、スキルが有効になった後に何が読み込まれるかです。SKILL.md の本文は常に読み込まれます。references/* は、SKILL.md が特定のファイルを読むようモデルに指示した場合にのみ読み込まれます。scripts/* はコンテキストに読み込まれずに実行されます。コンテキストを保護できるのは、この段階です。

ユーザーがトリガーの問題を理由に分割について尋ねている場合は、まずこの混同を指摘し、適切な方向へ案内してください。

デフォルト：分割しない

一枚岩の SKILL.md は、分割が必要だと確認されるまでは、分割されたものより優れています。

次のいずれかに当てはまる場合にのみ、分割してください。

• SKILL.md が約400行を超えており、内容に自然な分岐がある。
• 評価のトランスクリプトから、無関係なセクションでモデルがコンテキストを浪費しているという実証的な根拠がある。
• 特定の内容が大きく、限られた条件でのみ必要になる。

一枚岩のままにするメリット：

• コンテキストの読み込みが1回で済み、ルーターの説明文を保守する必要がありません。
• リファレンスを読むためのツール呼び出しのオーバーヘッドがありません。
• モデルが誤ったリファレンスを読み込んだり、必要なリファレンスを読み飛ばしたりするリスクがありません。
• 1つのファイルが唯一の情報源となり、保守しやすくなります。
• 内容の相互依存性が高く、全体を把握する必要がある場合に適しています。
• 人間のレビュアーが最初から最後まで読みやすくなります。

一枚岩のままにするデメリット：

• 内容の10％しか関係しない場合でも、呼び出しのたびに全トークン分のコストがかかります。
• 約500行を超えると、重要な情報を見つけるモデルの能力が低下し、拡張性に限界があります。
• めったに使わない内容やニッチな内容を制限する仕組みがありません。
• すべての内容について、常に読み込まれる状態にするだけの価値を示す必要があります。
• ファイルが大きくなるにつれて、保守が難しくなります。

有効な3つの分割軸

1. バリアント分岐

ユーザーの意図によって、選択される経路は1つに定まります。SKILL.md には判断ロジックと共通のワークフローを記載し、各 references/<variant>.md には経路ごとの詳細を記載します。

my-skill/
├── SKILL.md               # decision tree + shared steps
└── references/
    ├── variant-a.md
    ├── variant-b.md
    └── variant-c.md

適切なバリアントの例：クラウドプロバイダー、データベースエンジン、フレームワークの選択、出力形式、言語。

メリット：

• 呼び出しのたびに一致するバリアントのみを読み込むため、バリアントの内容が大きい場合は大幅に節約できます。
• バリアントを独立して変更できるため、保守が簡単になります。
• 新しいバリアントを追加しても、既存の内容が膨らみません。
• 入力に基づいて1つの経路を選ぶという、わかりやすいメンタルモデルです。
• すでにバリアントに言及しているユーザーの意図と自然に対応します。

デメリット：

• SKILL.md にルーティングロジックが必要となり、削減した行数の一部を使います。
• 複数のバリアントにまたがる変更は、すべてのバリアントファイルに及び、作業量が増えます。
• 時間が経つにつれて、バリアントごとの対応に差が生じるリスクがあります。
• ユーザーの意図が曖昧な場合、モデルが複数のバリアントを読み込み、節約効果が失われる可能性があります。
• バリアント間で内容の約60％を超えて共有する場合、抽象化が成り立たなくなります。

2. ワークフローと参照データ

SKILL.md には手順（動詞、順序、判断）を記述します。references/ にはキーで検索する資料を置きます。

適切な参照コンテンツ：スキーマ、エラーコード表、API の一覧、サンプル集、設定オプションの一覧表、デザイントークン。

メリット：

• すべての分割方法の中で最も効果が高く、検索範囲が絞られるため、モデルは1つの項目だけを読み取ります。
• 概念上の境界が自然です（手順とデータ）。
• 参照資料は、呼び出しごとのコストに影響を与えずに大きくできます。
• 新しい参照項目を追加しても、ワークフローに手を加える必要がありません。
• 参照データは多くの場合、機械的に生成して再生成できます。

デメリット：

• モデルは読み取る前に、何を検索すべきか把握している必要があります。ポインターには、検索キーを明示的に含める必要があります。
• ワークフロー内で参照データを随所に織り込む必要があり、明確な箇所ごとに参照できない場合はうまく機能しません。
• 概念上ひとまとまりの内容が分割されるため、人間にとって読みづらくなります。
• 参照資料にしか存在しない広い文脈を、モデルが見落とす可能性があります。
• 小規模な検索データ（合計約50行未満）は、分割する価値がほとんどありません。

3. 深さによる階層化（一般的なケースと例外的なケース）

SKILL.md では80％のケースを扱います。references/edge-cases.md では残りのケースを扱います。

ポインターは次のように記述する必要があります。

X、Y、またはZが見られた場合は、いったん止まり、続行する前に references/edge-cases.md を読んでください。

メリット：

• 一般的なケースを最小限に保ち、高速かつ低コストにできます。
• すべての呼び出しを煩雑にすることなく、例外的なケースを網羅的に扱えます。
• 一般的なケースに手を加えずに、例外的なケースへの対応範囲を簡単に広げられます。
• 専門家の進め方を反映しています。まず通常の方法を試し、必要に応じて例外に対応します。

デメリット：

• 読み込み条件は、ユーザー入力から明確に判断できる必要があります。ほとんどの例外的なケースはこれを満たしません。
• 条件が曖昧だと、常に読み込まれる（無駄）か、まったく読み込まれない（無用の長物）かのどちらかになります。
• 評価は自然と一般的なクエリに偏るため、例外的なケースのテストが不足します。
• エスカレーションすべき段階を過ぎても、モデルが一般的な手順を続けてしまう可能性があります。
• 80対20の見積もりはしばしば誤っており、例外的なケースと思われたものが、実際には一般的なケースであることが判明します。

うまく機能しない分割方法

それぞれのアンチパターンについて、「魅力的に見える理由」では設計者がその方法を選びたくなる理由を、「うまくいかない理由」では実際に生じる問題を説明します。

呼び出しがトピックごとにまとまらない場合の、トピック別分割

テスト用スキルを unit.md、integration.md、mocks.md に分割するのは、典型的な例です。

魅力的に見える理由：

• 概念的に整理されており、人間がドキュメントを構成する方法にも合っています。
• メンテナーにとって移動しやすくなります。
• 呼び出しごとのコンテキストを減らせそうに見えます。

うまくいかない理由：

• 実際のタスクは2～3つのトピックにまたがるため、呼び出しごとに複数のファイルを読み込む必要があります。
• 複数のトピックにまたがる関心事が、重複したり分断されたりします。
• 削減効果は理論上のもので、実証されていません。

実際の分岐条件がないまま、行数目標を達成するために分割する

魅力的に見える理由：

• 「SKILL.md を400行未満に保つ」といった経験則は、満たすべき明快なルールに感じられます。
• 分割すること自体が前進に感じられます。

うまくいかない理由：

• 分岐条件がないと、参照ファイルは並行して、または常に読み込まれるため、何も削減されません。
• SKILL.md に案内文が増え、コンテンツ全体がかえって長くなることもよくあります。

まれだが重要な内容を references/ に置く

魅力的に見える理由：

• 内容が大規模であるか、専門的です。
• SKILL.md から移すことが、整理整頓として適切に思えます。

うまくいかない理由：

• 参照ファイルは設計上、必ずしも読み込まれるとは限らず、モデルが読み飛ばす可能性があります。
• 内容が重要であれば、確実に読み込まれる必要があります。そのためには SKILL.md に記述しなければなりません。
• 「まれ」と「重要」が両立する場合、通常はそのスキルが2つの役割を担っている兆候です。スキルを2つに分けるべきです。

見た目だけの分割（Examples、Notes、Tips ファイル）

魅力的に見える理由：

• SKILL.md の視覚的な煩雑さを減らせます。
• 整理されているように感じられます。

うまくいかない理由：

• 読み込み条件がありません。常に読み込まれる（ツール呼び出しの無駄）か、まったく読み込まれない（内容が活用されない）かのどちらかになります。
• 実行時には存在しない重要度の階層を示唆します。
• 必要な内容がモデルから見えなくなることがよくあります。

ポインターの適切な管理

SKILL.md がリファレンスを指す場合、そのポインターが読み込み条件のすべてです。ルール：

• 読み込みのきっかけとなる、ユーザーに見えるシグナルを明記します。「ユーザーがスナップショットテストに言及した場合」とし、「テスト関連の懸念がある場合」とはしません。
• ポインターごとに1文にします。SKILL.md でリファレンスの内容を要約しないでください。
• ファイル名に読み込み条件を含めます。advanced.md ではなく go126-simd.md にします。
• 300行を超えるリファレンスには、ファイルの先頭に目次を設けます。
• ほとんどの実行で2つのリファレンスが同時に読み込まれる場合は、1つにまとめます。

ポインターを厳密に管理するメリット：

• 誤った読み込みの割合が大幅に下がります。
• ファイル名に読み込み条件が含まれるため、将来の保守担当者にも意図が伝わります。
• 各リファレンスが必要となる条件を、事前に明確にする必要があります。
• アーキテクチャ評価の解釈が容易になります。

ポインターを厳密に管理するデメリット：

• 明確なきっかけがない内容もあり、ルールに従うと不自然な表現になることがあります。
• ファイル名が長く、不格好になります。
• 規律が必要で、時間の経過とともに簡単に崩れます。
• きっかけとなる条件が実際に曖昧な場合でも、有用な読み込みを過度に制限することがあります。

references/ より scripts/ を使う

決定論的な処理（フォーマット、検証、スキーマ生成、ファイル変換、正規表現を多用する解析）には、references/ の説明文より scripts/ のスクリプトが適しています。

リファレンスの説明文よりスクリプトを使うメリット：

• 実行時のコンテキストコストがゼロです。
• 決定論的で、再現可能な出力が得られます。
• 再読み込みせずに、呼び出しをまたいで再利用できます。
• 独立してユニットテストを実行できます。
• 多くの場合、モデルによる説明文に基づいた生成より高速です。

スクリプトを使うデメリット：

• ランタイムがスクリプト実行に対応している必要があり、すべての環境で使えるわけではありません。
• モデルに説明文を推論させる方法より柔軟性がありません。
• コードを変更せずに、予期しないエッジケースに対処するのが困難です。
• 保守の負担が増えます。スキル内のコードが動作し続けるようにする必要があります。
• スクリプトを編集しないと、ユーザーが動作を簡単にカスタマイズできません。
• 失敗時の影響が明確です。スクリプトのエラーでワークフローが停止します。

判断チェックリスト

SKILL.md から内容を分割する前に、次の項目に答えてください。

1. この内容には、ユーザー入力からモデルが検出できる、明確で観測可能な読み込み条件がありますか？
2. SKILL.md に追加するルーターの説明文も考慮したうえで、分割によって実際にコンテキストを削減できますか？
3. これは参照データ（検索）ですか、それとも手順（順序）ですか？手順の内容は通常、そのまま残します。
4. 代わりにスクリプトで決定論的に処理できますか？
5. 現実的な呼び出し全体のうち、どの程度の実行でこのファイルが読み込まれますか？20%未満なら、インライン化するか削除してください。読み込み頻度が低いリファレンスでは、ルーティングのオーバーヘッドを正当化できることはまれです。20～80%が分割に最適な範囲です。80%を超える場合は、SKILL.md に含めてください。ルーティングのコストが読み込みによる節約を上回ります。

質問1への答えが明確でない場合は、分割しないでください。

スキルのアーキテクチャを評価する

アーキテクチャの評価は、出力の評価とは異なります。出力評価では「スキルは正しいものを生成したか」を問い、アーキテクチャ評価では「スキルは適切な理由で、許容できるコストの範囲内で正しいファイルを読み込んだか」を問います。ハーネスは同じで、メトリクスが異なります。両方を実行してください。出力品質が最低ラインであり、その上でアーキテクチャを最適化します。

アーキテクチャ評価を実行するメリット：

• 使用されていないリファレンス、使われていない SKILL.md のセクション、誤ったルーティングのコンテンツを検出できます。
• 分割によってトークンを実際に節約できたのか、見た目がすっきりしただけなのかを数値で評価できます。
• 直感では見逃す実際の読み込みパターンが明らかになります。
• 評価セットで宣言済みのすべての経路を網羅する必要が生まれ、使われていない経路が見つかります。
• 出力評価と組み合わせることで、両方の観点におけるデグレードを検出できます。

アーキテクチャ評価を実行するデメリット：

• 標準的な出力評価に加えて、ハーネスのセットアップが必要です。
• 経路の網羅性を確保するための評価セットの設計に手間がかかります。
• メトリクスはスキルごとに調整が必要です（しきい値はコスト構造によって異なります）。
• 出力評価も引き続き必要なため、反復にかかる総コストが増えます。
• 出力品質を犠牲にして、トークンコストの最適化に走りやすくなります。

アーキテクチャ向け評価セットの設計

出力評価では、現実的なクエリ全体で出力品質を最適化します。アーキテクチャ評価では、パスの網羅性を最適化します。スキルが備えているとするすべてのコードパスを評価セットで実行しなければ、指標は意味をなしません。

最低限、次の項目を作成します。

• 宣言された各バリアントにつき1つのクエリ（スキルでバリアントごとの分岐を使用している場合）。
• 各エッジケース分岐につき1つのクエリ（深度ティアごとの分岐がある場合）。
• 主要な検索カテゴリごとに1つのクエリ（参照データごとの分割がある場合）。
• 共通パスのみを通り、参照を読み込まないはずのクエリを1つ。
• スキルをまったく起動しないはずの、話題から外れたクエリを2～3個（説明のテストにもなります）。

現実的なクエリで参照ファイルが読み込まれない場合、そのファイルは使われていません。実行を始める前に、内容をインライン化するか削除してください。

計測

各評価実行は、スキルを読み込んだサブエージェントによって行われます。実行ごとに次の項目を記録します。

1. すべてのツール呼び出しを含む完全なトランスクリプト。
2. 読み込まれた references/* ファイル（スキルディレクトリ内のパスに対する view 呼び出しを解析します）。
3. scripts/* が呼び出されたかどうか。
4. 合計トークン数と実行時間。
5. 出力（並行して行う出力品質評価用）。

標準出力と一緒に、実行ごとの transcript.json と loads.json を保存します。skill-creator のハーネスでは timing.json にトークン数と時間がすでに記録されます。評価ステップを拡張し、トランスクリプトから参照の読み込み状況を抽出してください。

参照ファイルごとの指標

すべての評価実行を通じて、各 references/*.md について次の項目を算出します。

• 読み込み率：そのファイルを読み込んだ実行の割合。
• 同時読み込み率：他の各参照ファイルについて、両方を読み込んだ実行の割合。
• 読み込み時の使用率：そのファイルを読み込んだ実行のうち、内容が出力に明確に反映された実行の割合（内容を引用した、手順を適用した、スキーマを使ったなど）。トランスクリプトを確認します。
• 再読み込み率：同じファイルを2回読み込んだ実行の割合。

スキル全体の指標

• 呼び出しごとのトークン数の中央値と p95（参照の有無別）。
• SKILL.md の利用状況：トランスクリプトを読み、どの実行でもモデルが参照しなかった SKILL.md のセクションを特定します。削除の有力候補です。
• パスの網羅性：宣言されたすべてのパスが、少なくとも1つのクエリで実行されたか。

判断基準

観察結果	対応
参照ファイルの読み込み率が20%未満	SKILL.md にインライン化するか削除します。ルーティングのオーバーヘッドに見合いません
参照ファイルの読み込み率が20～80%	分割したままにします。適切な範囲で、ルーティングのメリットがあります
参照ファイルの読み込み率が80%超	SKILL.md に統合します。常時読み込みのコストのほうがルーティングのコストを下回ります
2つの参照ファイルが70%超の実行で同時に読み込まれる	1つのファイルに統合します
参照ファイルを読み込んでも出力に使われていない	SKILL.md 内の参照先を修正するか、削除します
同じ実行内で参照ファイルが再読み込みされる	SKILL.md のルーティングが不明瞭です。明確にしてください
どのクエリからも参照ファイルが読み込まれない	参照ファイルを削除します
どの実行でも参照されない SKILL.md のセクションがある	そのセクションを削除します

これらのしきい値は初期値です。コストの特性に合わせて調整してください。読み込みコストが低い小さな参照ファイルは、読み込み率が低くても許容できます。

2つのアーキテクチャの比較

アーキテクチャ（モノリシックと分割、または分割案Aと分割案B）を選ぶ際は、次の手順で比較します。

1. 両方のバージョンに同じ評価セットを適用します。
2. 両方で出力品質評価を実施します。品質が低下していないことを確認してください。品質が低下した場合、トークンを節約できてもアーキテクチャ変更は失敗です。
3. 実行ごとのトークン数の中央値、p95、時間の中央値を比較します。
4. パスの網羅性を比較します。それぞれのバージョンで、想定したパスを通じて同じ出力に確実に到達できるかを確認します。

分割によってトークンを15%節約できても、出力品質にばらつきが生じるなら、モノリシック構成のほうが優れています。効率よりも信頼性が重要です。

メトリクスではわからないこと

• SKILL.md の文章がわかりやすいかどうか。ツール呼び出しに戸惑ったり、行き詰まったりした試みがないか、トランスクリプトを確認してください。
• 説明が正しくトリガーされるかどうか。これは別の評価項目です（skill-creator スキルの run_loop.py を使用してください）。
• コンテンツの配置がユーザーのメンタルモデルに合っているかどうか。主観的なため、人間によるレビューが必要です。

設計時にきれいに見えた分割が、実際の負荷パターンと一致することはほとんどありません。自分の直感よりも、トランスクリプトを信頼してください。

アドバイスを提示するとき

特定のスキルの構成についてアドバイスを求められた場合：

1. まず診断します。これはトリガーに関する質問ですか、それとも情報開示に関する質問ですか？
2. 推奨する前に、既存の SKILL.md（またはユーザーによる説明）から関連する内容を引用します。
3. 必要最小限の分割案を提示します。必要以上に多くのファイルへ分割しないようにします。
4. 参照ファイルごとに、SKILL.md に記載する正確なポインター文を作成します。
5. トレードオフを明示します。このスキルの長所と短所を、推奨案の提示方法の参考にしてください。
6. 分割が役立つかどうか判断できない場合は、決定する前に計測（スキルを評価し、トランスクリプトを確認すること）を推奨します。