author-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／スキーマ検査と、その出力に対する固定ルール（audit-trace を参照）	チェックを抽象的に説明する文章。「網羅性を確認する」では解釈の余地が生まれます。一方、名前が付いた入力に対して名前が付いた検査を行い、その結果にルールを適用すれば、解釈の余地は生まれません

一般論ではなく、記録された結果を反証に使ってください。 ベースラインから、失敗によって実際に何が失われたのかが分かります。リベースでひそかに消えたコミット、到達しかけた課金経路、5回中4回の実行で使われた近道などです。それらを文章に取り入れてください。一般論から書いた反証――「リリース後のリグレッションは納期遅れより深刻だ」――は正しいものの、どのスキルにも当てはまり、そのため交渉の余地が生まれます。そこには実際に起きたことが何もないからです。記録された結果は、仮定の話に矮小化して論破することができません。RED のトランスクリプトを1つ渡され、それに反論するよう求められた3つの草稿は、3つともすべての正当化を忠実に再現し、コストを大きくした具体的な事実をすべて落としていました。

微妙な例外条項を付けないでください。 「重要な場合を除いてXをしない」は、ルールが閉じた交渉を再開させます。効果のあったレシピに微妙な例外条項を1つ追加するだけで、一貫性が失われ、指示が不明瞭になります。実際の例外は、観察可能な述語に基づく独立した条件にしてください。例外条項は適用範囲を限定する効果もありません。「コードブロックには上限を適用しない」と書いても、コードブロックを抑制してしまいます。ルールが例外対象に及ばないよう、構成を変更してください。

フロントマターと命名

• description には、発動条件と成果を記述し、ワークフローは決して記述しません。 スキルが生み出す 成果物（「tasks.md の実装計画」「2 軸のレビュー判定」など、成果を表す名詞）と、発動するタイミングを明記します。手順を要約してはいけません。プロセスの要約があると、エージェントは本文を読まずにその近道に従ってしまいます。「設計が承認され、tasks.md の計画を作成する必要があるときに使用する」なら本文が読まれますが、「計画時に使用 — タスク間でレビュアーを割り当てる」なら要約だけが実行され、本文は無視されます。これは、外部ルールの 2 つの要件（何をするかといつ使うかを記述する）と、本文が読み飛ばされる問題を両立させます。成果を表す名詞は多数のスキルの中から識別するのに役立ちますが、手順のリストは危険のもとです。「何を」は成果として示し、「何を」はワークフローとして示さないようにします。
• 動詞で始まる名前：author-skills、vet-feedback、root-cause のように、トピックではなくアクションに名前を付けます。エンジニアリングスキルにはプレフィックスを付けません。これらがデフォルトの語彙だからです。一方、ライフパックには名前空間として life-（Personal OS）を付けます。両方のパックがインストールされると、プレフィックスのない動詞（capture、orient、replan）がエンジニアリングスキルの名前と衝突するためです。動詞を先頭にするルールは、プレフィックスの後に適用します：life-plan-day、life-review-week。プレフィックスは / メニューから選ぶ人のための識別子であり、ルーティング用ではありません。以下のキーワードルールに従い、スキルの検出は引き続き説明文に基づいて行われます。
• キーワードの網羅性：エージェントやユーザーが実際に検索したり考えたりする言葉、つまり症状、文字どおりのエラーテキスト（error、exception、e2e、tech debt）、ツール名やファイル名（tasks.md）、同義語（spike、mock up）を説明文に含めます。スキルの検出はキーワードの一致によって行われます。見つけられないスキルは、存在しないのと同じです。成果を表す名詞は、ここでも役割を果たします。
• 失敗には 2 つの方向があり、推測ではなく両方をテストします。 要約しすぎると、前述のような失敗が起こります。よりよくあるのは、指定不足です。スキルがまったく発動しません。キーワードの網羅性と成果を表す名詞は後者を防ぎ、ワークフローの手順を省くことは前者を防ぎます。説明文はスキルの中で最も効果の大きい行であり、目視だけでは判断できない唯一のフィールドです。pressure-testing.md に従って、発動テストを実施してください。
• チーム内の規約 — 自己呼び出しに対応するため、一般的なガイダンスから意図的に変更しています。 説明文は、判断するエージェントへの直接の指示として読めるよう、二人称の「Use when…」で始めます。飛ばしてはいけない内容には、一般的な ## Critical 見出しに相当するチーム内の規約として、## Red Flags、## The Iron Law、または <NON-NEGOTIABLE> ブロックを使います。どちらも一連のスキル全体で統一してください。異なるスタイルを混在させた例外は多様性ではなく、規約からの逸脱です。
• ユーザーが呼び出すスキルには disable-model-invocation: true を設定します。これにより自動では呼び出されなくなり、どのスキル本文にもエージェントにそれを呼び出すよう指示してはいけません。ユーザー呼び出し型スキルへの引き継ぎは、ユーザーが実行できるようにスキル名を示す場合に限ります（/write-handoff、/cut-release）。REQUIRED SUB-SKILL: use \x` はモデル呼び出し可能な対象にのみ使います。disable-model-invocation` スキルを呼び出すようエージェントに指示するのは行き止まりの引き継ぎであり、文体上の細かな問題ではなく、実際のバグです。
• 説明文の対象読者は 2 種類あり、上記のルールはすべてモデル向けの説明文についてのものです。 モデル呼び出し可能な説明文はルーティングに使われるため、キーワードの網羅性、症状を表す言葉、成果を表す名詞が必要です。disable-model-invocation の説明文はルーティングには使われません。エージェントはそれを目にせず、ユーザーは名前を入力してスキルを実行します。そのため、成果物を示す簡潔な、人間向けの一行として記述してください。ユーザー呼び出し型の説明文にキーワードを詰め込んでも、誰も読まないテキストになるだけです。「検出は引き続きユーザーが入力する言葉に依存する」というのは誤りです。ユーザーが入力するのは 名前 です。

用語

この用語を使ってスキルを書き、スキルが用語に沿っているか確認します。

• 先導語 — モデルが事前学習ですでに身につけている、簡潔な概念（「seam」「tracer bullet」「red」など）で、わずかなトークンで行動の一領域全体を方向づけます。トークンとして繰り返されることで、スキル内に分散した定義が蓄積されます。言い換えを3文重ねても、このような単語1つにまとまることがよくあります。造語には事前の知識が結びついていないため、まずは事前学習で身につけた単語を選びます。
• 完了条件 — 各ステップは、エージェントが確認できる条件で終わります（「テストスイートがすべて成功し、出力に問題がない」であり、「テストの結果は良さそう」ではありません）。早すぎる完了を防ぐためのものです。条件が曖昧だと、注意が作業ではなく「完了すること」へそれてしまいます。
• 無操作テスト — この行は、スキルがない場合と比べて行動を変えるでしょうか？ある行が正しく、関連性もあっても、何も変えないことがあります（「注意してください」など）。既定の動作が何かについて意見が分かれたら、議論ではなくシナリオを実行して決着をつけます。不合格の文は削って整えるのではなく、丸ごと削除します。
• 重複 — 1つの意味に2つ目の置き場所を与えることです。これは先導語の意図的な逆です。先導語は注意を集中させるために トークン を繰り返しますが、重複は 意味 を繰り返すため、行動を変更するには複数箇所を編集する必要が生じ、言い直されたルールが本来の位置づけ以上に重く見えてしまいます。無操作の見直しでは検出できません。各コピーは有効で、それぞれ単独でテストに合格するからです。そのため、重複は別途確認します。各ルールの置き場所を1つ決め、それ以外の記述はすべて削除するか、その置き場所への参照に置き換えます。規定のゲート形式は例外です。## Red Flags の箇条書きや合理化の表の行でルールを繰り返すのは意図的なもので、失敗の表が求める反例として機能します。これはルールの症状であり、2つ目の置き場所ではありません。両方が通常の文章である場合に限り、言い直しを重複とみなします。
• 否定の罠 — 禁止事項を述べると、禁止対象が文脈に持ち込まれ、半ば指示のように読めてしまいます。肯定形で促し（「1行コメントを書く」など）、禁止するパターンに言及しないようにします。唯一の例外はプレッシャーゲート型のスキルです。この場合は、厳格な禁止事項と明示的な反例の組み合わせがまさに適切な手法です。上記の失敗の表を参照してください。
• 情報階層 — スキル内の手順、次にスキル内の参考情報、最後にコンテキストポインターの先にある開示済み参考情報の順です。すべての実行で必要な情報は本文に含め、一部の分岐でしか使わない情報はポインターの先に置きます。資料が読み込まれるかどうかを決めるのは、ポインターの 参照先 ではなく 文言 です。必読ファイルを曖昧なポインターの先に置くと、読み込みのばらつきにつながります。本文に含める前に、ポインターを明確にしてください。参考ファイルは SKILL.md から 1階層以内 に保ちます（別のファイルを介さないと到達できないファイルは、読まれずに流し読みされます）。約100行を超える参考ファイルには、先頭に目次を付けます。
• トークン予算 — セッションに注入されるスキルは最小限に保ちます。すべてのトークンが毎ターンのコストになるためです。読み込みレベルは3段階あり、それぞれで予算が決まります。メタデータ（名前と説明、約100トークン）は、すべてのセッションのすべてのターンでコストになります。本文は、スキルが発動した後のすべてのターンでコストになります。参考ファイルは、ポインターをたどるまでコストになりません。規律を重視するスキルでは、本文を約500語以下に抑えます（表とコードブロックは除く）。SKILL.md の本文は 200行 以下を目指し、上限は 300行 とします。scripts/lint-skill-length.py でこの上限を確認し、予算は減る一方に保ちます。200行を超えたら、まず詳細をポインターの先に分割するか、無操作テストに不合格の記述を削除し、本文に置く必要がある内容のためだけに余裕を残します。確認されない上限はただの希望です。以前、225行削って上限を設けなかったファイルは、数週間後には再び300行に達していました。すべての行が有効でも、長さ自体が失敗要因になります。

そもそも書かない場合

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

分割する場合

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

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

それ以外はすべて、コンテキストの負荷かユーザーの記憶を代償にして、細かくすること自体が目的になっています。

例

平凡な例をたくさん並べるより、優れた実例を1つ示すほうが効果的です。最も関連性の高い単一の言語で、実際の状況に基づいた、完全で実行可能な例を用意し、WHY に関するコメントを付けます。5つの言語に移植したり、空欄を埋めるだけのテンプレートにしたりしないでください。

相互参照

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

もっともらしい言い訳

考え	実際のところ
「スキルが明らかに分かりやすい」	作者にとって分かりやすいかどうかは、決して評価に値する視点ではありません。実行してみてください
「ほんの小さな編集だ」	コードと同じように、編集でスキルも劣化します。まず旧バージョンを基準に比較してください
「ドキュメントのテストはやりすぎだ」	テストしていないスキルは、本番環境で失敗します。失敗のたびにセッション全体を無駄にします
「読み返せば、ほぼテストしたのと同じだ」	読み返しで分かるのは流暢さであり、振る舞いではありません。何もしないテストへの答えが得られるのは、実行したときだけです
「問題が起きたら修正すればいい」	問題は、エージェントがスキルを黙って無視する形で起こります。失敗に気づくことはありません
「複数のスキルをまとめて作業するほうが効率的だ」	テストしていないスキルをまとめるのは、テストしていないコードをまとめるのと同じです

デプロイチェックリスト

各項目について TODO を作成します。

RED

• pressure-testing.md に従って、プレッシャーのあるシナリオを作成済み（ゲートスキルでは、組み合わせたプレッシャーが3つ以上）
• pressure-testing.md に従ってシナリオをサニタイズ済み：エージェントが見るパスにテスト用語がなく、テスト対象の文章やそのキーワードもプロンプトに含まれていない
• モデルの一覧を明記済み。このスキルを提供する各モデルでベースラインを実行済み。すべてのトランスクリプトにモデル名を明記済み
• スキルなし（または旧バージョン）でベースラインを実行済み。失敗ともっともらしい言い訳を逐語的に記録済み
• ベースラインが実際に失敗したことを確認済み。そうでなければ中止し、何も書かない GREEN
• 失敗を分類し、分類に合った形式にします（禁止事項セット／レシピ／REQUIRED スロット／観測可能な条件付きルール）
• 説明は「トリガー＋結果を表す名詞」とし、ワークフローの手順は含めません。名前は動詞から始め、ユーザーが入力する文字列どおりのキーワードを含めます
• 説明のトリガーをテストします：発動すべきクエリと発動すべきでないクエリを実行し、両方向を確認します（pressure-testing.md に従います）
• 記録された失敗に対処する最小限のテキストにし、実例は最大1つにします
• 対策には、一般的な結果ではなく、ベースラインで記録された内容（数値、パス、ニアミス）を反映します
• ロスター内のすべてのモデルでスキルを有効にして再実行し、最も性能の低いモデルも準拠することを確認します
• エージェント自身の報告ではなく、成果物とトランスクリプトに基づいて評価します。引用を、ルールが機能した証拠とみなしていないことを確認します

REFACTOR

• 新たな合理化を明示的に打ち消し、合理化の表と危険信号のリストを作成します（ゲートスキル）
• 挙動を左右する文言を小規模にテストします：スキルなしの対照、サンプルごとの新しいコンテキスト、5回以上の反復、フラグが付いたすべてのトランスクリプトを手動で確認します
• メタテストを実施します：テスト対象のエージェントが、テキストは明確だったと確認し、準拠を容易にする要素は何も挙げないことを確認します
• 新たな合理化が現れなくなるまで再テストします

Ship

• ノーオップ確認：すべての文がノーオップテストに合格するか、文全体を削除します
• 重複確認（別の工程で実施します。ノーオップ確認では重複を検出できません）：各ルールの記載場所を1か所に定め、他の箇所の繰り返しは削除するか参照に置き換えます
• すべての disable-model-invocation の説明を、人間向けの簡潔な1行にします。トリガーキーワードや症状を表す語は含めません
• 本文をトークン予算内に収めます（300行以下、lint-skill-length.py が合格すること。200行を超える場合は、本文にその分の余裕が必要な理由を記載します）。適切な説明付きの参照の背後に資料を置き、参照は1階層までとします。100行を超える参照には目次を付けます
• 相互参照は REQUIRED SUB-SKILL の本文として記載し、補助ファイルは相対名で参照します
• すべての引き継ぎで呼び出すのはモデルから呼び出し可能なスキルに限ります。disable-model-invocation の対象は、呼び出すのではなく、ユーザーが実行するものとして明記します
• 構造とルーティングを確認します（エージェントが実行）：フロントマターが有効（name と description を含むこと。ユーザーが呼び出すスキルには disable-model-invocation: true を設定すること）、名前が動詞から始まること、本文が行数制限内であることを確認します。また、説明のトリガーを手動でテストし、pressure-testing.md に従って発動すべきクエリと発動すべきでないクエリを実行し、どちらも意図どおりにルーティングされることを確認します
• version: を更新します。挙動を変えない文言の修正はパッチ、新しいルールやスロットの追加はマイナー、既存の使い方に支障が出る場合はメジャーとします。この編集の RED/GREEN の証拠をスキルの TESTS.md に記録し、確立した実行可能なアサーションを eval.json に記録します（scripts/lint-skill-evals.py は形式を検証し、scripts/lint-skill-frontmatter.py はバージョンの欠落や形式不正をエラーにします）

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

複数のスキルを同時に編集することは別の問題であり、その答えは作業対象を分離することです。 上記のルールが対象としているのは、テストサイクルを実行していないスキルをリリースすることです。並列作業を禁じるものではありません。並列化で問題になるのは共有状態です。このリポジトリで22ファイルを対象に長さを確認した際には、各編集が個別に正しくテストされていたにもかかわらず、1日でその負担を3回負いました。2人目の作業者に依頼する前に、両者が何を書き込むのかを明確にしてください。

• 共有台帳の書き込み担当は一人にします。 あるパスでリポジトリの長さの上限を再計算し、隣の作業者がまだ編集中だった3つのファイルの項目を、その瞬間にディスクにあった内容でリセットしてしまいました。作業者は項目のクリア準備ができたことを報告し、レビュー担当者がバッチ処理の後に一度だけクリアします。
• 未コミットの作業を根拠に、残すべき場所を正当化してはいけません。 あるパスでは、隣の作業者が数分前に作成した未コミットの兄弟ファイルを挙げて、削除を正当化してしまいました。場所を確認するには、作業ツリーではなくgit show HEAD:<path>を使います。
• 作業者から報告があるまで、その作業者のファイルを読んではいけません。 編集途中のディレクトリは、誰も選んでいない状態です。そのようにして導き出された2つの結論は、同じ日にどちらも誤りだと判明しました。そのうち1つは、発生したことのない失敗を強制するリンターを出荷してしまいましたが、発覚して削除されました。