884js/lib-docs-generator

ライブラリドキュメント生成ガイド

概要

ライブラリのドキュメントからスキルを自動生成する。

方針:

1. llms.txtがあれば → そのまま使う（リンク先はクロールしない、llms-full.txtは無視）
2. llms.txtがなければ → 自前でllms.txt形式のファイルを自動生成
3. スキル発動時 → 都度WebFetchで詳細取得（常に最新）

実行フロー

┌─────────────────────────────────────────────────┐
│ Phase 1: URL解析                                 │
├─────────────────────────────────────────────────┤
│ 1. /llms.txt を確認                              │
│    ├── あり → curlでダウンロード                  │
│    │         （llms-full.txtは無視）              │
│    │         → Phase 4 へ                        │
│    └── なし → Phase 1.5 へ                       │
└─────────────────────────────────────────────────┘
                    ↓ (llms.txtなし)
┌─────────────────────────────────────────────────┐
│ Phase 1.5: URL収集 + ユーザー確認                │
├─────────────────────────────────────────────────┤
│ - サイトマップ/ナビゲーションからURL収集          │
│ - 収集URLリストを提示                            │
│ - ユーザー承認を待つ                             │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Phase 2: ドキュメント収集                        │
├─────────────────────────────────────────────────┤
│ - 各URLをWebFetchで取得                          │
│ - タイトル + 概要 + コード例 + API情報を抽出     │
│ - カテゴリ分け                                   │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Phase 3: docs.md生成                             │
├─────────────────────────────────────────────────┤
│ - template.mdを参照                              │
│ - 詳細形式で整形（概要+コード例+API情報）        │
│ - 品質チェックリストを確認                       │
│ - references/docs.mdとして保存                   │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Phase 4: SKILL.md生成                            │
├─────────────────────────────────────────────────┤
│ - スキルディレクトリ作成                          │
│ - SKILL.md生成（WebFetch都度取得方式）           │
└─────────────────────────────────────────────────┘

---

Phase 1: URL解析

llms.txtの確認（最優先）

1. /llms.txt をWebFetchで確認

   WebFetch(url="https://example.com/llms.txt", prompt="Check if this is a valid llms.txt file")
   

2. 存在する場合:

   • docs.md として保存（llms.md は作らない）

   mkdir -p .claude/skills/{library}/references
   curl -s https://example.com/llms.txt -o .claude/skills/{library}/references/docs.md
   

   • Phase 4（ファイル生成）へ直接進む（ユーザー確認不要）

3. 存在しない場合:

   • Phase 1.5へ進む

llms.txtの一般的なパターン

| サイト | llms.txt URL | |--------|--------------| | Expo | https://docs.expo.dev/llms.txt | | Vercel | https://vercel.com/llms.txt | | Tamagui | https://tamagui.dev/llms.txt | | その他 | /llms.txt を確認 |

---

Phase 1.5: URL収集 + ユーザー確認

llms.txtがない場合のみ実行

1. URL収集

サイトマップ確認:

curl -s https://example.com/sitemap.xml -o sitemap.xml

ナビゲーション解析:

WebFetch(
  url="https://example.com/docs",
  prompt="Extract all documentation page URLs from the navigation/sidebar. Return as a list of URLs."
)

2. ユーザー確認

収集したURLリストを提示し、承認を待つ:

以下のURLを収集対象として検出しました:

Getting Started:
- https://example.com/docs/getting-started
- https://example.com/docs/installation

API Reference:
- https://example.com/docs/api/hooks
- https://example.com/docs/api/components
...

このリストで収集を開始してよろしいですか？
除外したいURLや追加したいURLがあれば教えてください。

---

Phase 2: ドキュメント収集

目的: 各URLから包括的な情報を抽出（概要、コード例、API情報を含む）

取得する情報

各URLから以下を抽出:

1. 基本情報

   • ページタイトル
   • 概要（最初の1-2文）

2. 主要コンテンツ

   • セクション見出し
   • 重要な説明文（箇条書き）

3. コード例

   • 基本的な使用例（最初のコードブロック）
   • インポート文

4. API情報（APIリファレンスページの場合）

   • 関数/コンポーネント名
   • パラメータと型
   • 戻り値

WebFetchプロンプト（詳細版）

WebFetch(
  url="[URL]",
  prompt="Extract the following from this documentation page:
  1. Page title
  2. Brief description (1-2 sentences)
  3. Main content summary (key points as bullet list)
  4. First code example with imports
  5. API signatures if present (function name, parameters, return type)
  Format as structured markdown."
)

並列取得

ページ数が多い場合はTaskエージェントを並列起動:

Task(subagent_type="Explore", prompt="以下のURLから詳細情報を抽出: [URLリストA]")
Task(subagent_type="Explore", prompt="以下のURLから詳細情報を抽出: [URLリストB]")

カテゴリ分け

URLパターンで自動分類:

| パターン | カテゴリ | |----------|----------| | /getting-started, /quickstart, /intro | Getting Started | | /installation, /setup | Getting Started | | /api, /reference | API Reference | | /concepts, /fundamentals | Core Concepts | | /guides, /how-to | Guides | | /examples, /tutorials | Examples | | /advanced, /configuration | Optional |

---

Phase 3: docs.md生成

生成手順

1. 収集情報の整理

   • Phase 2で取得した全情報を整理
   • 重複・無効URLを除外
   • 情報の欠落がないか確認

2. カテゴリ分類

   • URLパターンと内容に基づいて分類
   • Getting Started / Core Concepts / API Reference / Guides / Examples

3. 構造化

   • 各ページごとにサブセクションを作成
   • 概要 → 主要ポイント → コード例 → API情報 の順で記載

4. 品質チェック

   • 下記チェックリストを確認

5. 保存

   • references/docs.md として保存

template.mdを参照

templates/docs.md を参照して、詳細な出力形式で整形する。

出力形式（詳細版）

# {Library}

> {ライブラリの概要を1-2文で}

## Getting Started

### Installation
- **URL**: https://...
- **概要**: インストール方法
- **手順**:
  - npm install {package}
  - 設定ファイルの作成

### Quick Start
- **URL**: https://...
- **概要**: 基本的な使い方
- **コード例**:
  ```tsx
  import { useQuery } from '@tanstack/react-query'

  function Example() {
    const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
  }

API Reference

useQuery

• URL: https://...
• 概要: データ取得用フック
• シグネチャ: useQuery(options: UseQueryOptions): UseQueryResult
• 主要パラメータ:
  • queryKey: クエリの一意識別子
  • queryFn: データ取得関数
• コード例:

  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  })
  

### 品質チェックリスト

生成後、以下を確認:

- [ ] **必須セクション**: Library名、Description、Getting Started が含まれている
- [ ] **URL検証**: 全URLがアクセス可能
- [ ] **コード例**: 主要機能にコード例がある
- [ ] **API情報**: API Referenceページにはシグネチャがある
- [ ] **重複なし**: 同じ内容が複数回出現していない
- [ ] **網羅性**: 主要なドキュメントページが含まれている

### 良い例・悪い例

**良い例:**
```markdown
### useQuery
- **URL**: https://tanstack.com/query/latest/docs/react/reference/useQuery
- **概要**: サーバーからのデータ取得・キャッシュ・再検証を行うフック
- **シグネチャ**: `useQuery(options): UseQueryResult`
- **主要パラメータ**:
  - `queryKey: QueryKey` - クエリの一意識別子
  - `queryFn: QueryFunction` - データ取得関数
- **コード例**:
  ```tsx
  const { data, isLoading } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

**悪い例:**
```markdown
- [useQuery](URL): フック

保存

# references/docs.md として保存
Write to: .claude/skills/{library}/references/docs.md

---

Phase 4: SKILL.md生成

ファイル構成

{library}/
├── SKILL.md              # メインスキルファイル
└── references/
    └── docs.md           # llms.txt形式（リンク集 + 概要）

SKILL.mdテンプレート

templates/skill.md を参照して、SKILL.mdを生成する。

プレースホルダーを実際の値に置き換える:

• {library}: スキル名（小文字、ハイフン区切り）
• {Library}: ライブラリの表示名
• {package-name}: メインパッケージ名
• {日本語キーワード}: 日本語での呼び出しキーワード

descriptionの書き方

ルール:

• 1024文字以内
• 英語（最終行の日本語キーワード部分を除く）
• 三人称・動詞で始める

トリガー条件を含める:

1. import文のパターン: imports "package-name"
2. ワイルドカード: any "@tanstack/*" packages
3. ユーザーの質問パターン: asks about {Library}
4. 関連キーワード: 主要なAPI名、関数名、コンポーネント名

良い例:

description: |
  Provides documentation for TanStack Query (React Query).
  Use when working with code that imports "useQuery", "useMutation", "@tanstack/react-query", or any "@tanstack/query-*" packages.
  Use when the user asks about data fetching, caching, or shows code with React Query hooks.
  Can also be invoked directly with "React Query", "TanStack Query", "データフェッチ".

---

生成されるスキルの動作

スキル発動時:
  1. references/docs.md を読む
  2. 質問に関連するセクション/URLを特定
  3. WebFetchで該当URLの詳細を取得
  4. 回答を生成

メリット:

• スキル生成が高速（全文クロール不要）
• 常に最新情報（都度Fetch）
• ストレージ節約
• llms.txtありなしで同じ使い勝手

---

クロールのベストプラクティス

技術的な詳細は crawling-guide.md を参照。

---

トラブルシューティング

SPAサイトで取得できない

• 静的なドキュメントページを探す
• GitHubリポジトリのドキュメントを確認
• 代替ドキュメントソース（MDN、DevDocs等）を検討

構造が複雑

• 手動でdocs.mdを調整
• 目次を追加して参照しやすくする