research-library

リサーチライブラリ

$RESEARCH_HOME（デフォルトは ~/research）は、特定の Git リポジトリ内に置くべきではない参照資料を、プロジェクト間で共有するための保管場所です。ベンダーのリポジトリのクローン、PDF／epub、ドキュメントサイトのミラーなどを保存します。これは、次の2つを避けるためにあります。（1）精査されていないサードパーティのコンテンツが、たまたまリポジトリの作業ツリー内にあるというだけで、エージェントに周囲の情報として読み込まれること。（2）各プロジェクトが同じ参照資料をそれぞれの Git 管理対象外フォルダーにクローンすること。

このスキルはライブラリが存在することを前提としています。 ライブラリは単なるディレクトリであり、インストールするものはありません。また、以下の規約以外に、このレイアウトに依存するものはありません。$RESEARCH_HOME が未設定で、~/research も存在しない場合は、その旨を伝え、ウェブから取得する方法に黙って切り替えるのではなく、作成を提案してください。設定作業は、シェルプロファイルで RESEARCH_HOME を設定することだけです。

このスキルが読み取り、実行し、書き込むもの

• 読み取り：$RESEARCH_HOME とその中のエントリー、および参照先を確認するためのリポジトリ自身の AGENTS.md。 size --ungreppable は、保管場所内のすべてのファイルを開き、先頭の 8 KB を読み取ります。
• 実行：ライブラリ内のクローンに対する git clone／fetch／reset／sparse-checkout／tag -d／reflog expire／gc のみ。また、パッケージの健全性確認（リポジトリの統計、コミット、Issue、リリース一覧、最新リリース）には gh api を使い、add でクローンする前にリポジトリの報告サイズを確認します。 package_health.py は、基準値と比較するため、node が PATH にある場合は node --version も実行します。また、apt ソースについては apt-cache policy と apt-cache show を実行します。これらはこのマシンの apt キャッシュを読み取るだけです。
• 書き込み：$RESEARCH_HOME 内のみです。add はクローンを作成して来歴ファイルを書き込み、provenance はそのファイルを書き込み、update、deepen、reshallow はクローンとその depth: フィールドを変更します。 name、check、size は何も書き込まず、--dry-run は実行される内容を表示します。プロジェクトのリポジトリにシンボリックリンクを作成したり、コピーしたりすることはありません。また、保管場所の外にあるものに触れることもありません。
• 環境変数からの読み取り：保管場所には RESEARCH_HOME、add でデフォルトとしてテキストのみをクローンするかどうかには RESEARCH_TEXT_ONLY を使います。
• ネットワーク：指定されたクローン URL、PyPI、npm レジストリ、crates.io、Debian の madison API（api.ftp-master.debian.org）、Launchpad（api.launchpad.net）、package_health.py 用の GitHub、クローン前のサイズ確認用の GitHub、およびユーザー自身の gh ログイン経由の GitHubに接続します。公開されている読み取り専用エンドポイントのみを使用し、アップロードは行いません。

ウェブから何かを取得する前に

WebFetch／WebSearch を使ったり、新しいコピーをクローンしたりする前に、対象のトピックに関する資料が $RESEARCH_HOME/repos/、$RESEARCH_HOME/docs/、$RESEARCH_HOME/pages/ にすでに存在するか確認してください。プロジェクト自身の AGENTS.md に、そのプロジェクトに関連する具体的なエントリーへの参照が記載されている場合もあります。

レイアウト

$RESEARCH_HOME/
  repos/<host>--<owner>--<repo>/   # shallow git clones
  docs/<file>.pdf|.epub            # downloaded reference docs
  pages/<slug>/                    # mirrored/llms.txt-derived doc site snapshots
  README.md                        # full conventions + rationale

エントリの命名、追加、確認

すべてのホスト上のすべてのリポジトリで、例外や GitHub 固有の扱いを設けず、<host>--<owner>--<repo> という規則に従います。また、すべてのエントリに来歴ファイルを付けます。どちらも手作業で導き出さないでください。そのための処理が scripts/library.py であり、これが存在する理由は、どちらの失敗も気づかれないまま起きるからです。渡された URL から名前を導き出すと、クローン自体の origin から導き出した名前ではなくても、まったく普通に見えてしまいます（セルフホストのインスタンスは有名なホストに似ており、名前が変更されたリポジトリは何も通知せずにリダイレクトします）。また、何もバージョン管理されないストアでは、それに気づくものがほかにありません。

python3 $S/scripts/library.py name <url>            # the entry name, from any spelling of a remote
python3 $S/scripts/library.py add <url>             # clone, canonical name, SOURCE.md written
python3 $S/scripts/library.py add <url> --dry-run   # the clone and the file it would write
python3 $S/scripts/library.py check                 # every entry against these conventions

S=~/.agents/skills/research-library。add はクローン後にクローン自体のリモートから名前を再導出し、食い違っていればエントリ名を変更します。実際に取得したブランチと短縮 SHA を ref として記録し、別途指定されない限りテキストのみをクローンします。省かれるものと、それが検索に影響しない理由については以下を参照してください。Git クローンではないエントリ（ダウンロードした PDF、ミラーリングしたドキュメントサイトなど）については、素材に応じた方法で取得した後、library.py provenance <path> --url <url> --kind <kind> --ref <ref> を実行してメタデータ部分を書き込みます。ここが決定的な部分であり、省略される部分でもあります。すべてのコマンドで --json を指定できます。name と check は読み取り専用で、add と provenance は $RESEARCH_HOME の中だけに書き込みます。

check が形式を検証するため、また、読み手が手作業で修正する必要が生じる場合に備えて、来歴ファイルの形式を示します。含める項目は url、kind（repo-clone、llms-txt-mirror、site-mirror のいずれか）、ref（クローンの場合はブランチ／タグ／コミット、ミラーの場合は取得日）、fetched、履歴を意図的に深くした場合の depth（以下を参照）、チェックアウトの範囲を絞った場合の text-only（以下を参照）、そして一目で明らかでない場合に限る note（たとえば、クローンしたものとは異なるブランチまたはリポジトリからドキュメントを公開している場合）です。

add は、ホストが大容量と判定したものをクローンする前に確認を求めます。プロンプトは表示せず、報告された容量を示して終了コード 3 で終了します。エージェントの Bash 呼び出し内の対話型プロンプトは、入力するものがないまま停止してしまうためです。--yes を指定すると続行します。--min <MB> を指定するとしきい値を変更できます（デフォルトは 250 MB）。--depth N または --full を指定すると、コミットを 1 つより多くクローンし、その内容を記録します。この確認には GitHub の API を使うため、問い合わせできないホストからクローンすることを拒むことはありません。

報告されるサイズは処理を開始するためのしきい値であり、実際の容量予測ではありません。また、警告には意図的に見積もりを記載しません。 2026-09-07 に深さ 1 で実際のエントリ 5 件を測定したところ、ディスク上の容量は報告サイズの 0.23 倍（cpython は報告値 851 MB、ディスク上では 192 MB）から 1.32 倍（Roo-Code は報告値 359 MB、ディスク上では 473 MB）の範囲でした。5.7 倍もの幅があり、上限ですらありません。予測値を記載した警告は、安心させる方向に 4 倍も外れていたことになります。

クローンにはテキストが保持されます。検索するのはテキストだけだからです

add はデフォルトでテキストのみをクローンします。画像、動画、音声、フォント、アーカイブ、コンパイル済みオブジェクト、モデルの重みはサーバーに残し、テキスト検索で読み取れるものはすべてチェックアウトします。--all-files を指定するとエントリー単位でこの設定を解除でき、RESEARCH_TEXT_ONLY=0 を指定するとマシン全体で解除できます。

python3 $S/scripts/library.py add <url>               # text-only, the default
python3 $S/scripts/library.py add <url> --all-files   # every file, images and binaries included
python3 $S/scripts/library.py add <url> --dry-run     # the two commands and the file it would write

除外によって検索結果が1件でも失われてはならず、それだけがこれをデフォルトにしている理由です。 除外される形式はどれも、ripgrep と grep がすでに検索対象にしていないものです。どちらも、ファイルの先頭ブロックに NUL バイトがあるとバイナリと判定してスキップするため、そのバイト列が検索にもたらすものはありません。このため、ディレクトリを除外する判断とは異なります。ディレクトリを除外すると grep が気付かないまま検索できなくなりますが、まさにその理由から、ここでは採用していません。

2026-09-08 に intellectronica/ruler でエンドツーエンドの検証を実施しました。バイナリが97%を占めるこのリポジトリを、同じコミットから2通りの方法でクローンしたところ、どちらのツリーにも検索可能なファイルが257個あり、その集合も同一でした。また、grep -rIl ruler が両方で190個のファイルを返し、テキストのみのクローンから欠けていたファイルは1つ、69 MB の .gif でした。ディスク上では141 MBが3.0 MBになり、.git は70 MBから644 KBになりました。

最後の数値こそ知っておく価値があります。単独では何の効果もない2つの仕組みを組み合わせて得られる数値だからです。--filter=blob:none は --depth 1 のクローンでは何も先送りしません。チェックアウト時に HEAD のすべての blob が実体化されるためです。スパースセットだけなら作業ツリーは小さくなりますが、.git のサイズはまったく変わりません。両方を組み合わせると、スパースセットが必要としない blob は取得されません。一方だけを使ったクローンでは、見かけから想像されるほど容量を節約できません。

ドキュメントは保持します。PDFがその理由です。 PDFは grep にとってはバイナリですが、エージェントには読み取り可能です。したがって、区別の基準は「grep で検索可能かどうか」ではなく、「ドキュメントか、デモ用アセットか」です。現在、リポジトリのクローン内には9個のPDFがあり、合計6.6 MBで、**除外される容量の0.5%**です。その中には4.6 MBの flameshot-documentation.pdf も含まれています。節約分の0.5%を使えば、読み手が必要とするものを失いかねない唯一のケースをなくせます。電子書籍やオフィス文書の形式も同じ判断で保持します。.svg は例外にする必要がありません。テキスト形式なので、NULルールによってそのまま保持されます。

HEADよりも狭い範囲をチェックアウトするエントリーは、そのことを明示しなければなりません。そうでないと、後で grep が何も見つけなかったとき、何がチェックアウトされたのかを問うべき状況が、答えとして受け取られてしまいます。add は text-only: yes を記録し、check は両方向のずれを報告します。つまり、フルチェックアウトなのにその設定を主張しているエントリーと、記録がないのにスパースチェックアウトされているケースです。これにより、誰かが手動で適用したパスベースの sparse-checkout も検出できます。

update に特別な処理は不要です。浅いフェッチとハードリセットを行っても、core.sparseCheckout とパターンリストは維持されることを、実際の更新で確認済みです。

ライブラリの容量

python3 $S/scripts/library.py size                  # entries at or above 250 MB, biggest first
python3 $S/scripts/library.py size --min 0          # everything
python3 $S/scripts/library.py size --ungreppable    # and how much of it no text search can read

--ungreppable により、既存のエントリーを再クローンするかどうかを、理念ではなく数値に基づいて判断できます。除外リストではなく内容で分類するため、レポートがパターンと食い違うこともあります。これにより、拡張子のない残存ファイルが可視化されます。ライブラリ全体で620ファイル、16 MB、grepできない容量の1.25%で、どの拡張子パターンでも対象にできません。2つ目のフィルターを設ける理由にはならず、結論として示すのに十分小さい値です。ストア内の全ファイルを読み取るため（3 GBのライブラリで、ウォーム時に184,279ファイルを2.9秒で処理）、フラグとして用意されています。

2026-09-08に86エントリーを測定した結果、作業ツリー3,274 MBのうち1,286 MB、39%がgrepできない状態です。容量は一部に集中しており、block/goose は343 MB中310 MB、RooCodeInc/Roo-Code は293 MB中276 MBです。一方、ライブラリ最大のエントリーは、パス除外を別の問題として扱うべきことを示す反例です。nodejs/node は669 MB中15 MBで、669 MBの作業ツリーはベンダー提供のV8とOpenSSLのソースコードであり、最後の1バイトまでgrepできます。

エントリーごとに.gitと作業ツリーを分けて測定します。それぞれに対処法が異なり、比率から適用すべき対処法がわかるためです。単一コミットで.gitが大きい場合は大きなBLOBが原因で、唯一の対策はクローンを保持しないことです。単一コミットで作業ツリーが大きい場合は、ベンダーディレクトリが原因です。実際の4.8 GBのライブラリで最悪のエントリーを測定したところ、単一コミットで940 MBあり、そのうち675 MBを単一のベンダー提供のdeps/ディレクトリが占めていました。一方、参照用クローンに存在するsrc、lib、docの合計は34 MBでした。そこでは深さは問題ではなく、浅いクローンをどれだけ作り直しても容量は変わりません。

更新、履歴を深める、ディスク容量を取り戻す

python3 $S/scripts/library.py update                      # every clone, each at its intended depth
python3 $S/scripts/library.py update <entry>              # just this one
python3 $S/scripts/library.py deepen <entry> --depth 500  # more history, recorded as deliberate
python3 $S/scripts/library.py reshallow <entry>           # back to a depth-1 footprint, disk included

update は各クローンをリモートの最新状態に更新します。使い捨ての参照用クローンであり、ローカルコミットを保持する作業コピーではないため、浅いフェッチとハードリセットを行います。update と library.py check はそれぞれ異なる問いに答えるもので、どちらももう一方の代わりにはなりません。一方はすべてのクローンを先に進め、もう一方は先に進めても何もできない可能性があるかどうかを示します。

記録がないまま 1 コミットより深いクローンは、切り詰めずにスキップします。 意図的に深めたのか、誤って深めたのかを見分ける方法はなく、切り詰めると読み直しても元に戻せません。2026-09-07 に 71 件のライブラリで確認したところ、深いエントリーはちょうど 1 件で、依存関係の制約履歴を読むために意図的に深められていました。すべてを fetch --depth 1 で更新するループでは、それが何の通知もなく失われていたでしょう。手入力した git fetch ではなく deepen を使ってください。意図がエントリーの depth: フィールドに記録され、update がそれを確認できるようになります。

reshallow があるのは、手動で浅い状態に戻してもディスク容量を取り戻せないからです。 2026-09-07 に encode/httpx で測定した .git のサイズ（KB）は次のとおりです。新規の --depth 1 クローンは 2,492 KB です。400 コミット分深めてから、fetch --depth 1 と reset --hard で再び浅い状態にすると、再び 1 コミットと表示されますが、ディスク使用量はまったく減りません。さらに reflog expire、gc --prune=now、repack -a -d、prune、gc --aggressive を加えても 4,852 KB になったところで止まります。原因はタグです。深めるとタグも取得され、それぞれが履歴の深い位置にあるコミットを参照するため、その下にあるすべてのオブジェクトが引き続き到達可能になります。タグを削除すると、同じクローンは 2,472 KB になり、開始時より小さくなります。広く公開されている手順にはその手順が抜けているため、そのまま実行するとクローンは恒久的に 95% 大きいままで、成功したと報告されます。これは順番どおりに実行する 5 つのコマンドで、そのうち 1 つは参考資料にまったく載っていません。まさにコードに含めるべき処理です。

デタッチ状態の HEAD では拒否します。タグこそが、そのクローンが存在する理由かもしれないためです。--force を指定すると上書きできます。

更新後も不自然に古く見えるエントリーは、ピン留めされていることがほとんどです。 check がそのエントリーを示します。明示的に --branch <tag> を指定して作成したクローンは HEAD がデタッチ状態になり、その参照を永久に追跡します。そのため git fetch origin を実行しても同じものを再取得し、何年も前のものなのに更新処理では「最新」と報告されます。2026-09-02 に 52 件のライブラリに対して check を初めて実行した際に確認しました。このようなクローンは 1 件で、より単純なルールならピン留めとして検出されていた 51 件は、このスキルの説明どおりにクローンされていました。check --remote は、ネットワーク接続が必要な唯一の確認事項である、追跡中のブランチが今もリモートのデフォルトかどうかを調べます。それ以外の処理を即座に終えられるよう、デフォルトでは無効になっています。

README の説明を鵜呑みにせず、実際のソースを grep する

リポジトリをクローンしたら、README やドキュメントサイトの説明を信頼するよりも、真実を確認するために実際のソースを grep してください。インストール済みのバージョンと比べて、どちらも古かったり、誤っていたりする可能性があります。これまでに実際のバグを発見したことがあります。インストール済みの GNOME バージョンには存在しない GNOME キーバインディングスキーマを説明していたドキュメントページ（gnome-shell のソースを直接読んで初めて判明）や、実際のマウント動作が、レンダリング済みのドキュメントページではなく、実際の最小化された JS バンドルにしか一致しなかったドキュメントサイトのビルドツールなどです。

どちらも情報の古さが原因です。さらに深刻なケースもあります。README で機能をうたっているのに、そもそも実装されていないケースです。ingesta 用の服薬管理ツールを調査していた 2026-08-27 に確認しました。ある Home Assistant インテグレーションの README には NIH RxNorm による成分検索が機能として記載されていましたが、README 以外のリポジトリ内には rxnorm も ingredient もどこにもありませんでした。機能一覧を比較するだけなら存在すると判定されますが、grep すればすぐに確認できます。「このプロジェクトは X を実行できるか」という疑問への、手軽で決定的な確認方法は、ドキュメントの主張ではなく、X がコード内に実際に登場するかどうかです。

オープンソースの候補では、ソースが実際に試してみるよりも優れている理由も同じです。試用ではたまたま通った経路を確認できますが、ソースを見れば存在するすべての経路がわかります。また、UI からはわからない、用量が数値なのか自由入力なのか、権限がマニフェストから削除されているのか、といった疑問にも答えられます。

依存関係の候補を評価する

ライブラリやツールを選ぶ際も、上記のルールと同じ考え方を一歩先に適用します。概要の主張ではなく、ソースが何を示しているかを確認します。検索結果の概要ではなく、パッケージ自身のレジストリメタデータとファイル一覧からパッケージを評価してください。実際に確認すべき項目は次のとおりです。

各候補は、他候補と直接比較する前に、それぞれ単独で絶対的な基準に照らして評価してください。 人気は、一定の水準を超えると弱い指標であり、決して同点を破る基準にはなりません。人気が低くても基準を満たすプロジェクトは、人気が高くても基準を満たさないプロジェクトより優れています。Telegram ライブラリ 2 つから選んだ 2026-08-30 にこの方針を示しました。スクリプトがスター数を not scored の下に表示するのもこのためです。

python3 $S/scripts/package_health.py pypi <name>
python3 $S/scripts/package_health.py pypi anyio --clone $RESEARCH_HOME/repos/github.com--agronholm--anyio
python3 $S/scripts/package_health.py pypi shellcheck-py --upstream koalaman/shellcheck
python3 $S/scripts/package_health.py npm @biomejs/biome
python3 $S/scripts/package_health.py crates ripgrep
python3 $S/scripts/package_health.py apt ripgrep
python3 $S/scripts/package_health.py github BurntSushi/ripgrep

標準ライブラリのみ、S=~/.agents/skills/research-library。ソースの指定は必須のサブコマンドです。pypi、npm、crates、apt、github のいずれかを指定し、デフォルト値はありません。そのため、毎回指定してください。廃止された package_health.py <name> <owner/repo> 形式は、代替手段を示して終了コード 2 で終了します。1 つのツールが複数の配布経路（PyPI または npm のラッパー、crate、apt パッケージ、リリースバイナリ）で提供されている場合は、各経路のソースを実行し、配布内容と費用を比較してください。パッケージ自身の GitHub リポジトリはメタデータから取得され、レポートの repo from 行に出所が示されます。その検索結果が誤っている、または見つからない場合は、--repo <owner/repo> を渡してください。レジストリには HTTPS を使用し、GitHub には gh api を使用して、独自のトークンとレート制限が適用されるようにします。すべてのソースで、回答全体を取得するには --json を指定してください。

各ソースで該当する場合に報告される評価軸と、それぞれの用途は次のとおりです。

• メンテナンス — stable 系列のリリースとそのリリース間隔の中央値、最終プッシュと最終リリースの比較（「活発に開発されているが、リリースは遅い」状態と「停滞」状態を区別します）、過去1年間の人間のコントリビューター数とバス係数、Issue のクローズまでの時間、アーカイブ済みフラグ、ライセンス、取り下げまたは非推奨となったリリースです。
• 型付け（動的型付けのエコシステムのみ）— PyPI の py.typed（--clone を使用）と、npm 独自の型定義、個別の @types/…、どちらもない場合を確認します。Python では、プロジェクト独自の型チェッカー設定とその厳格さも確認し、型の漏れを予測します。次に、お使いのチェッカーをお使いのモードで、実際の小規模な使用サンプルに対して実行します。ゲートでどのような結果になるかを示せるのは、これだけです。
• 実績 — pypi --clone を使用して、手書きのソースに対するテストとソースの比率（機械的なレイヤーには --generated <glob> を指定）、カバレッジが CI で強制されているのか、単に報告されるだけなのか、そして CI ワークフローが実際に何を対象としているのかを確認します。
• 適合性 — ランタイム依存関係の数と名前（主に extras で構成される生の requires_dist は使いません）、バージョン上限と、それが配布アーティファクトに適用されるのか、開発用ロックファイルにのみ適用されるのか、ライセンスの互換性、オフラインで実行できるかどうかを確認します。
• 配布物 — 最新の stable リリースをインストールしたときに実際にダウンロードされるものと、そのサイズを確認します。これは導入コストを示します。意味合いはソースごとに異なります。詳しくは以下をご覧ください。
• 最低要件 — メタデータに記載されたすべての最低バージョンを、推測せずに確認し、手間がかからない場合はこのマシンの環境とそれぞれ比較します。具体的には、requires_python とこのマシンの python3、manylinux タグまたは libc6 依存関係に記載された glibc の最低要件とこのマシンの glibc、engines.node とこのマシンの node、crate の MSRV、アセット名に記載された libc ファミリーを比較します。NOT MET HERE は要件を満たしていないことを示し、not compared は比較しなかった理由を示します。
• アップストリーム — pypi と npm で --upstream <owner/repo> を指定すると、ラッパーの場合、そのラッパーが再パッケージしているプロジェクトを示します。これはラッパー自身のリポジトリではありません。アップストリームの GitHub における最新の stable リリース、そのリリースと一致する形式で表記したラッパーのバージョン、経過日数を報告し、そのリリースの Linux x86_64 アセットと、同じ場所にあるチェックサムまたは署名ファイルを表示します。NO MATCHING WRAPPER RELEASE は、表記が異なるか、ラッパーが遅れていることを意味します。表示された2つのバージョンを比較してください。 GitHub digest はアップロードファイルの GitHub によるハッシュであり、発行元のチェックサムではありません。

ソースごとの追加項目：

• pypi <name> — wheel と sdist、そのタグ、サイズ、アップロード日を確認します。バイナリをラップするものを採用する前に、linux x86_64 の行を確認してください。wheel があればバイナリはその中に含まれています。SDIST ONLY または NO WHEEL for this machine の場合は、インストールのたびに pip がビルドするか、ビルドフックがダウンロードします。--clone <path> を指定すると、API では分からない情報、つまり py.typed、テストとソースの比率、CI の一覧、実際に存在するライセンスファイルも確認できます。
• npm <name> — 最新の公開版ではなく、dist-tags.latest に基づいて評価します。install scripts（RUNS AT INSTALL はインストール時にコードがマシン上で実行されることを意味します）、provenance、そして実際にバイナリを含むプラットフォームパッケージを確認します。これはデフォルトで解決されます。たとえば、@biomejs/biome のようなラッパーは 779 kB ですが、その Linux パッケージは 64.7 MB です。install size はこの2つを合わせたサイズです。
• crates <name> — crates.io が示す安定版、クレートのサイズと bin_names、MSRV（null の場合は undeclared）を確認します。クレートは cargo install がコンパイルするソースです。バイナリを含む場合は、最新の GitHub リリースの Linux アセットを「prebuilt binary」セクションに一覧表示します。
• apt <name> — これは別の問いであり、その旨がレポートにも示されます。apt パッケージはディストリビューションによって保守されています。レポートには、このマシンの候補パッケージと保守者（main は Canonical がサポートし、universe は Ubuntu Pro を利用する場合のみ Canonical のセキュリティ修正を受け、サードパーティーのリポジトリはその公開元が保守します）、サイズ、上流の安定版 GitHub リリースからの遅れ（上流情報はパッケージの Homepage、または --upstream から取得）、さらに、どの Ubuntu および Debian リリースにどのバージョンが含まれるかを示すリリース間比較が表示されます。apt とリリースバイナリのどちらを選ぶか、次の LTS で何が利用できるようになるかを判断するための情報です。
• github <owner/repo> — レジストリがなく、Go または Rust のバイナリがリリースアセットとしてのみ配布されているツール向けです。保守状況の軸、リリース一覧から分かる安定版のリリース頻度、最新安定版リリースの Linux x86_64 アセットを確認します。

レポートには、答えのように見えて落とし穴となる行が4つあります。表示どおりに読んでください。 open issues+PRs は GitHub のフィールドであり、両方を数えます。PRE-RELEASE ONLY または pre-releases の行は、安定版が更新されていない可能性がある一方で、開発版が進んでいることを意味します。shallow clone の行は、履歴に関する問いを調べる前に git fetch --deepen が必要であることを意味します。npm の tarball サイズはラッパー単体のサイズであり、見るべきなのは install size です。2026-09-02 に httpx で確認した例では、表面的に読むと、PyPI には過去1年間に4回のリリースがあり、最新のものは昨日公開されたとあります。しかし、安定版の行を見ると、過去1年間のリリースはゼロで、最後のリリースは634日前です。「自分にとって保守されているか」という問いへの答えは正反対になります。

数値だけでは見えないこと——バス係数を左右するボット、API が GPL と報告するデュアルライセンスのプロジェクト、履歴上の遅れが分かるまではバージョン上限が問題にならない理由、オフラインテストが可能であることの証明方法、各レジストリ固有の落とし穴——については、references/dependency-health.md を参照してください。推奨事項を書く前に読み、スクリプトを実行する前には読まないでください。

プロジェクトのリポジトリ内にシンボリックリンクを作らない

$RESEARCH_HOME またはその中の項目を、プロジェクトの作業ツリーにシンボリックリンクしてはいけません。そうすると、この内容がそのリポジトリを対象とするものの通常の読み取りパスに戻ってしまいます。これこそ、すべてのリポジトリの外に置いている理由です。タスクで実際に必要な場合に限り、$RESEARCH_HOME のパスを直接指定してアクセスしてください。

プロジェクトごとのポインター

このスキルでは、特定のプロジェクトでどの項目が重要なのか判断できません。各プロジェクトの AGENTS.md には、関連するパスを具体的に記載してください（「GNOME Shell 拡張機能の動作については、オンラインで何かを読む前に $RESEARCH_HOME/repos/gitlab.gnome.org--GNOME--gnome-shell を確認する」など）。これは提案ではなく、常設のルールとして記載します。これにより、AGENTS.md は読むもののスキルを発見する仕組みを持たないエージェントからも、このライブラリにアクセスできるようになります。

設計の背景

references/rationale.md — リポジトリごとの reference/ ディレクトリではなくこれが存在する理由、人気のホスト向けに命名の例外を設けていない理由、固定タグの更新に関する落とし穴、ドキュメントサイトのミラーリングに関する調査（llms.txt とその代替手段）、そして RAG／埋め込みについて調査したうえで、意図的に採用しなかった理由を説明しています。