どのAIでも使えるスキル集を作り、手入れを続ける

## スキルの細かい中身を、使う時だけ読み込むようにフォルダを分ける 各スキルに、主指示ファイル、必須metadata、任意のreferenceディレクトリとscriptディレクトリを備えた専用ディレクトリを割り当てる。完全な例、研究資料、正規template、コレクション全体の文書は明確に分けた場所へ置く。すべてのスキル本文を読み込まなくてもユーザーやエージェントがコレクションを見つけられるよう、ルートにスキルマップを維持する。 名前とdescriptionを起動時の索引として扱う。詳細な指示、reference、scriptは、スキルが発動した時だけ読み込む。この構造により、必要に応じて詳細資料を利用可能なまま保ちながら、現在のタスクへ注意を集中できる。 ## スキルの本体ファイルを短くし、どのツールでも使える書き方にする スキルの主指示ファイルは500行未満に保ち、詳細資料はreferenceへ移す。nameと三人称のdescriptionを含むYAML metadataを必須とし、ディレクトリ名には小文字とハイフンを使用し、各段落に十分な情報価値があるか検討する。スキルが基礎事項を明示的に教える場合を除き、対象者は上級者と想定する。 プラットフォームに依存しない指針を書く。プラットフォーム固有の制約が不可欠な場合を除いてベンダー固有のツールを抽象化し、概念説明用のpseudocodeを本番利用可能なコードとして示さず、例を移植可能にする。 ## スキルを使う時と使わない時の境目を書く 発動条件、中心概念、実践指針、例、ガイドライン、注意点、統合、referenceの各セクションを含める。すべての発動セクションには、肯定的なtriggerと、隣接する作業を適切なスキルへ振り分ける「発動しない」境界を明記しなければならない。 経験から得た注意点は、一般的な指針では見落としやすい失敗パターンを捉えるため、特に重視する。インストール構成が変わるとlinkが壊れる場合は、統合指針の中で他のスキルを安定したプレーンテキスト名によって参照する。 ## スキルを変えたら、一覧と数字の出どころを一緒に直す スキルを追加または変更する時は、コレクションの概要、配布manifest、corpus indexを同時に更新する。発見、package化、評価が同じ成果物を記述するよう、そのスキルを発動scenario、再利用可能な動作mechanism、裏付けとなるclaimへ対応付ける。 数値、benchmark、変動しうる主張、ベンダー性能に関する主張には由来を記録する。スキルが再利用可能な動作変更または証拠に依存する主張を導入するたびにmechanismとclaimのregistryを更新し、それらの関係を文章内の暗黙情報として残してはならない。 ## AIに判断させる前に、決まった自動チェックを通す 変更を受け入れる前に、metadataのparse、厳格なschemaとcorpus構造、プラットフォーム互換のインストール構成、スキル本文の健全性、発動境界、敵対的benchmarkについて、リポジトリで定義された検査を実行する。これらを任意の診断ではなく、レビューのゲートとして扱う。 構造、manifestの同期、rubricの計算、取得状態、registryの形を、最初に決定論的な方法で検証する。モデルによる判断は、それらの検査に合格した後だけ使用し、再現可能な構造上の失敗をモデルの判断で正当化してはならない。 ## 例のプロジェクトごとに、それぞれの準備とテストのコマンドを使う リポジトリにトップレベルのbuild systemがない場合、それを作り上げてはならない。各exampleまたはsubprojectが宣言するruntimeとpackage managerを特定し、それぞれ固有のsetup、build、test、lint、format、type-checkコマンドを使用する。環境と依存関係はそのsubprojectの範囲内に保つ。 反復作業中は関係する最小のコマンドを実行し、レビュー前にsubprojectで文書化された一連のゲートを完了する。1つのコマンドが成功したことを全ゲート合格の証拠とせず、compile、unit test、asynchronous test、lint、format、static type checkを区別する。 ## 研究の1回ごとを、用意されたツールで決まった段階ずつ進める すべての研究runを提供されたlifecycle toolから初期化し、state file、queue entry、thread log、source evaluationのひな型、mechanism proposal templateを一貫して作成させる。取得、評価、提案、新規性レビュー、run検証、レビュー準備完了、終了の各段階を、サポートされた遷移によって進める。run stateを手作業で編集してはならない。 有効なrunは、リポジトリ全体のゲートとは独立して検証する。提案されたmechanismを昇格できるのは、runの準備が整い、必要なreviewerが記録され、準備状況の検査に合格した後だけとする。数値、benchmark、変動しうる主張をスキルへ入れる前に、claimの由来を追加する。 ## 自動でくり返す研究では、予算が決まるまで有料のAIを呼ばない loopを手動で起動する場合もプラットフォーム固有のschedulerから起動する場合も、発見、1段階の前進、日次処理、状態報告のための決定論的なコマンドを用意する。有料モデルを呼び出さずに取得処理を利用できる状態に保ち、明示的な予算ゲートが存在するまでは、無人loopから有料モデルを呼び出してはならない。 queue、runtime log、snapshot、status report、保留review、event stream、failure、通常のrun directoryは、sourceではなく運用状態として扱う。意図して指定したseed runを除き、これらを決してcommitしてはならない。 ## 関係するスキルを、コピーを作らず1つのパッケージで配る hostがplugin sourceを個別にcacheする場合は、複数のpackageから同じsource treeを参照せず、関連するスキルのコレクションを1つのpackageとして配布する。これにより、1つの一貫したversionとmanifestの境界を保ちながら、重複cacheを防げる。 起動時には、発見に必要なmetadataだけを提示する。packageの広さが恒久的なcontext負荷にならないよう、スキル本文全体と補助resourceの読み込みは発動時まで遅らせる。 ## AIに渡す資料をしぼり、変更を送る前に人の許可を取る contextの量より質を優先する。注意資源には限りがあり、中間位置で情報が失われるため、資料を増やすと性能が下がる場合がある。sub-agentは組織上の役割を模倣するためだけでなく、範囲を限定した作業の注意資源を分離するために使う。概念説明の例には、特定言語に依存しない、または広く読めるpseudocodeなどを使用し、移植可能に保つ。 モデル判断より決定論的な証拠を先に扱い、リモート公開を人の管理下に置く。エージェントは変更を準備してすべてのローカルゲートに合格できるが、pushまたはmergeの前には人から明示的な承認を得なければならない。