writing-skills

スキルの作成

スキルが存在する理由

スキルは、確率的なシステムから不確実性を取り除きます。根本となる美徳は予測可能性です。エージェントが実行のたびに同じプロセスをたどることであり、同一の出力を生成することではありません。ブレインストーミングのスキルは、確実に発想を広げるべきです。トークンは変わっても、振る舞いは変わりません。このドキュメントのすべてのルールは、予測可能性を高めるための手段です。

鉄則

NO NEW SKILL AND NO EDIT TO A SKILL SHIPS WITHOUT A FAILING TEST FIRST

スキルの作成は、プロセスのドキュメント化にテスト駆動開発を適用することです。サイクルは次のとおりです。

1. RED — 失敗を確認します。 スキルなしでシナリオを実行します（編集の場合は、現行バージョンで実行します）。実際に起きた失敗と、それを正当化する説明を一字一句そのまま記録します。これらが、テキストで防ぐべきことを定義します。ベースラインのエージェントが失敗しない場合は中止してください。修正すべきことはなく、失敗の裏付けがないテキストは何の効果もありません。
2. GREEN — 必要最小限のテキストを作成します。 記録した失敗に対処するための最小限のスキルテキストだけを書きます。仮定上の失敗への対処は不要です。同じシナリオを、スキルを適用して再実行します。従わない場合、またはテキストが不明瞭な場合は、修正して再実行します。
3. REFACTOR — 抜け穴を塞ぎます。 プレッシャーがかかると、エージェントは新たな正当化を考え出します。それぞれを一字一句そのまま記録し、明示的な対策を追加して再テストします。最大のプレッシャーの下でもスキルが機能するまで繰り返します。

ベースラインを実行する前にテキストを書きましたか？ それはエージェントが実際に何を誤るかではなく、何を誤ると推測したかを記録したものです。今すぐベースラインを実行してから、記述を残すか判断してください。

シナリオの構築、プレッシャーの種類、マイクロテスト、説明文によるトリガー、非ゲート（テクニック／リファレンス）テスト、メタテストを含むテスト手法は、このファイルと同じ場所にある pressure-testing.md に記載されています。テストを実行する前にお読みください。従うよう促す表現技法は、influence-principles.md に記載されています。

失敗に形式を合わせる

何かを書く前にベースラインの失敗を分類してください。ある種類の失敗を修正する形式が、別の種類の失敗を確実に悪化させる場合があります。

ベースラインの失敗	こちらを書く	こちらは書かない
ルールを理解しているが、プレッシャーがかかると破る	厳格な禁止事項＋正当化の一覧（考え方 → 実態）＋危険信号のリスト	「できれば／検討してください」といった柔らかい指針
指示には従うが、出力の形式が正しくない	肯定的な手順、または契約：出力がどのようなものか、その構成要素と順序を明示する	禁止事項。競合する動機があると、エージェントは「X をしてはいけない」という指示を交渉の余地があるものとして扱います。直接比較する表現テストでは、禁止事項を示した群が、指針なしの群よりも望ましくない内容を多く生成しました。手順を示せば、交渉の余地がなくなります
すでに作成しているものから要素を省く	エージェントが記入するテンプレート内の必須項目	テンプレート付近に置く文章での注意書き
振る舞いが条件に応じて変わるべき	観察可能な条件に基づく条件文（「design.md が存在する場合は、その継ぎ目を引用する」）	例外条項を加えた無条件のルール
絶対に省略したり誤判定したりしてはならない確認	スキルがエージェントに実行させて結果を読み取らせる、決定的なプリミティブによる手順。固定された grep／git／スキーマのチェックと、その出力に対する固定ルールです（trace を参照）	確認について抽象的に説明する文章。「網羅性を確認する」は解釈の余地を生みます。名前の付いた入力に対して名前の付いたチェックを実行し、その結果にルールを設ければ、解釈の余地は生じません

例外を加える文言は禁止です。 「重要な場合を除き、X をしてはいけない」とすると、ルールが閉じたはずの交渉の余地が再び生まれます。効果のあった手順に例外を一つ付け足すだけで、一貫性が失われ、雑音が増えます。実際の例外は、観察可能な条件に基づく独立した条件文にしてください。免除条項も対象を限定できません。「制限はコードブロックには適用されない」としても、コードブロックが抑制されることに変わりはありません。ルールが免除対象に及ばないよう、構成を組み替えてください。

Frontmatter と命名

• description には、トリガーと成果を記述し、ワークフローは記述しません。 スキルが生み出す 成果物（成果を表す名詞。「tasks.md の実装計画」「2 軸のレビュー判定」など）と、スキルがいつ起動するかを記載し、手順を要約してはいけません。プロセスの要約があると、エージェントは本文を読む代わりに近道としてそれに従ってしまいます。「設計が承認され、tasks.md の計画を作成する必要があるときに使用する」なら本文が読まれますが、「計画時に使用 — タスク間でレビュアーを割り当てる」なら要約に従い、本文は無視されます。これにより、外部ルールの 2 つの要件（何をするかといつ使うかを記載する）と、本文が読み飛ばされる問題の両方を満たせます。成果を表す名詞は多数のスキルの中から該当するものを見分けやすくし、手順の列挙は危険を招きます。「何をするか」は成果として記述し、「何をするか」をワークフローとして記述するのは禁止します。
• 動詞から始まる名前：writing-skills、receive-review、debug のように、トピックではなくアクションに名前を付けます。
• キーワードを網羅する：エージェントやユーザーが実際に検索したり思い浮かべたりする語句を、症状、エラーの文字列（error、exception、e2e、tech debt）、ツール名やファイル名（tasks.md）、類義語（spike、mock up）など、description に盛り込みます。スキルの発見はキーワードの一致で決まります。誰にも見つけられないスキルは、存在しないのと同じです。成果を表す名詞にも、ここで同じ役割を持たせます。
• 両方向の失敗を、推測ではなくテストします。 要約しすぎると前述の問題が起きます。一方、よくあるのはこちらの問題です。仕様が不十分だと、スキルがまったく起動しません。キーワードの網羅と成果を表す名詞で後者に対処し、ワークフローの手順を省くことで前者に対処します。description はスキルの中で最も効果の高い行であり、目視では判断できない唯一のフィールドです。pressure-testing.md に従ってトリガーテストを行ってください。
• プロジェクト内の慣例 — 自己起動のために、一般的なガイダンスから意図的に逸脱しています。 説明は二人称の「Use when…」で始めます。この行が、判断を行うエージェントへの直接的な指示として読めるためです。読み飛ばしてはいけない内容には、一般的な ## Critical 見出しに相当するプロジェクト内の慣例として、## Red Flags、## The Iron Law、または <NON-NEGOTIABLE> ブロックを使います。どちらの慣例も全体で統一してください。スタイルを混在させた例外は多様性ではなく、統一性の崩れです。
• ユーザーが起動するスキルには disable-model-invocation: true を付けます。これにより、自動起動できなくなり、スキル本文からエージェントに別のスキルの起動を指示することもできなくなります。ユーザーが起動するスキルへの引き継ぎは、ユーザーが実行するスキル名（/handoff、/release）を指定する場合に限ります。REQUIRED SUB-SKILL: use \x` を使えるのは、モデルが起動できる対象だけです。disable-model-invocation` が設定されたスキルをエージェントに起動させる指示は、行き止まりの引き継ぎであり、文体上の些細な問題ではなく、実際のバグです。
• 説明の対象読者は 2 種類あり、上記のルールはすべてモデル向けの説明に関するものです。 モデルが起動できるスキルの説明は、キーワードの網羅、症状を表す語句、成果を表す名詞によって、スキルの選択につなげます。一方、disable-model-invocation が設定されたスキルの説明は、選択には何も役立ちません。エージェントには表示されず、ユーザーはスキル名を入力して起動するからです。この場合は、成果物を示す、人間向けの簡潔な 1 行を書きます。ユーザーが起動するスキルの説明にキーワードを詰め込んでも、誰も読むことのない文章にしかなりません。「発見は引き続きユーザーが入力する語句に左右される」という説明は誤りです。ユーザーが入力するのはスキル名です。

語彙

以下の用語を使ってスキルを書き、それらに照らしてスキルをレビューしてください。

• 先頭語 — モデルが事前学習ですでに身につけている簡潔な概念（「seam」「tracer bullet」「red」など）で、わずかなトークンで行動の広い範囲を定着させます。トークンとして繰り返すことで、スキル全体に分散した定義が蓄積されます。言い換えを3文重ねても、そのような単語1つに集約されることがよくあります。造語には事前学習による連想がないため、まずは事前学習済みの単語を使ってください。
• 完了条件 — 各ステップは、エージェントが確認できる条件で終わらせてください（「スイートがすべて成功し、出力に問題がない」であって、「テストは問題なさそう」ではありません）。これは早すぎる完了を防ぐ手段です。境界が曖昧だと、注意が作業ではなく 完了すること に向いてしまいます。
• ノーオプテスト — この行は、スキルがまったくない場合と比べて行動を変えますか？行が事実に即し、関連性があっても、ノーオプであることはあります（「注意してください」など）。既定の動作が何かという議論は、口論ではなくシナリオを実行して決着させてください。テストに通らない文は、削って短くするのではなく、文全体を削除してください。
• 重複 — 1つの意味に2つ目の居場所を与えることです。これは、注意を集中させるために トークン を繰り返す先頭語とは意図的に逆のものです。重複では 意味 を繰り返すため、動作を変える際に複数箇所の編集が必要になり、言い換えたルールが本来の重要度以上に重みのあるものとして読まれます。ノーオプの精査では見つかりません。各コピーはそれぞれ有効で、単独でもテストに通るためです。そのため、重複は別途精査してください。各ルールの唯一の居場所を明確にし、それ以外の箇所にある同じ内容の記述は、すべてその居場所への参照に置き換えるか、削除してください。所定のゲート形式は例外です。## Red Flags の箇条書きや合理化の行が意図的にルールを繰り返すのは、失敗テーブルが求める対抗策としてであり、ルールの症状を示すものであって、2つ目の居場所ではありません。言い換えを重複とみなすのは、両方の箇所が通常の文章である場合に限ります。
• 否定の罠 — 禁止事項を述べると、禁止対象の行動が文脈に入り込み、指示のようにも読めてしまいます。禁止パターンを一切口にしないよう、「1行コメントを書く」のように肯定形で促してください。唯一の例外はプレッシャーゲート型スキルです。この場合は、厳格な禁止事項と明示的な対抗策を組み合わせるのがまさに適切です。上記の失敗テーブルを参照してください。
• 情報階層 — スキル内の手順、次にスキル内の参考情報、その次にコンテキストポインター経由で開示する参考情報の順です。すべての実行で必要な内容はインラインにし、一部の分岐でしか必要とされない内容はポインターの先に置いてください。資料が読み込まれるかどうかを決めるのは、ポインターの参照先ではなく 文言 です。必読ファイルを弱いポインターの先に置くと、読み込みが不安定になります。内容をインラインにする前に、ポインターを明確にしてください。参考ファイルは SKILL.md から 1階層以内 に置いてください（別のファイル経由でしかたどれないファイルは、読まれずにざっと見られるだけです）。約100行を超える参考資料には、冒頭に目次を付けてください。
• トークン予算 — セッションに挿入されるスキルは最小限にしてください。トークンは毎ターン消費されます。3段階の読み込みレベルで予算が決まります。メタデータ（名前と説明、約100トークン）は、すべてのセッションのすべてのターンで消費されます。本文は スキルが発動した後のすべてのターン で消費され、参考ファイルはポインターをたどるまでコストがかかりません。規律を扱うスキルは、中核となる本文を約500語以内にしてください（表とコードブロックを除く）。SKILL.md 本文の厳格な上限は 約500行／5,000語 です。それを超える詳細は、ポインターの先に分割してください。すべての行が有効であっても、長さ自体が失敗の原因になります。

そもそも書かないほうがよい場合

機械的にチェックできるルールがあるからといって、スキルを省略する理由にはなりません。スキルにチェック方法を説明させるのではなく、チェックを実行させる理由になります。リポジトリに既存の強制ツール（既存のリンター、CI のスキーマチェック、Git フック）がある場合、スキルはそれを示し、その結果を読み取ります。そうでない場合（このセットは利用するリポジトリに何もインストールしないため、こちらが一般的です）、スキル自体に決定論的な手順を含めます。つまり、エージェントが実行する正確な grep／git／スキーマチェックと、その出力に適用する正確なルールです。スキルが、チェック手順にすでに含まれているルールを何も追加せず、冗長に言い換えたものになってはいけません。ドキュメントのコンテキスト予算を使う価値があるのは、チェックでは判断できないケースです。決定論的な部分は散文ではなく、正確なチェック手順に記述します。

分割する場合

スキルを分割するのは、次の2つの場合に限ります。

1. 明確に異なるトリガーがある場合。 独立して起動する別の条件や先頭の語がある場合、または別のスキルから独立して呼び出す必要がある場合です。
2. 完了後の手順を隠している場合。 後続の手順が、現在の手順をエージェントに急がせる明らかな誘因になっており、分割によってそれらを実際のコンテキスト境界（サブスキルへの引き継ぎ、またはサブエージェントのディスパッチ）の向こう側に置ける場合です。インラインで言及してもコンテキスト内に残るため、何も隠せません。

それ以外は、粒度を細かくすること自体が目的になっており、コンテキストの負荷やユーザーの記憶力というコストがかかります。

例

凡庸な例をたくさん並べるより、優れた実例を1つ示すほうが効果的です。実際のシナリオをもとに、完全で実行可能な例を、WHY（なぜそうするのか）がわかるコメント付きで、最も関連性の高い言語で示します。5つの言語に移植したり、空欄を埋めるだけのテンプレートにしたりしないでください。

相互参照

このセット内の他のスキルは、散文で参照してください。たとえば REQUIRED SUB-SKILL: use \verify`のように記述し、別のスキルのフォルダー内にあるファイルへのリンクは使わないでください。リンクは読み込みを強制し、フォルダー同士を密結合させます。自身のSKILL.md` と同じ場所にあるファイルは相対ファイル名で参照し、いつ読み込むべきかを示す文言を添えてください。

よくある合理化

考え	実際
「スキルは明らかにわかりやすい」	書いた本人にとってわかりやすいという見方だけは、決して判断材料になりません。実行してください
「小さな編集だ」	編集によってスキルが退行することも、コードと同じです。まず旧バージョンを基準に比較してください
「ドキュメントをテストするなんて大げさだ」	テストされていないスキルは本番で失敗し、失敗するたびにセッション全体が無駄になります
「読み返せば、ほぼテストしたことになる」	読み返しで確認できるのは流暢さであり、動作ではありません。何もしないテストに答えられるのは実行だけです
「問題が起きたら直せばいい」	エージェントがスキルを黙って無視することで問題が起きます。失敗に気づくことはありません
「複数のスキルをまとめて処理するほうが効率的だ」	テストされていないスキルをまとめるのは、テストされていないコードをまとめるのと同じです

デプロイチェックリスト

各項目にTODOを作成してください。

RED

• pressure-testing.md に従ってプレッシャーシナリオを作成済み（ゲートスキルでは、複数のプレッシャーを組み合わせたものを3つ以上）
• モデルの一覧を明記済み。スキルを提供する各モデルでベースラインを実行し、各トランスクリプトにモデル名を記載済み
• スキルなし（または旧バージョン）でベースラインを実行済み。失敗と正当化を一字一句記録済み
• ベースラインで実際に失敗したことを確認済み。そうでなければ中止してください。書くことはありません

GREEN

• 失敗を分類済み。それに合った形式を使用（禁止事項の列挙／手順／必須スロット／観察可能な条件）
• 説明はトリガー＋結果を表す名詞のみとし、ワークフローの手順は含めない。名前は動詞から始め、ユーザーが入力する具体的なキーワードを含める
• 説明のトリガーをテスト済み。起動すべきクエリ／起動すべきでないクエリを実行し、両方向を確認済み（pressure-testing.md に従う）
• 記録した失敗への対処に必要な最小限のテキストを使用。具体例は最大1つ
• 一覧内のすべてのモデルでスキルを有効にして再実行済み。最も性能の低いモデルが準拠することを確認済み

REFACTOR

• 新たな正当化に明示的に対処済み。正当化の表と危険信号の一覧を作成済み（ゲートスキル）
• 動作を促す文言を細かくテスト済み。スキルなしの対照テスト、各サンプルでの新しいコンテキスト、5回以上の反復を実施し、フラグが立ったトランスクリプトをすべて手作業で確認済み
• メタテストを実施済み。テスト対象のエージェントがテキストを明確だと確認し、準拠を容易にする要素があったか尋ねても、何も挙げなかった
• 新たな正当化が現れなくなるまで再テスト済み

Ship

• 不要箇所の確認：すべての文が不要箇所テストに合格するか、文全体を削除済み
• 重複の確認（別のパスで実施。不要箇所の確認では重複を検出できません）：各ルールに明確な定義箇所を1つだけ設け、言い換えは削除するか参照に置き換え済み
• すべての disable-model-invocation の説明を、人間向けの簡潔な一文にする。トリガーキーワードや症状を表す語は含めない
• 本文をトークン予算内に収める（約500行／5,000語以下）。参照資料は適切に記述したポインターの先に開示し、階層は1段までにする。100行を超える参照資料には目次を付ける
• 相互参照は REQUIRED SUB-SKILL の文章にする。補助ファイルは相対名で参照する
• すべての引き継ぎで、モデルから呼び出し可能なスキルのみを実行する。disable-model-invocation の対象は、実行せずにユーザーが実行するものとして明記する
• 構造とルーティングを確認（エージェントが実行）：フロントマターが有効（name と description を含む。ユーザーが実行するスキルでは disable-model-invocation: true を設定）、名前が動詞から始まる、本文が行数の上限内であることを確認する。さらに、説明のトリガーを手作業でテストする。pressure-testing.md に従って起動すべきクエリと起動すべきでないクエリを実行し、それぞれが意図どおりにルーティングされることを確認する

スキルをまとめて作成しないでください。 次のスキルに着手する前に、1つのスキルを最後まで作成し、テストして、検証してください。