Agent Skillにデザイン支援と検証機構を追加
このPRは、既存の Agent Skills にデザイン支援用スキルとコンポーネント選択支援ツリー、そしてビルド時の整合性検証スクリプトを加え、AI ツールが正確かつ安全に Web Awesome を利用できるようにした点が最大の特徴です。
背景
AI コーディングアシスタントはコンポーネント API とデザインガイドラインの両方を把握できると、実装支援が格段に向上します。#2456 で導入された webawesome‑design スキルはレイアウトやトークンの指針を提供しましたが、コンポーネント選択の誤りやスキル内容のドリフトを防ぐ仕組みが不足していました。
実際にエージェントは <wa-dropdown> と <wa-select> を取り違えるなどの誤選択が頻発し、また手動で管理していた Markdown がライブラリ更新と同期しないリスクが指摘されていました。これらの課題を解消するため、設計と検証を組み込んだ拡張が本 PR で行われました。
技術的な変更
主要な追加ファイルとして scripts/verify-skills.js、scripts/agent-skill/choosing-components.md、scripts/design-skill/SKILL.md のバージョン注入ロジック、そして npm run verify:skills タスクが新たに導入されました。また、package.json の verify スクリプトに統合されたことで CI で自動的に実行されます。
verify-skills.js は 3 つのチェックを行います。① choosing-components.md に記載された <wa-*> タグが Free または Pro のコンポーネントディレクトリに実在するか、② Pro とマークされたコンポーネントが実際に Pro パッケージに属しているか、③ 相対 Markdown リンクがすべて解決できるかを検証し、失敗時は非ゼロ終了コードで CI を止めます。
choosing-components.md は ユーザー意図（例: 1 つ選択、アクション実行、フィードバック表示）に応じたコンポーネント選択表を提供し、scripts/agent-skill.js のコピー処理に組み込まれます。これによりエージェントは「意図 → コンポーネント」の決定木を参照でき、誤選択が大幅に減少します。
デザインスキル側では、injectVersion 関数が SKILL.md の frontmatter に metadata.version を自動挿入します。コピー後に実行されるため、ソース Markdown は手を加える必要がなく、リリースバージョンと常に一致します。
ドキュメント面では、CHANGELOG.md のエントリ形式が Clear & Succinct に統一され、docs/_layouts/component.njk の不要なテーブルセル削除や AI ポリシーページの文言刷新、accessibility.md の署名アイコン追加など、ユーザー体験の微調整も同時に行われました。以下は component.njk の削除前後の差分例です。
@@ -134,9 +134,6 @@
- <td class="table-default">
-
- </td>
+ <!-- 削除: 空のデフォルトセルは不要」 -->
これらの変更はすべて追加・置換であり、既存の API や設定を破壊するものはありません。
設計判断
手書き Markdown をそのままコピーする方針を取ったのは、生成ロジックに依存せずメンテナンスコストを抑えるためです。スキル全体は自動生成部分と手動部分が混在しますが、コピー対象を明示的に列挙することで将来的なドリフトを防止しています。
検証ロジックを npm run verify のフローに組み込んだことは、追加 CI 設定を増やさずに一元管理できるというトレードオフです。失敗時にビルドが止まるため、リリース前に必ず整合性が確保されます。
さらに 2 つのスキルを併用推奨する記述を AI Skills ページに追記したのは、機能の重複を防ぎつつ全体像を網羅させる狙いです。利用側は「コンポーネント」だけか「デザイン」だけか選択でき、両方インストールすれば最も包括的な支援が得られます。これにより導入ハードルは変わらず、価値だけが増大します。
まとめ
本 PR は、AI アシスタント向けに コンポーネント選択支援ツリー と ビルド時検証 を導入し、デザインスキルのバージョン同期 を自動化したことで、エージェントが正確かつ最新の情報を参照できる環境を実現しました。既存機能への影響はなく、今後のスキル拡張やリリースサイクルに対しても安全に運用できる基盤が整いました。