Agent Skill生成をEleventyプラグインへ移行

2026年02月06日 02:50 JST shoelace-style/webawesome

https://github.com/shoelace-style/webawesome/pull/2030

Web AwesomeのAgent Skill生成処理がEleventyのビルドフローに統合されました。これにより、ドキュメントアプリケーションが独自のEleventyプロセスを実行する際にも、Skillファイルが確実に生成されるようになります。

背景

Web Awesomeは Agent Skill と呼ばれる、AIエージェントがコンポーネントを理解するための構造化データを生成しています。従来はビルドスクリプト（build.js）内で生成処理を呼び出していましたが、ドキュメントアプリケーションが独自のEleventyプロセスを実行する際に、この生成処理が実行されない問題がありました。

EleventyはWeb Awesomeのドキュメントサイトを構築する静的サイトジェネレーターです。ドキュメントアプリケーションは開発モードで独立したEleventyプロセスを起動するため、ビルドスクリプト経由では生成処理が実行されず、Skillファイルが欠落していました。

技術的な変更

Eleventyの設定ファイル（.eleventy.js）に eleventy.after イベントハンドラを追加し、ビルド完了後にAgent Skill生成を実行するようになりました。

変更後:

import { generateAgentSkill } from '../scripts/agent-skill.js';
import { getSiteDir } from '../scripts/utils.js';

eleventyConfig.on('eleventy.after', async () => {
  const siteDir = getSiteDir();
  await generateAgentSkill({
    siteDir,
  });
});

eleventy.after イベントは、Eleventyがすべてのファイルを生成した直後に発火します。このタイミングでSkill生成を実行することで、生成されたサイトディレクトリを参照しながら処理を行えます。

一方、ビルドスクリプト（build.js）からは、Agent Skill生成の呼び出しを削除しました。

変更前:

// Generate Agent Skill (must run after Eleventy generates _site)
spinner.start('Generating Agent Skill');
await generateAgentSkill();
spinner.succeed();

変更後:

上記のコードブロックが削除され、generateAgentSkill のインポート文も削除されています。ビルドスクリプトは generateDocs() を呼び出し、その内部でEleventyが実行されるため、結果的にEleventyの eleventy.after イベントで生成処理が実行されます。

agent-skill.js では、引数の順序を調整して siteDir を copyTo の前に配置していますが、これはコードの可読性向上のための変更で、機能への影響はありません。

設計判断

生成処理をEleventyのライフサイクルに組み込む方式 が採用されました。

PR説明文では「ドキュメントアプリが独自のEleventyプロセスを実行していたため、Skill生成が欠落していた」と述べられています。ビルドスクリプト側で制御する従来の方式では、Eleventyプロセスの実行タイミングによっては生成処理が実行されないケースが発生していました。

eleventy.after イベントを利用することで、Eleventyプロセスがどのように起動されても、ビルド完了時に必ず生成処理が実行される設計になっています。これは、開発モードとプロダクションビルドの両方で一貫した動作を保証する判断といえます。

まとめ

本PRは、Agent Skill生成のタイミングをビルドスクリプトからEleventyのイベントハンドラに移行した変更です。ドキュメントアプリケーションの実行方式に依存しない生成フローを確立し、開発・本番環境での動作の一貫性を確保しています。