docs-search

Docs Search — 公式ライブラリドキュメントのナビゲーション方法

エージェントがライブラリの公式ドキュメントを参照する際に行う、汎用的な操作をまとめた方法論です。ライブラリごとのスキルではありません。作業の90％は検索対象のライブラリに関係なく同じであるため、1つのスキルと、共有ナレッジグラフ内の簡潔なライブラリごとの記録（/knowledge/libraries/）で構成されています。

これは、library-reference-distillation と並ぶナビゲーションレイヤーです。あちらのスキルは、時間をかけてイディオムを抽出し、ライブラリ参照用のルールパック全体を作成するためのものです。このスキルは、時間をかけずに何かを調べるだけの場合に使います。ルールパック全体ではなく、約30行の地形記録を作成単位とする、より軽量で素早く作成できる代替手段です。

適用するタイミング

次の場合にこのスキルを使います。

• エージェントがライブラリの公式ドキュメントから具体的な答えを得る必要があり、次の手として「ドキュメントを検索する」場合
• ユーザーが「<library> のドキュメントで X はどこにありますか？」や「<library> で最近 Y に変更はありましたか？」と尋ねた場合
• ドキュメントの内容が状況に合っているように見えるものの、本番環境での動作が異なる場合
• エージェントがライブラリに関する質問を Google で検索しようとしており、まずライブラリ独自のサイト内検索、llms.txt、または変更履歴を確認すると役立つ場合
• 以前使ったことのあるライブラリについて registry/ に地形記録がある場合 — ナビゲーションを始める前に読みます
• ライブラリは使ったことがあるものの、記録がまだない場合 — この方法論を適用し、次回の検索を効率化するために、見つけた内容を registry/<library>.md に記録します

このスキルは、次の用途には使いません。

• ライブラリ参照用ルールパックの作成 — イディオムや失敗時のギャップに関するルールを抽出し、洗練されたスキルにまとめたい場合は、代わりに library-reference-distillation を使います。ライブラリ X 用の完全なライブラリ参照スキルができたら、X のレジストリエントリーは不要になるため、削除してください。
• 一般的なウェブ検索 — 特定のライブラリの公式ドキュメントに関する質問ではない場合（例：「エコシステム全体で X を実現する最善の方法は何ですか？」）、このツールは適切ではありません。
• 社内・独自のドキュメントの閲覧 — llms.txt、公開された変更履歴、公開されたイシューがない場合には使いません。この方法論は、公開され、バージョン管理されているオープンソース形式のドキュメントを前提としています。

使い方

4つのカテゴリは互いに独立した操作です。症状に応じて操作を選びます。

症状	選ぶ操作	最初に読むルール
質問が曖昧 — 「ドキュメントで X を検索する」	ソースを選ぶ	src-decision-tree
HTML をスクレイピングしようとしているが、AI 向けの標準形式を確認していない	ソースを選ぶ（llms.txt）	src-llms-txt-first
名前が指定されたエントリーを読む前に knowledge/libraries/ を確認しようとしている	ソースを選ぶ（対象を限定して読む）	src-bounded-knowledge-read
最新のドキュメントを読んでいるが、ユーザーは古いバージョンを使っている可能性がある	バージョンを合わせる	ver-find-selector
質問が「アップグレード後に X は変わりましたか？」	バージョンを合わせる（変更履歴）	ver-changelog-first
ドキュメントの内容と本番環境での動作が一致しない	別の方法に切り替える	fall-known-issues
質問が「このイディオムを慣例に沿ってどう構成すればよいですか？」	別の方法に切り替える（サンプル）	fall-samples-over-prose
標準的なエントリーポイントを見つけ、次に進もうとしている	再利用できる形で記録する	capture-registry-record

カテゴリの概要と順序の根拠については、references/_sections.md を参照してください。

ルールのカテゴリ

#	カテゴリ	プレフィックス	方針	ルール
1	ソースを選ぶ	src	質問を分類し、llms.txt を確認してから、範囲を限定してナレッジを読む	3
2	バージョンを照合する	ver	ユーザーのバージョンに合わせ、リファレンスより先に変更履歴を確認する	2
3	フォールバックする	fall	ドキュメントと実際の動作が矛盾する場合は既知の問題を確認し、慣用的な書き方は説明文よりサンプルを優先する	2
4	再利用できるよう記録する	capture	レジストリに構成を記録し、次回の検索を速くする	1

クイックリファレンス

1. ソースを選ぶ

• src-decision-tree — セクションを選ぶ前に、質問を分類します（API の動作／変更履歴／慣用的な書き方／既知のバグ／移行）。「ドキュメントを検索する」だけでは計画になりません
• src-llms-txt-first — HTML を取得する前に、<docs-root>/llms.txt または /llms-full.txt を確認します。存在する場合は、AI 向けの標準形式です
• src-bounded-knowledge-read — ファイル名がインデックスです。knowledge/libraries/<slug>.md だけを読み、ディレクトリをスキャンしないでください。ナレッジストアのサイズに関係なく、呼び出しごとのトークンコストを一定の範囲に保てます

2. バージョンを照合する

• ver-find-selector — リファレンスページを読む前に、バージョンセレクターを見つけます。ユーザーに尋ねるか、package.json を読んでバージョンを特定します
• ver-changelog-first — 質問に「アップグレードしてから」や「X は変更されましたか」が含まれている場合は、リファレンスより先に変更履歴を読みます

3. フォールバックする

• fall-known-issues — ドキュメントがユーザーのコードと一致しているのに実際の動作が異なる場合は、ドキュメントを読み直す前に、GitHub のイシュー、ステータスページ、Discord／フォーラムで既知のバグを確認します
• fall-samples-over-prose — 「どのように構成すべきですか？」という質問では、まず examples/ ディレクトリまたはサンプルリポジトリを確認します。慣用的な構成は説明文ではなくコードにあります

4. 再利用できるよう記録する

• capture-registry-record — 新しいライブラリの検索が成功したら、knowledge/libraries/<library>.md の docs: セクションに記録し、今後の検索で調査フェーズを省略できるようにします

ナレッジストア

ライブラリごとの構成記録は、リポジトリルートにある共有ナレッジグラフの /knowledge/libraries/ に保存されています。同じファイルは code-distill からも書き込まれます。各スキルはそれぞれのセクション（このスキルは docs:、code-distill は code:）を所有し、互いの内容を上書きしません。統合スキーマ、Wiki リンクの規約、マージの手順については、knowledge/README.md を参照してください。

ナレッジストアは v0.1.0 では意図的に空です。最初の記録は事前に追加するのではなく、実際の検索で必要になったときに追加します。実際に検索していないライブラリの記録を追加しようとしていることに気づいたら、作業を止め、必要になるまで待ってください。

読み取りの規律：ユーザーがライブラリを指定したら、必ず read knowledge/libraries/<slug>.md を実行します。「何があるか」を確認するために knowledge/libraries/ をスキャンしてはいけません。ファイル名がインデックスであり、必要なときだけアクセスすることで、ナレッジストアのサイズに関係なく、呼び出しごとのトークンコストを一定の範囲に保てます。

関連スキル

• library-reference-distillation — ライブラリリファレンス向けの完全なルールセットを作成するための手引きです（より大規模な関連スキル）。ライブラリ X 向けの完全なライブラリリファレンススキルが公開されたら、X のレジストリエントリを削除します
• radical-simplification — このスキルの上位にある思考レイヤーです。このスキル自体も、「どう調べればよいか」という質問に対して「制約する → 不変条件に名前を付ける」という方法を適用した例です
• init（および類似のスキル）— 調べる対象が 自分のコードベース の場合は別の問題です。このスキルは外部ライブラリのドキュメントを対象としています

作成者向け注記

これらのルールは重要な役割を担うものであり、飾りではありません。それぞれ、ドキュメントを参照する際にエージェントが陥りがちな誤った既定の行動を示しています。あらゆる質問を「ドキュメントを検索すること」と捉える、llms.txt を無視する、ユーザーが古いバージョンを使っているのに最新のリファレンスページを読む、現実と食い違ったときにドキュメントを読み直す、コードより説明文を優先する、次回も同じ検索作業をやり直す、といった行動です。プロンプトを与えれば有能なモデルがすでに正しく行うことを言い換えただけのルールは削除してください。網羅性はルールの数ではなく、実際のドキュメント検索プロンプトに対する /dev-skill:eval で検証します。レジストリは、実際の検索で項目が必要になったときに自然に拡張していきます。