writing-great-skills

確率的なシステムから決定性を引き出すスキルが存在します。予測可能性、つまり毎回同じ出力を生成することではなく、エージェントが毎回同じ プロセス を実行することが、最も重要な美徳です。以下のあらゆる手段は、その実現に役立ちます。

太字の用語はGLOSSARY.mdで定義されています。詳しい意味はそちらで確認してください。

呼び出し

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

• モデル呼び出し型のスキルには説明が残るため、エージェントが自律的に実行でき、ほかのスキルからも呼び出せます（名前を入力して呼び出すこともできます）。コンテキスト負荷が増え、説明が毎ターンのコンテキストに含まれます。設定方法：disable-model-invocationを省略し、モデル向けの説明に「ユーザーが…を望んでいるとき」「…について言及したときに使う」といった、幅広い呼び出し条件を記述します。
• ユーザー呼び出し型のスキルはエージェントから呼び出せなくなります。名前を入力して呼び出せるのはユーザーだけで、ほかのスキルからも呼び出せません。コンテキスト負荷はゼロですが、認知負荷がかかります。スキルが存在することを覚えておくための索引を、あなた自身 が担う必要があります。設定方法：disable-model-invocation: trueを設定します。descriptionは人向けとなり、トリガーの一覧を省いた1行の概要を記述します。

エージェントが自律的にスキルを呼び出す必要がある場合、またはほかのスキルから呼び出す必要がある場合に限り、モデル呼び出し型を選びます。手動でしか実行しないスキルは、ユーザー呼び出し型にしてコンテキスト負荷をなくします。

ユーザー呼び出し型のスキルが増え、覚えきれなくなった場合は、ルータースキルで認知負荷を解消できます。これは、ほかのスキルの名前と、それぞれを呼び出すタイミングを記した、ユーザー呼び出し型のスキルです。

説明を書く

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

• スキルの要点を表す語を先頭に置きます。説明はスキルの呼び出しに使われます。
• 分岐ごとにトリガーを1つにします。 1つの分岐を別の表現で言い換えた同義語は重複です。「TDDを使って機能を実装する…テストファースト開発を求めている」は、同じ分岐を二度記述しています。まとめて、本当に異なる分岐だけを残します。
• 本文ですでに示しているスキルの概要は削ります。説明にはトリガーと、「ほかのスキルから呼び出す必要がある場合」の条件だけを残します。

情報の階層

スキルは、手順とリファレンスという2種類のコンテンツで構成され、自由に組み合わせられます。スキルは手順だけ、リファレンスだけ、またはその両方で構成できます。重要なのは、どちらを使うか、そしてそれぞれを情報の階層のどこに置くかという判断です。情報の階層は、エージェントがその内容をどれだけすぐに必要とするかで順位づけされた段階です。

1. スキル内の手順 — SKILL.md に記載する、順序立てられたアクションです。最上位にあたり、エージェントが何をどの順番で行うかを示します。各手順は完了基準で終えます。これは、作業が完了したと判断できる条件です。基準は 確認可能（エージェントが完了と未完了を見分けられるか）にし、必要に応じて 網羅的（「変更一覧を作成する」ではなく「変更されたモデルをすべて説明する」）にします。曖昧な基準は早すぎる完了を招きます。
2. スキル内のリファレンス — SKILL.md に記載する、必要に応じて参照する定義、ルール、事実です。レビューに関するすべてのルールが同じ階層に並ぶように、妥当なフラットな集合となることもよくあります。これは適切な構成であり、問題ではありません。このスキルはすべてリファレンスです。
3. 外部リファレンス — SKILL.md から別ファイルに移し、コンテキストポインターを通じて参照するリファレンスです。ポインターの条件が満たされたときにのみ読み込まれます。（スキルの一部として残る GLOSSARY.md のような関連ファイルに記載された 明示的な リファレンスから、スキルシステムの外部にあり、どのスキルからも参照できる完全な外部リファレンスまで含みます。）

厳格な完了基準は、スキルに手順があるかどうかにかかわらず、徹底的な調査、つまり作業中にエージェントが行う掘り下げを促します。「すべてのルールを適用する」という基準は、「すべての手順を実行する」と同様に、フラットなリファレンスにも拘束力を持つためです。

情報を下位に移すのが少なすぎると最上位が肥大化し、多すぎるとエージェントが実際に必要とする内容が隠れてしまいます。このバランスが判断の要点です。

段階的な開示とは、SKILL.md からリンク先のファイルへと階層を下げ、最上位を読みやすく保つことです。仕組みとしては、スキルフォルダー内に、内容に応じた名前を付けたリンク先の .md ファイルを置きます（このスキルでは、定義の全内容を GLOSSARY.md で開示しています）。スキルには複数の使い方があるものもあり、それぞれ異なる使い方を分岐と呼びます。つまり、異なる実行がスキル内の異なる経路を進みます。分岐は、何を開示するかを判断する最も明確な基準です。すべての分岐で必要な内容はインラインにし、一部の分岐でしか使わない内容はポインターの先に移します。コンテキストポインターの到達先ではなく、その 文言 によって、エージェントがいつ、どれだけ確実に内容にたどり着くかが決まります。

階層が個々の要素を どこまで下げるか を決めるのに対し、同所配置は、要素をそこに置く際に 何を隣り合わせるか を決めます。概念の定義、ルール、注意事項は、あちこちに散らさず、ひとつの見出しの下にまとめます。そうすれば、ある部分を読むと関連する内容も一緒に目に入ります。

分割するタイミング

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

• 呼び出し単位で分割 — 単独でそのスキルを起動すべき明確な先頭語がある場合、または別のスキルからそのスキルに到達させる必要がある場合は、モデルが呼び出すスキルとして切り出します。新たに常時読み込まれる説明によってコンテキスト負荷が生じるため、独立して呼び出せる価値がそれに見合う必要があります。
• 手順の順序で分割 — まだ先にある手順（ある手順の完了後の手順）が、エージェントに現在の手順を急がせ、早すぎる完了を招く場合は、手順の連なりを分割します。先の手順を見えないようにすることで、現在のタスクに対してより多くの調査を行えるようになります。

そぎ落とし

それぞれの意味は、信頼できる唯一の情報源にまとめます。動作を変更する際に、編集箇所が1か所で済むよう、権威ある場所をひとつにします。

すべての行について関連性を確認します。その内容は、スキルの機能に今も関係していますか？

続いて、行ごとではなく、文ごとに不要な記述を探します。各文を単独で不要かどうか判定し、不要だとわかったら、単語を削るのではなく文全体を削除します。大胆に削ってください。不要と判定された文章の大半は、書き直さずに削除するべきです。

先導語

先導語とは、スキルの実行中にエージェントが思考に用いる、モデルの事前学習にすでに存在する簡潔な概念です（例：レッスン、戦場の霧、トレーサー弾）。テキスト内で繰り返し使われることで（必ずしも繰り返す必要はありません。強力な先導語なら一度だけで足りることもあります）、分散した定義が積み重なり、モデルがすでに持つ事前知識を呼び起こして、最小限のトークンで行動のまとまり全体の基盤になります。

先導語は、二つの面で予測可能性を高めます。本文では、エージェントがその語の登場時に毎回同じ振る舞いを選ぶことで、_実行_の基盤になります。説明では、同じ語がプロンプト、ドキュメント、コードに使われていると、エージェントがその共通言語をスキルに結び付け、より確実に起動することで、_呼び出し_の基盤になります。

先導語を使うよう、スキルを再構成できる箇所を探してください。3か所で明記されている三つ組（重複）や、ある考えを示すためだけに一文を費やしている説明は、どれも一つのトークンに集約できる箇所です。たとえば次のとおりです。

• 「高速、決定論的、低オーバーヘッド」→ タイト — あるフェーズの品質を言い換えた表現を、事前学習済みの一語に集約します（_タイト_なループ）。
• 「信頼できるループ」→ レッド — あいまいなゲートを、観測可能な二値状態に変えます（バグがあればループは_レッド_になり、なければそうなりません）。

どちらも得られます。トークンを減らし、エージェントが思考を組み立てるための、より明確な手掛かりになります。どのスキルにも、先導語で置き換えられる言い換えが含まれていると考え、それを見つけてください。

失敗モード

ユーザーがスキルで直面している可能性のある問題を診断する際に、次の項目を使ってください。

• 早すぎる完了 — 本当に完了する前にステップを終え、意識が_終わらせること_に移ってしまうこと。対策は順に、まず完了基準を明確にすること（低コストで局所的です）。それでも本質的にあいまいで、かつ急いで終えようとする様子が見られる場合に限り、分割（シーケンスの分割）によって完了後のステップを見えにくくします。
• 重複 — 同じ意味が複数の場所にあること。保守コストとトークン数が増え、その意味の重要度が実際の順位を超えて、序列の中で過剰に高まります。
• 堆積物 — 追加するのは安全に感じられ、削除するのはリスクに感じられるため、古い層が積み重なること。整理する習慣のないスキルがたどる、典型的な行く末です。
• 肥大化 — すべての行が有効で重複していなくても、スキルが単に長すぎること。可読性と保守性を損ない、トークンを浪費します。対策は序列です。ポインターの先にある参照先を明示し、分岐またはシーケンスごとに分割して、各経路に必要なものだけを残します。
• 効果なし — モデルが既定ですでに従う行であり、何も伝えないために読み込みコストを払っている状態です。判定方法は、既定の振る舞いと比べて行動が変わるかどうかです。弱い先導語（エージェントがすでにある程度は徹底しているのに「徹底する」）は効果がありません。別の手法ではなく、より強い語（「執拗に」）に置き換えてください。
• 否定表現 — 禁止によって誘導すると逆効果になります。「ゾウのことを考えるな」はゾウを名指しするため、考えにくくするどころか、かえって思い浮かびやすくします。肯定形で促してください。禁止したい振る舞いを言葉にせず、目標とする振る舞いを示します。肯定形では表現できない厳格な安全策に限り禁止表現を残し、その場合も代わりに何をすべきかを併記してください。