Agent-Orientation Note を llms.txt に追加

Web Awesome が生成する llms.txt に、AI エージェントやコーディング アシスタント向けに Agent Skills の概要とインストール手順を記載した段落が加わります。これにより、LLM がパッケージの提供スキルを把握した上で UI を構築できるようになります。

背景

Web Awesome はビルド時に llms.txt を自動生成し、LLM 用の標準化されたコンポーネント API を提供しています。生成物は H1 → blockquote → ## Documentation / ## Components という構造で、AI が参照しやすい形に整形されています。

しかし、AI エージェントが利用できる Web Awesome Agent Skills の存在とインストール方法が文書に記載されていなかったため、エージェントがスキルを自動的に認識できませんでした。webawesome-app の議論（[#394]）でこのギャップが指摘され、llms.txt に直接案内を埋め込む方針が立ち上がりました。

この追加により、llms.txt を読むエージェントはスキル情報を取得でき、別途ドキュメントを参照する手間が省かれます。

技術的な変更

packages/webawesome/scripts/llms.js に、生成される概要ブロックの末尾に Agent Skills の紹介文が挿入されました。具体的には、フォントアイコンに関する記述の直後に 6 行のテキストが追加されています。

+For AI agents and coding assistants building with Web Awesome: two Agent Skills ship with the package. The `webawesome` skill is this component reference in progressive, on-demand form; the companion `webawesome-design` skill covers full-page layout (`<wa-page>`), theming, brand color, and visual composition. After installing `@awesome.me/webawesome`, register them with `npx skills add ./node_modules/@awesome.me/webawesome/dist/skills/webawesome`
+and `npx skills add ./node_modules/@awesome.me/webawesome/dist/skills/webawesome-design`. See ${baseUrl}/docs/ai/agent-skills for both.

この変更は コードロジック を変えるものではなく、文字列リテラルの追加のみです。生成プロセスは既存のフローを踏襲し、dist-cdn/llms.txt と dist/llms.txt の両方に同一内容が出力されます。

設計判断

生成ドキュメントにエージェント向け案内を埋め込む 手法が採用されました。別ファイルで案内を管理する代わりに、llms.txt の生成時点で情報を付加することで、ドキュメントの整合性と配布の一貫性が保たれます。

このアプローチは 単一ソース・オブ・トゥルー の原則に沿い、llms.txt が唯一の参照先になることを意図しています。スキル情報が更新された場合はこのスクリプトを修正すれば即座に全ビルドに反映され、重複管理のリスクが低減します。

結果として、AI エージェントがパッケージを利用する際の導入ハードルが下がり、同時にメンテナンスコストも抑えられました。

まとめ

llms.txt に Agent-Orientation Note を追加したことで、AI エージェントが Web Awesome の提供スキルとそのインストール手順を自動的に取得できるようになり、ドキュメント生成プロセスのシンプルさと一貫性が強化されました。