writing-great-skills

Skill の役割は、ランダムなシステムから決定性を引き出すことです。予測可能性——agent が毎回同じ プロセス を実行すること（同じ出力を生成することではありません）——は根本的な美徳であり、以下のすべての手段はその実現に役立ちます。

太字の用語は GLOSSARY.md で定義されています。意味を詳しく知りたい場合は、そちらを参照してください。

呼び出し

コストの異なる 2 つの選択肢があります。

• モデル呼び出し型の skill は description を保持するため、agent が自律的に呼び出せ、他の skills からも利用できます（ユーザーが名前を手動で入力して呼び出すこともできます）。その代わり、コンテキスト負荷が生じます。description は毎ターン context window に含まれます。仕組み：disable-model-invocation を省略し、豊富なトリガー表現（"Use when the user wants…"、"mentions…"）を含む、モデル向けの description を記述します。
• ユーザー呼び出し型の skill は、agent から利用できる範囲から description を除外します。ユーザーが名前を入力した場合にのみ呼び出せ、他の skill から呼び出すこともできません。コンテキスト負荷はゼロですが、認知負荷が生じます。存在を覚えておく必要がある index は、ユーザー です。仕組み：disable-model-invocation: true を設定します。description は人間向けの一行要約となり、トリガー一覧は含めません。

agent が自力でその skill を見つける必要がある場合、または別の skill から呼び出す必要がある場合にのみ、モデル呼び出し型を選びます。手動でしか呼び出されないなら、ユーザー呼び出し型にして、コンテキスト負荷を避けます。

ユーザー呼び出し型の skills が増えすぎてユーザーが覚えられなくなったら、ルーター skill で累積した認知負荷を軽減します。これは、他のユーザー呼び出し型の skills の名前と、それらを使用するタイミングを案内する、ユーザー呼び出し型の skill です。

description の記述

モデル呼び出し型の description には、skill の内容を説明し、呼び出すべき 分岐を列挙するという 2 つの役割があります。すべての語句がコンテキスト負荷を増やすため、description は本文以上に簡潔にする必要があります。

• skill の先頭の語句を前に置きます——description が呼び出しを担う場所だからです。
• 各分岐にトリガーを 1 つ設けます。 単一の分岐を言い換えるだけの同義語は、重複です。"build features using TDD … asks for test-first development" は、同じ分岐を 2 回記述しています。統合し、本当に異なる分岐だけを残します。
• 本文にすでにある概要は削除します。 Description にはトリガーと、必要であれば "when another skill needs…" という到達範囲を示す文だけを残します。

情報の階層

Skill は 手順とリファレンスの 2 種類の内容で構成され、両者は自由に組み合わせられます。skill はすべて手順でも、すべてリファレンスでも、両方を含んでもかまいません。重要なのは、どの種類の内容を使うか、そして各ブロックを情報の階層のどこに置くかです。情報の階層とは、agent が資料を必要とする即時性の順に並べた段階です。

1. skill 内の手順 - SKILL.md に記述する順序付きのアクションで、最優先の層です。agent が順番に実行する内容です。各手順は 完了基準で締めくくり、作業が完了したと判断する条件を agent に示します。可能であれば 検証可能 にします（agent は完了と未完了を判別できますか？）。必要に応じて 網羅的 にします（「変更された model がすべて検討されている」は、「変更点の一覧を作成する」より適切です）。曖昧な基準は 早すぎる完了を招きます。
2. skill 内のリファレンス - 必要に応じて参照する、SKILL.md 内の定義、ルール、事実です。通常、正当なフラットな同列の集合です（ある review のすべてのルールが同じ段階にある状態）。これは問題ではありません。この skill はすべてリファレンスで構成されています。
3. 外部リファレンス - SKILL.md から独立したファイルに移し、コンテキストポインターを介して参照します。ポインターが参照を促した場合にのみ読み込まれます。（GLOSSARY.md のような sibling ファイルを含む、開示されたリファレンスから、どの skill からも参照できる skill system の完全な外部にある 外部リファレンスまでを扱います。）

強力な完了基準は、skill に手順があるかどうかにかかわらず、十分な調査作業を促します。これは agent が作業中に情報を掘り下げることです。「すべてのルールが適用されている」という基準がフラットなリファレンスを支えるのと同様に、「すべての手順が完了している」という基準が手順の流れを支えます。

下層に移す内容が少なすぎると最上位が肥大化し、多すぎると agent が実際に必要とする資料が隠れてしまいます。この緊張関係こそが、判断のすべてです。

段階的開示とは、SKILL.md から linked ファイルへと、階層の下層に内容を移し、最上位を明瞭に保つことです。仕組み：skill folder 内に、内容がわかる名前を付けた linked .md ファイルを作成します（この skill では、完全な定義を GLOSSARY.md に開示しています）。複数の使い方がある skill もあり、それぞれ異なる使い方が 分岐となります。つまり、異なる runs が skill 内を異なる経路で進みます。分岐は、開示の必要性を見極める最も明確な基準です。すべての分岐で必要な内容はインラインで記述し、一部の分岐からしか参照されない内容はポインターの先に置きます。資料に agent がいつ、どれほど確実にたどり着けるかを決めるのは、対象ファイルではなく、コンテキストポインターの 文言 です。

階層は内容を どこまで下層に移すか を決め、併置は移した内容の 隣に何を置くか を決めます。ある概念の定義、ルール、注意事項は、あちこちに散らさず、同じ見出しの下にまとめます。そうすることで、一部を読む際に関連項目も一緒に確認できます。

分割するタイミング

粒度とは skill の分割の細かさです。分割するたびに、どちらか一方の負荷が生じるため、分割による利点がある場合にのみ分割します。分割方法は 2 つあります。

• 呼び出し単位 - 独立した 先頭の語句で自律的に呼び出すべき場合、または別の skill から利用する必要がある場合は、モデル呼び出し型の skill に分割します。常時読み込まれる新しい description に対してコンテキスト負荷を支払うことになるため、独立して利用できる価値が必要です。
• 手順の順序単位 - 後続の 手順（ある手順の完了後の手順）によって、agent が前の手順を急いで終わらせたくなる場合（早すぎる完了）は、一連の 手順を分割します。それらを視界の外に置くことで、agent は現在のタスクに対する調査作業をより多く行うようになります。

削減

それぞれの意味について、信頼できる唯一の情報源を設けます。これは権威ある場所を 1 つだけにすることです。そうすれば、動作を変更する際の編集箇所も 1 か所になります。

行ごとに関連性を確認します。skill の役割を今も支えていますか？

次に、行単位だけでなく、文ごとに不要な記述を探します。各文を個別に不要かどうか確認し、不要なら語句を削るのではなく、文全体を削除します。思い切って削除してください。不要と判断された文章の大半は、書き直すのではなく削除すべきです。

先導語

先導語とは、モデルの事前学習にすでに存在する簡潔な概念で、エージェントがスキルの実行時に思考の手がかりとして使うものです（例：lesson、fog of war、tracer bullets）。テキスト内で繰り返し登場し（必ずしもそうとは限りません。強力な先導語なら一度だけで十分な場合もあります）、分散した定義を積み重ねます。モデルがすでに持つ事前知識を引き出すことで、最小限のトークンで一連の行動を定着させます。

先導語は、予測可能性を二つの場面で高めます。本文では、_実行_を定着させます。エージェントはその語に出会うたび、同じ種類の行動を取ります。説明文では、_呼び出し_を定着させます。同じ語がプロンプト、ドキュメント、コードベースに存在すると、エージェントはその共通言語をスキルに結び付け、より確実に呼び出すようになります。

スキルを先導語を使う形に再構成できる箇所を探しましょう。三つ組を三か所で繰り返し説明している部分（重複）や、一つの概念を説明するのに一文を費やしている説明文——どの段落も、単一トークンにまとめるべき箇所です。たとえば：

• 「fast, deterministic, low-overhead」→ tight——一つの段階で繰り返し述べている一つの性質を、事前学習済みの一語にまとめます（一つの tight loop）。
• 「a loop you believe in」→ red——曖昧なゲートを、二値で観察可能な状態に変えます（バグによってループが red になるか、ならないか）。

トークンを減らせる_だけでなく_、エージェントが思考を結び付ける、より明確なフックも得られます。すべてのスキルには、先導語に置き換えられる重複した説明が含まれていると考えて、それらを探しましょう。

失敗パターン

ユーザーがスキルを使う際に遭遇する可能性のある問題の診断に使います。

• 早すぎる完了 - 現在のステップが本当に完了する前に終わり、注意が_完了した状態_へ移ってしまいます。対処する順序：まず完了条件を明確にします（低コストで、影響範囲も限定的です）。それでも避けられないほど曖昧で、かつ 急いで終わらせる様子が見られる場合に限り、完了後のステップを分割して隠します（シーケンスの分割）。
• 重複 - 同じ意味が複数の箇所に存在します。保守コストを増やし、トークンを浪費し、その意味が実際の階層以上に重要であるかのように見せてしまいます。
• 堆積 - 追加は安全に見え、削除にはリスクがあるように思えるため、古くなったレイヤーが積み重なります。刈り込みの規律がないスキルは、どれも最終的にこの状態になります。
• 肥大化 - どの行も有効で重複がなくても、スキルが長すぎる状態です。可読性と保守性を損ない、トークンを浪費します。対処法は階層化です。リファレンスをポインターの先に置き、分岐やシーケンスごとに分割して、各経路が必要なものだけを持つようにします。
• 無意味な指示 - モデルがデフォルトで行うことを一行で指示するため、読み込ませても何も伝わりません。テスト方法：デフォルトの行動を変えるかどうかです。弱い先導語（エージェントがすでにおおむね徹底している場合の be thorough など）は無意味な指示です。対処法は、手法を変えるのではなく、より強い語（relentless など）に置き換えることです。
• 否定形 - 禁止による誘導は逆効果です。don't think of an elephant と言うと、象の名を挙げることで、考えにくくするどころか、かえって思い浮かびやすくします。肯定形でプロンプトを作り、目標とする行動を直接伝えて、禁止したい行動には触れないようにします。肯定形で表現できない厳格なガードレールに限り、禁止を残します。その場合も、代わりにどうすべきかを併記します。