authoring-verifiable-skills

検証可能なスキルの作成

基本原則。 起動しないスキルは何もしません。また、誰も失敗するところを見たことがないスキルは、何も証明しません。既存のスキルが十分に機能していないという証拠に基づいて変更する作業は、optimising-skills に属します。

• この2つの失敗はどちらも表面化しません。 どちらも、スキルが機能している場合とまったく同じように見えます。
• 重視すべきなのは、起動の接点 と ゲート です。 その後の作業はすべて、すでに呼び出されているスキルを改善するものです。
• あなたは何かの作業の途中でこれを開きました。 これはその作業を進める方法であり、作業に取って代わるものではありません。始める前に何をしていたのかを明確にし、終わったらその作業に戻ってください。

目の前のシグナルに対応するルールを読む

この表はゲートであり、チェックリストではありません。 これから書く、または修正するものに左列を照らし合わせてください。

• 各行にルールは1つです。 該当する行から始めてください。
• シグナルがない軸は、該当なしとして報告し、それを発動させるシグナルを明記します。
• 作業が2つの行に該当する場合は、両方を読んでください。 読むことは簡単なほうです。
• 「すべて読む」を既定とするインデックスは、余計な手順が増えた目次にすぎません。
• すべての行を読んでから、該当するものに対処してください。取り消しにくいものから始めます。 行を読むのにコストはかかりません。読み飛ばした行に、網羅できなかった内容があります。

次のものが見られる場合…	読むもの
新しいスキル、または一度も起動しない、あらゆる場面で起動する、もしくは近隣のスキルに負けるスキル	rules/activation-surface.md
エージェントから見えるものではなく概念を振り分けるインデックス、またはゲートがまったくないスキル	rules/gate-not-checklist.md
2つの判断を含むルール、必須ブロックが欠けているルール、または別のルールを言い換えているルール	rules/one-rule-one-decision.md
長い説明文、実際には箇条書きである段落、またはざっと読めないファイル	rules/readable-in-one-pass.md
失敗するところを一度も見たことがないチェック一式、またはシナリオのないスキル	rules/prove-it-with-checks.md
判定ではなく数値を返すツール、またはレポートや判断に加えようとしている数値	rules/prove-a-measure.md
作成者が考えた順序で並んだファイル、またはすべての行に MUST と記されたファイル	rules/order-and-strength.md
思い出されない名前、またはインストール済みのスキルと名前が重複するもの	rules/name-and-scope.md
作業に複数の段階があるのに、現在どの段階かを示す方法がないスキル、または読者が今すぐ行うはずのことに対して not yet とするルール	rules/states-carry-licenses.md
説明文に書かれたパス、URL、ベンダー、またはパッケージマネージャー	rules/portable-by-default.md

判別の基準。

• 起動と名前の違い。 スキルが呼び出されるかどうかは、起動が担います。呼び出された後に他のスキルと区別できるかどうかは、名前が担います。
• ゲートと1ルールの違い。 どのファイルを開くかはゲートが担います。そのファイルに何を書くかは1ルールの原則が担います。
• 読みやすさと順序の違い。 1行の形は読みやすさが担います。どの行を先にするかは順序が担います。

基本方針。

• まず起動の接点を修正してください。 一度も起動しないスキルは何もしません。その失敗は表面化しません。
• すでに知っている必要がある概念ではなく、作業の中でエージェントから見えるものに基づいて振り分けてください。
• そのチェックが本来の理由で失敗するところを実際に見るまでは、良いチェックだと判断しないでください。

すべてのスキルを構成するもの

• SKILL.md には、フロントマター、中核となる原則、ゲートを記載します。
• rules/<name>.md には、5つのブロックに分けて、1つの判断を記載します。
  • Decision: 何を選ぶかを1文で記載します。
  • Use when: 条件を、目に見える事柄として記載します。
  • Do: 選択する内容を記載します。
  • Avoid: 防ぐ失敗を記載します。
  • Verify: 否定的な結果が返る可能性のあるチェックを記載します。
• evals/*.scenarios.mjs には、肯定・否定両方の有効化シナリオを記載します。

許可される形式は3種類で、チェッカーはすべてに対応しています。

• ルーティング形式。 エントリーファイルとrules/で構成し、ゲートの各行にルールを1つずつ対応させます。デフォルトの形式です。
• フラット形式。 エントリーファイルのみで構成します。単一のトピックを扱い、ルーティングが不要なスキル向けです。
• 複数トピック形式。 トピックのディレクトリへルーティングするエントリーを設け、各ディレクトリ内でもルーティングを行います。独立したINDEX.mdを設ける手間に見合うのは、この場合だけです。

すべて強制される上限です。

• ルール。 proseは450語未満、読み取るテキストは600語未満、proseは24〜70行です。
• エントリー。 proseは160行未満で、ゲートの行数はルールの数以上です。
• 説明。 500文字前後、上限は700文字です。

信じる前に検証する

node tools/verify-skill.mjs skills/<name>      # structural invariants
node tools/mutate-skill.mjs skills/<name>      # each check fires for its own reason
node tools/readability.mjs --skill skills/<name>
node tools/check-yaml-parity.mjs               # frontmatter against a real YAML parser

• 壊れたスキルが正しい理由で失敗することを確認するまでは、テストスイートがすべて成功しても証明にはなりません。
• シナリオテストスイートがない場合は、合格ではなく、必ずUNPROVENとして報告します。
• 数値を信じる前に、出力を読みましょう。 書き換えを評価するための指標は、その書き換えによって攻略されます。

この場合も省略しないでください

• スキルが小規模な場合。 説明に不備がある小規模なスキルは、大規模なスキルと同様に見つけられません。
• 名前を変更するだけの場合。 名前は有効化の対象範囲の半分を占めます。
• 表現に問題がない場合。 失敗の原因は表現ではなく、構造とルーティングでした。
• 既存のスキルをコピーする場合。 それによって、不具合が別の場所にも持ち込まれます。

ルーティング

• 上の表でルールを選びます。 表を最後まで読み、どのルールを開いたかを1行で述べてください。
• ユーザーからの直接の指示は、ここにある内容より優先されます。
• タスクにスキルが必要かどうかは、ここでは判断しません。 それが決まった後にスキルを書くことが、このスキルの役割です。
• 既存のスキルの性能が不十分な場合は、optimising-skillsが担当します。 読み取り時に構造を修正するのはこちらで行い、動作の変更はあちらで、予測を先に書いたうえで実験として行います。