ライブラリドキュメント生成ガイド
概要
ライブラリのドキュメントからスキルを自動生成する。
方針:
- llms.txtがあれば → そのまま使う（リンク先はクロールしない、llms-full.txtは無視）
- llms.txtがなければ → 自前でllms.txt形式のファイルを自動生成
- スキル発動時 → 都度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の確認（最優先）
-
/llms.txtをWebFetchで確認WebFetch(url="https://example.com/llms.txt", prompt="Check if this is a valid llms.txt file") -
存在する場合:
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（ファイル生成）へ直接進む（ユーザー確認不要）
-
存在しない場合:
- 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-2文）
-
主要コンテンツ
- セクション見出し
- 重要な説明文（箇条書き）
-
コード例
- 基本的な使用例（最初のコードブロック）
- インポート文
-
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生成
生成手順
-
収集情報の整理
- Phase 2で取得した全情報を整理
- 重複・無効URLを除外
- 情報の欠落がないか確認
-
カテゴリ分類
- URLパターンと内容に基づいて分類
- Getting Started / Core Concepts / API Reference / Guides / Examples
-
構造化
- 各ページごとにサブセクションを作成
- 概要 → 主要ポイント → コード例 → API情報 の順で記載
-
品質チェック
- 下記チェックリストを確認
-
保存
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文字以内
- 英語（最終行の日本語キーワード部分を除く）
- 三人称・動詞で始める
トリガー条件を含める:
- import文のパターン:
imports "package-name" - ワイルドカード:
any "@tanstack/*" packages - ユーザーの質問パターン:
asks about {Library} - 関連キーワード: 主要な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を調整
- 目次を追加して参照しやすくする