Web AwesomeにAgent Skillsサポートを追加

2026年02月03日 02:14 JST shoelace-style/webawesome

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

Web Awesome 4.3.0で、AI開発支援ツール向けのAgent Skills仕様に準拠したドキュメントセットが追加されました。これにより、Claude CodeやCursorなどのAI支援ツールが、Web Awesomeのコンポーネントとその使用方法をより正確に理解できるようになります。

背景

これまでWeb Awesomeは、AI支援ツール向けに単一ファイルの llms.txt を提供していました。しかし、単一ファイル形式では、AIツールが必要な情報だけを効率的に取得することが困難でした。すべてのコンテキストを一度に読み込む必要があるため、複雑なタスクでのコンテキスト管理が非効率的でした。

Agent Skills仕様は、複数のMarkdownファイルに分割された構造化ドキュメントを通じて、AIツールが必要な情報を段階的に取得できる仕組みを提供します。#1998 は、この仕様に準拠したドキュメントセットの生成機能を実装しています。

技術的な変更

Agent Skillの生成は、Eleventyのビルド後に実行される新しいスクリプト scripts/agent-skill.js によって行われます。このスクリプトは、以下の処理を実行します。

ドキュメントの生成プロセス

EleventyがレンダリングしたHTMLファイルから情報を抽出し、Markdownに変換する方式が採用されています。これは、Web AwesomeのドキュメントソースがNunjucksテンプレートを多用しているためです。

function createTurndownService(baseUrl) {
  const turndown = new TurndownService({
    headingStyle: 'atx',
    codeBlockStyle: 'fenced',
    bulletListMarker: '-',
  });

  // Custom rule for code examples - extract clean code from syntax-highlighted blocks
  turndown.addRule('codeExample', {
    filter: node => {
      return node.nodeName === 'DIV' && node.classList?.contains('code-example');
    },
    replacement: (_content, node) => {
      const sourceDiv = node.querySelector('.code-example-source');
      const codeElement = sourceDiv?.querySelector('pre code');
      const code = codeElement?.textContent.trim();
      // ...
      return `\n\n\`\`\`${lang}\n${code}\n\`\`\`\n\n`;
    },
  });
}

turndownライブラリを使用してHTMLからMarkdownへの変換を行い、シンタックスハイライト済みのコードブロックから元のコードを抽出するカスタムルールを実装しています。

生成されるファイル構造

Agent Skillは以下のディレクトリ構造で生成されます：

webawesome/
├── SKILL.md              # メインスキルファイル
└── references/
    ├── components/       # 各コンポーネントの個別ドキュメント
    ├── frameworks/       # React、Vue、Angular、Svelteのガイド
    ├── utilities/        # レイアウトとスタイリングユーティリティ
    ├── installation.md   # インストールガイド
    ├── usage.md          # 使用パターン
    ├── form-controls.md  # フォーム統合
    ├── themes.md         # テーマとカラーパレット
    └── ...

このファイル群は dist/skills/webawesome/ と dist-cdn/skills/webawesome/ に出力され、npmインストール時は node_modules/@awesome.me/webawesome/dist/skills/webawesome/ からアクセスできます。

ビルドプロセスへの統合

scripts/build.js に、Agent Skill生成ステップが追加されました：

// Generate llms.txt (needs CEM, runs before docs)
spinner.start('Generating llms.txt');
await generateLlmsTxtFile();
spinner.succeed();

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

llms.txtの生成は、Custom Elements Manifest（CEM）が必要なためドキュメント生成前に実行されます。一方、Agent Skillの生成は、EleventyがHTMLを生成した後に実行される必要があります。この実行順序の依存関係が、コメントで明示的に記述されています。

llms.txt生成の再実装

llms.txt生成がCEMプラグインから独立した関数に変更されました：

変更前：

import { llmsTxtPlugin } from './scripts/llms.js';

// ...
llmsTxtPlugin({
  outdir,
  docsDir: path.join(__dirname, 'docs'),
  baseUrl: 'https://webawesome.com',
}),

変更後：

export async function generateLlmsTxtFile(options = {}) {
  const {
    outdir = path.resolve(__dirname, '../dist-cdn'),
    copyTo = [path.resolve(__dirname, '../dist')],
    docsDir = path.resolve(__dirname, '../docs'),
    cemPath = path.resolve(__dirname, '../dist-cdn/custom-elements.json'),
    baseUrl = 'https://webawesome.com',
  } = options;

  const customElementsManifest = JSON.parse(fs.readFileSync(cemPath, 'utf-8'));
  // ...
}

この変更により、llms.txt生成とAgent Skills生成が同じビルドステージで実行され、一貫性が保たれます。

設計判断

PRの説明では、静的コンテンツの重複を最小限に抑えつつ、リファレンスファイルを相対的に小さく保つこと が目標として挙げられています。

Eleventyのビルド出力から変換する方式を選択した理由は、ドキュメントソースがNunjucksテンプレートを多用しており、Markdownソースから直接情報を抽出することが困難だったためです。この方式により、レンダリング済みのHTMLから正確な情報を取得できます。

生成されたファイルは「LLM向けに最適化されており、人間向けではない」と明記されています。これは、AIツールが効率的に情報を取得できるよう、構造と内容が調整されていることを意味します。

また、llms.txtとAgent Skillsの比較表が新たに追加され、ユーザーが適切な方式を選択できるようになりました：

Feature	llms.txt	Agent Skill
Format	Single text file	Directory with multiple markdown files
Best for	Quick context, simple queries	Deep integration, complex tasks
Context usage	Loads everything at once	Progressive disclosure (loads as needed)
Supported by	Most AI tools	Tools supporting agentskills.io spec

この比較により、Agent Skillsをサポートするツールでは新しい方式を、そうでないツールでは既存のllms.txtを使用するという選択が可能になっています。

まとめ

本PRは、Web AwesomeにAgent Skills仕様準拠のドキュメント生成機能を追加し、AI開発支援ツールがより効率的にコンポーネント情報を取得できるようにしました。Eleventyのビルド出力から変換する方式により、Nunjucksテンプレートベースのドキュメントソースに対応しつつ、段階的な情報開示によるコンテキスト効率の向上を実現しています。この機能は実験的なものとして導入され、フィードバックに基づいて今後調整される予定です。