Webサイトの品質を見るAIエージェントのスキル集を作る

## リポジトリを、Webの品質の項目ごとのスキルに分ける リポジトリを、一つの巨大な指示ファイルではなく、自己完結したエージェント機能の集合として扱う。広範な監査と、パフォーマンス、アクセシビリティ、発見可能性、全般的な品質、ユーザー体験の指標に特化したスキルを分け、エージェントがタスクに必要な機能だけを読み込めるようにする。 リポジトリ全体の文書、コントリビューション規則、ライセンス、エージェント向け指針はルートに置く。各スキルのディレクトリは、主要な指示ファイル、自動化スクリプト、詳細なリファレンスを管理する。ユーザー向け指針、実行可能なヘルパー、ソース資料を無関係なディレクトリに隠さない。 スキルを変更する前に、起動契約、管理対象ファイル、依存関係、検証経路、ほかのスキルとの関係を特定する。 ## フォルダとファイルの名前、SKILL.mdの頭の情報を決める 各スキルに、有効なYAMLフロントマターを持つ`SKILL.md`を用意し、次の情報を含める。 - kebab-caseの`name` - スキルを使う場面を示し、現実的な起動フレーズを含む一文の`description` - 必要な場合はライセンスのメタデータ - リポジトリで管理する場合は、安定した作成者とバージョンのメタデータ 厳密な命名規則を一貫して使用する。 - スキルのディレクトリ名にはkebab-caseを使う。 - 主要な指示ファイルの名前は正確に`SKILL.md`とする。 - スクリプトのファイル名にはkebab-caseと適切な実行用拡張子を使う。 - リファレンスのファイル名には、リポジトリで定めた大文字表記規則を使う。 パッケージを自己完結させ、スキルに記載したすべてのパスが、対応するリポジトリ構成内で解決できることを確認する。 ## SKILL.mdは500行未満にし、詳しい中身はリファレンスのファイルへ移す 主要なスキルは500行未満に保つ。起動条件、中核ワークフロー、重要な制約、ナビゲーションは`SKILL.md`に置き、詳しい説明、大きな例、専門的な資料はリファレンスへ移す。 具体的で実行可能な指針を書く。各指針には、短いタイトル、直接的な指示、適用に必要な値やしきい値を含める。何を調べ、どの判断を行い、どの証拠で完了を確認するかを説明する指示を優先する。 決定論的または反復的な作業の出力が推論コンテキストを圧迫する場合は、スクリプトを使う。同じ手順を主要なスキルと複数のリファレンスへ重複して記載しない。 ## 直す前と後のコードと、良い・悪いの目安の表を見せる 指針が実行可能な動作を定める場合は、問題のあるパターンと修正後のパターンを示す。例は単独で理解できる程度に小さく保ち、実際に機能することを検証する。 たとえば、画像の安定性に関する指針では、指定が足りない画像と、寸法および有用な読み込みメタデータを宣言した画像を対比する。 問題例は、`src="hero.jpg"`だけを持つ画像要素。改善例は、同じ要素に`width="1200"`、`height="600"`、`alt="Hero image"`、`loading="lazy"`を指定したもの。 比較可能な品質しきい値は、良好、中間、不良の範囲を明示した表で示す。読者が上限や下限を含むか推測しなくて済むように、単位と境界演算子を記載する。 ## エラーで止まり、結果をJSONで返すシェルスクリプトを書く シェルのヘルパーは、速やかに失敗し、機械可読で、安全に後片付けできなければならない。 - shebangで使用するシェルを宣言する。 - `set -e`などで、エラー時に即座に停止する動作を有効にする。 - 進捗と状態のメッセージを標準エラーへ送る。 - JSONなどの機械可読な結果を標準出力へ送る。 - 一時ファイルを安全に作成し、後片付け用のtrapを登録する。 - 自己完結させるか、すべての外部依存関係と前提条件を文書化する。 人間向けの診断情報を機械可読の出力ストリームへ混ぜない。ヘルパーを再利用可能な自動化として扱う前に、成功、失敗、不正な入力、後片付けの各動作を試す。 ## リファレンスは1つの話題にしぼり、スキルからリンクする 各リファレンスは一つの主題に絞り、実用的な例と正本へのリンクを含める。エージェントが無関係なコンテキストを取り込まずに個別に読み込めるよう、可能な場合は各リファレンスを200行未満に保つ。 すべてのリファレンスを主要なスキルまたは保守されている索引からリンクする。古くなったリンクや重複した指針を取り除き、変更される事実は最も近い正本で管理する。 リファレンスは深い情報を提供するために使い、情報の投棄場所にしない。各リファレンスは、エージェントが明確な判断を下すか実行する際に役立つものにする。 ## スキルを出す前に、頭の情報・例・リンク・スクリプトを確かめる スキルを提出または公開する前に、次を行う。 1. YAMLフロントマターを解析して検証する。 2. descriptionに実用的な起動フレーズが含まれることを確認する。 3. すべての実行可能な例を動かすか、別の方法で検証する。 4. 参照されるすべてのファイルが存在し、すべての内部リンクが解決できることを確認する。 5. 文書化されたインターフェースを通じてスクリプトを実行し、出力チャンネルの動作を検証する。 6. 適用されるエージェントスキル仕様に照らしてパッケージを検証する。 構文検査の成功は必要だが、それだけでは不十分とみなす。起動用の説明、例、リファレンス、スクリプトは、スキルが約束する動作と一致しなければならない。 ## 問題を重大から低まで順位付けし、特定のフレームワークに寄せない 検出事項の優先度を一貫して決める。 1. **重大:** セキュリティ脆弱性または機能の完全な停止。 2. **高:** 深刻なパフォーマンス障害または重大なアクセシビリティ上の障壁。 3. **中:** パフォーマンス、発見可能性、検索品質を有意に改善できる機会。 4. **低:** コードスタイルまたは小規模な最適化の機会。 Web向け指針を特定のフレームワークに依存させない。標準のHTML、CSS、JavaScriptを先に示し、フレームワーク固有の注記は別の節に置く。タスクにフレームワーク依存が不可欠でない限り、標準のプラットフォームAPIを優先する。 スタイル上の改善に労力を使う前に、影響が最も大きい正確性の問題とアクセス上の障壁をレビューする。 ## スキルを呼ぶ言葉を壊さずに、スキルを更新する スキルのdescriptionを更新する時は後方互換性を保ち、従来の起動フレーズが機能し続けるようにする。実装と同時にバージョンのメタデータを更新し、破壊的変更はリポジトリで定められた変更記録またはコミットの説明へ記載する。 構造を変える時は、主要なスキル、影響を受けるリファレンス、スクリプト、例、リンクをまとめて更新する。最終差分をレビューし、意図しない範囲拡大、古くなった生成物、指示の重複がないか確認する。 動作を変更するたびに、対象を絞った検証チェックリストを再実行する。起動経路、例、参照される成果物が未検証の間は、更新したスキルの準備が整ったと報告しない。