正しく呼び出され、チェックに通るエージェントスキルを作ってリリースする

## スキルの説明文は「何をするか・いつ使うか」だけにし、手順を書かない 説明文は、圧縮した手順ではなくルーティング用メタデータとして扱う。エージェントは本文全体を読む前に説明文からスキルを選ぶ場合があるため、そこに処理手順を埋め込むと、詳しいワークフローが上書きされたり迂回されたりする可能性がある。 説明文には、簡潔な機能の記述に続けて、スキルの用途と使用条件を記す。有効なスキーマの上限内に収め、1,024文字の上限が適用される場合はそれを守る。順序付きの手順、実装の流れ、トラブルシューティング手順は説明文に決して含めず、方法に関する案内はすべてスキル本文に置く。 現実的なプロンプトで説明文をテストし、意図した依頼で起動し、無関係な作業では起動せず、エージェントを完全な手順へ導くことを確認する。 ## フロントマターは仕様にある項目だけにし、関連スキルへの参照を正しく保つ 近隣のリポジトリからフィールドをコピーするのではなく、有効なスキル仕様に従う。トップレベルには、`name` と `description` を含む仕様定義済みのフィールドだけを置き、`license` と `allowed-tools` はリポジトリの契約に従う場合にのみ使う。`allowed-tools` がある場合は、空白区切りのリストにしなければならない。リポジトリ固有のフィールドは `metadata` の下に置く。 名前に使える文字を英字、数字、ハイフンに限定する。説明文の長さと起動条件の表現を検証する。作成者、セマンティックバージョン、ドメイン、トリガー、役割、適用範囲、出力形式、関連スキルなどの構造化メタデータは、リポジトリで定義された列挙値と形式に従わせる。 関連スキルの各項目は、既存のスキルディレクトリへ解決できなければならない。リポジトリで承認されたライセンス値を一貫して使い、ライセンスがMITに固定されているリポジトリでは `license: MIT` と正確に記す。YAMLパーサーが受理するという理由だけで、未知の列挙値、壊れた参照、独自のトップレベルフィールドを許容してはならない。 ## メインのスキルファイルを短くし、詳しい中身を参照ファイルへ分ける メインのスキルファイルは、ルーティングと操作のコンテキストとして読み込める程度に簡潔に保つ。実用的な第1階層の目安は約80〜100行で、役割、起動条件の案内、5段階の中核ワークフロー、必須事項と禁止事項、詳細な参照資料へのルーティング表を含める。 詳しい技術情報は、通常それぞれ100〜600行となる、焦点を絞った第2階層の参照ファイルに置く。各参照資料は1つの主題を扱い、関連する型を含む完全に動作する例を示し、境界事例とアンチパターンを説明し、案内を使うべき時と使うべきでない時を明記する。 現在の作業に必要な参照資料だけを読み込む。有用な場合は関連スキルを相互リンクするが、その全内容を重複させない。コンテキスト使用量の削減を設計上の成果として扱う。適切にルーティングされた2階層構造なら、必要な手順を省かずに約50%の削減を目標にできる。 ## 例では、フレームワークに備わっている仕組みを使う フレームワーク固有の案内では、そのフレームワークで確立された仕組みを使わなければならない。フレームワークがグローバルなエラー処理、ミドルウェア、依存性注入、ライフサイクルフック、その他の組み込み抽象化を備えている場合、例ではそれを手動で作り直さず、その仕組みを使う。 リポジトリ全体の見た目を統一するために、無関係なフレームワークへ単一の汎用アーキテクチャを強制してはならない。エラー処理、構成、テスト、統合については、フレームワークの規約を優先する。 参照資料の例は完全かつ実行可能に保ち、言語が型をサポートする場合は型も含める。対象範囲のフレームワークバージョンに照らして例を確認し、組み込み動作を重複実装するパターンや、フレームワーク固有の制約を隠すパターンを退ける。 ## すべてのスキルファイルの最後に、文書へのリンクを1つ置く すべてのスキルファイルは、最終行に正規の文書バックリンクをちょうど1つ置いて終えなければならない。厳密なレンダラーでも実際のハイパーリンクになるよう、裸のURLではなく、ラベルを `Documentation` としたMarkdownリンク構文と正規URLを使う。 正規パスは、`metadata.domain` やスキルディレクトリ名などの安定したメタデータから導出する。メタデータがない場合は、文書で定められた代替ドメインを適用する。スキルの追加や名前変更を行う時は、ディレクトリ、ドメイン、バックリンクをまとめて更新する。そうしないと、公開リンクが存在しないページを返す可能性がある。 複数の公開面を明示的に考慮する。未加工ファイルの集約機能では発見のためにバックリンクが必要な一方、文書ビルドでは生成ページ、ミラー、言語モデル用インデックスから同じ自己リンクを対象から外す場合がある。同期工程で両方の挙動を維持し、レンダリング後のリンク先をテストする。 ## スキルを作る・変える時は、重なりを確かめ、関連する参照も直す 新しいスキルでは、次を行う。 1. 既存スキルに重複する責務がないか確認する。 2. 機能と起動条件のメタデータを備えたメインスキルを作成し、処理手順は本文に置く。 3. 詳細な内容のために、焦点を絞った参照資料を追加する。 4. 主題から参照資料へのルーティング表を追加する。 5. 最終行に正規の文書バックリンクを1つだけ追記する。 6. 起動するプロンプトと起動しないプロンプトをテストする。 7. 分類体系が変わった場合は、スキルガイドとドメイン索引を更新する。 スキルを変更する前に、現在の本文全体と変更の影響を受ける参照資料を読む。機能と起動条件から成る説明文の形、および段階的開示の構造を維持する。名前、適用範囲、トリガー、依存関係が変わる場合は、ルーティング表、関連スキルへの参照、文書索引、起動テストを更新する。 ## 1つのバージョンファイルを正本にして、件数と変更履歴をそろえる 1つのバージョンマニフェストを、リリースバージョンと、スキル、ワークフロー、参照ファイルなどの計算済み件数の正本として使う。リポジトリの更新ツールを実行し、ファイルシステムから件数を再計算して生成文書を同期する。CIとレビュー担当者が書き込みなしでずれを検出できるよう、チェックモードとドライランモードに対応させる。 安定した Added、Changed、Fixed の構造で変更履歴の先頭に新しいリリースを追加し、バージョン比較リンクを維持する。集約文書を再生成する前に、新規または変更された内容に合わせてガイド、判断ツリー、コマンド表、相互参照を更新する。 件数を埋め込んだソーシャル用素材は、その件数が変わった場合にのみ再生成する。バージョンだけのパッチでは、新しい素材は不要である。生成された差分を確認し、自動化によって無関係な変更が隠されないようにする。 ## リリース前に、スキルとMarkdownのチェックツールを動かす リリース前にスキル整合性バリデーターを実行する。YAMLの解析、必須フィールド、名前の形式、説明文の長さと必須の `Use when` 起動条件句、参照ディレクトリの存在、参照資料の構造、件数の整合性を検査しなければならない。1つのスキルまたは1つの検証系統に限定した検査と、CI向けの機械可読な結果を用意する。 Markdownバリデーターは別に実行する。表を壊すHTMLコメント、閉じられていないコードフェンス、欠けている表の区切り行、列数の不一致を検査する。対象を絞った調査の後に、リポジトリ全体を検証する。 終了コード0を成功、終了コード1を検証失敗として扱い、警告は明示的に確認する。狭い範囲の検査が通ったというだけで、未解決の検証エラーがあるリリースを決して公開してはならない。 ## 使ったコマンドと結果を残してから、リリースできると伝える 同期と検証の後、意図的に残された変更履歴を除外し、古いバージョン参照を検索する。説明文、起動テスト、ルーティング表、関連スキルへの参照、正規バックリンク、生成された件数、条件付き素材がリリースと一致することを手動で確認する。 動作パターンや工程上の規律を他の成果物から取り入れた場合は、第三者への帰属表示、ライセンス通知、調査資料への参照を維持する。整理の過程で出典情報を失ってはならない。 更新コマンドと検証コマンド、その結果、確認済みの警告、意図的に省略した条件付き工程を正確に記録する。必要なバリデーターがすべて通り、最終差分に説明のつかない変更がないことを確認してから、リリース準備完了と報告する。