writing-great-skills

スキルは、確率的なシステムから決定性を引き出すために存在します。予測可能性 — 同じ出力を生成することではなく、エージェントが毎回同じ プロセス に従うこと — が根本的な美徳です。以下の仕組みはすべて、この美徳に役立ちます。

太字の用語はGLOSSARY.mdで定義されています。完全な意味については、そちらを参照してください。

呼び出し

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

• モデル呼び出し型スキルは説明を保持するため、エージェントが自律的に呼び出せる_だけでなく_、ほかのスキルからも呼び出せます（名前を入力して呼び出すこともできます）。コンテキスト負荷が発生します — 説明が毎ターン、コンテキストウィンドウに残ります。仕組み：disable-model-invocationを省略し、モデル向けのトリガー表現を豊富に含む説明を記述します（「ユーザーが…を望んでいるとき、…に言及したときに使用する」）。
• ユーザー呼び出し型スキルは、エージェントが参照できる範囲から説明を取り除きます。呼び出せるのは、名前を入力したあなただけです — ほかのスキルからも呼び出せません。コンテキスト負荷はゼロですが、認知負荷が発生します。スキルの存在を覚えておく必要があるのは、_あなた_です。仕組み：disable-model-invocation: trueを設定します。descriptionは人向けになり、1行の要約にして、トリガーのリストを取り除きます。

エージェント自身がスキルにアクセスする必要がある場合、または別のスキルからアクセスする必要がある場合に限り、モデル呼び出し型を選びます。手動でしか呼び出さないスキルは、ユーザー呼び出し型にしてコンテキスト負荷をゼロにします。

ユーザー呼び出し型スキルが、覚えておける数を超えて増えてきた場合、その累積した認知負荷はルータースキルで解消できます。これは、ほかのスキルと、それぞれを使う場面を示すユーザー呼び出し型スキルです。

説明を書く

モデル呼び出し型の説明には、スキルの内容を示すことと、スキルを呼び出すべき分岐を列挙することの2つの役割があります。単語が増えるたびにコンテキスト負荷も増えるため、説明は本文よりもさらに厳しく削る必要があります。

• スキルを表す最初の語を先頭に置きます — 呼び出しに関する役割を果たすのは説明です。
• 分岐ごとにトリガーを1つにします。 1つの分岐を別の言い方で表す類義語は重複です — 「TDD を使った機能の構築…テストファースト開発を求めている」は、同じ分岐を2度書いています。まとめて、本当に異なる分岐だけを残します。
• 本文ですでに説明している内容は削ります。 説明にはトリガーだけを残し、必要に応じて「別のスキルが必要とするとき」のような範囲指定を加えます。

情報階層

スキルは、steps と reference の2種類の内容で構成され、自由に組み合わせられます。スキルは steps のみ、reference のみ、または両方で構成できます。重要なのは、どちらを使うか、そしてそれぞれを information hierarchy のどこに置くかという判断です。これは、エージェントがその内容をどれだけすぐ必要とするかに応じた階層です。

1. In-skill step — SKILL.md 内の順序付きアクションで、主要な階層です。エージェントが何をどの順番で行うかを示します。各 step は completion criterion で締めくくります。これは、作業が完了したことをエージェントに示す条件です。checkable（エージェントが完了と未完了を区別できるか？）にし、重要な場合は exhaustive（「変更されたすべての model を記録する」であり、「変更一覧を作成する」ではない）にしてください。曖昧な基準は premature completion を招きます。
2. In-skill reference — 必要に応じて参照する、SKILL.md 内の定義、ルール、事実です。多くの場合、フラットなセットで問題ありません（review のすべてのルールを同じ階層に置くなど）。これは洗練された構成であり、欠点ではありません。このスキルはすべて reference です。
3. External reference — SKILL.md から別ファイルに移し、context pointer 経由でアクセスする reference です。pointer が機能したときだけ読み込まれます。（これは、スキルの一部として残る GLOSSARY.md のような隣接ファイルといった disclosed reference から、どのスキルからでも参照できるスキルシステム外の external reference まで及びます。）

厳格な completion criterion は、スキルに steps があるかどうかにかかわらず、深い legwork（エージェントが作業の中で行う掘り下げ）を促します。「すべてのルールを適用する」は、フラットな reference を「すべての step を実行する」と同じように拘束するためです。

下に移す量が少なすぎると、上部が膨らみます。移しすぎると、エージェントが本当に必要とする内容を隠してしまいます。この緊張関係こそが、判断のすべてです。

Progressive disclosure とは、階層を下へ進み、SKILL.md からリンクされたファイルへ移すことで、上部を読みやすく保つ方法です。仕組みとしては、スキルのフォルダー内にリンクされた .md ファイルを置き、内容に応じた名前を付けます（このスキルでは、定義の全容を GLOSSARY.md に開示しています）。スキルには複数の使い方があるものもあり、異なる使い方はそれぞれ branch です。つまり、スキル内で異なる経路をたどる実行です。Branching は disclosure を判断する最も明確な基準です。すべての branch が必要とする内容はインラインに置き、一部の branch だけが参照する内容は pointer の先に移します。context pointer の wording が、参照先ではなく、エージェントがその内容にアクセスするタイミングと確実性を決めます。

階層が各要素を どれだけ下に 置くかを決める一方、co-location は、そこに置くと決めた後で 何を隣に置くか を決めます。概念の定義、ルール、注意点は、あちこちに散らさず一つの heading の下にまとめてください。そうすれば、一部を読むだけで関連項目も合わせて確認できます。

分割するタイミング

Granularity とは、スキルをどれだけ細かく分割するかです。分割のたびに2種類の load のいずれかを消費するため、分割するのは、その価値がある場合に限ります。分割には2つの方法があります。

• Invocation ごと — 単独でスキルを起動する固有の leading word が必要な場合、または別のスキルから呼び出す必要がある場合は、model-invoked スキルを分割します。新たに常時読み込まれる description の context load が発生するため、独立した到達性には、それに見合う価値が必要です。
• シーケンスごと — 後続の steps（ある step の post-completion steps）によって、エージェントが現在の作業を急いで終えようとする（premature completion）場合は、steps のシーケンスを分割します。後続の手順を見えない状態にしておくと、エージェントは現在のタスクでより多くの legwork を行いやすくなります。

プルーニング

各意味を single source of truth として保ちます。つまり、動作を変更するときに1か所だけ編集すれば済むよう、権威ある場所を一つにします。

各行を relevance の観点から確認します。今もスキルの動作に影響しますか？

次に、行単位だけでなく、文ごとに no-op を探します。各文を単独で no-op test にかけ、該当する文があれば、言葉を少し削るのではなく文全体を削除してください。思い切って削除しましょう。no-op test に通らない文章の大半は、書き換えるのではなく削除すべきです。

リーディングワード

リーディングワードとは、モデルの事前学習にすでに含まれている簡潔な概念で、スキルの実行中にエージェントが思考する際に使うものです（例：lesson、fog of war、tracer bullets）。テキスト全体で繰り返し使うことで（必ずしも繰り返す必要はなく、強力なリーディングワードなら一度だけで十分な場合もあります）、分散した定義が積み重なり、最小限のトークン数で行動全体の領域を定着させ、モデルがすでに持つ事前知識を呼び起こします。

リーディングワードは、予測可能性を二重に高めます。本文では、_実行_を定着させます。その言葉が現れるたびに、エージェントは同じ振る舞いにたどり着きます。説明文では、_呼び出し_を定着させます。同じ言葉がプロンプト、ドキュメント、コードにあれば、エージェントはその共通言語をスキルに結び付け、より確実に呼び出します。

スキルをリーディングワードでリファクタリングできる箇所を探しましょう。3か所で同じ3要素を列挙している箇所（重複）や、ある考えを示すためだけに説明文で一文を使っている箇所は、いずれも1つのトークンに集約できる余地があります。例：

• 「速く、決定論的で、オーバーヘッドが少ない」 -> tight — あるフェーズ全体で言い換えられている性質を、事前学習済みの1語にまとめます（tight なループ）。
• 「信頼できるループ」 -> red — 漠然としたゲートを、観測可能な二値状態に変えます（バグがあるとループは red になる、そうでなければならない）。

二重の効果が得られます。トークン数を減らせるうえに、エージェントが推論を掛けるための、より明確なフックができます。すべてのスキルには、リーディングワードで置き換えられる言い換えが含まれていると考え、それを見つけましょう。

失敗モード

これらは、ユーザーがスキルで直面している可能性のある問題を診断するために使います。

• 早すぎる完了 — 本当に完了する前にステップを終え、意識が_準備が整った状態_へと逸れてしまうことです。対策は次の順で行います。まず完了条件を明確にします（低コストで局所的な対策です）。完了条件がどうしても曖昧なまま_であり_、急いでいる様子も見られる場合に限り、シーケンスを分割して完了後のステップを隠します（シーケンスによる分割）。
• 重複 — 同じ意味が複数箇所にあることです。保守コストとトークン数が増え、階層内での意味の目立ちやすさが、本来の順位よりも高くなります。
• 堆積 — 追加は安全そうに見える一方、削除はリスクがあるように見えるため、古くなった層が積み重なることです。プルーニングの規律がないスキルは、どれも最終的にこの状態になります。
• 肥大化 — 各行が有効で重複していなくても、スキルが単に長すぎることです。可読性と保守性を損ない、トークンを浪費します。階層構造で対処しましょう。リファレンスはポインターの先に置き、分岐またはシーケンスごとに分割して、各経路で必要な情報だけを持たせます。
• ノーオペレーション — モデルがデフォルトですでに従う行なので、何も伝えていないのに読み込みコストが発生します。テスト方法は、その行がデフォルトの振る舞いを変えるかどうかです。弱いリーディングワード（エージェントがもともとある程度徹底しているのに「徹底する」など）はノーオペレーションです。修正するには、別の手法ではなく、より強い言葉（relentless など）を使います。
• 否定 — 禁止によって指示すると逆効果になります。「象のことを考えないで」と言うと象に言及することになり、象を考えやすくしてしまいます。肯定形でプロンプトを書き、目標とする振る舞いを明示して、禁止したい内容には触れないようにします。禁止表現は、肯定形では言い換えられない厳格なガードレールに限って使い、その場合でも代わりに何をすべきかを併記します。