literature-search

文献検索（共有ツールチェーン）

このスキルはループではありません。複数のループが論文の発見や新規性の確認に利用する、文献検索の依存機能です。標準ライブラリのみで動作するエントリーポイントtools/lit_search.pyと、tools/lit/パッケージをまとめています。Semantic Scholar（S2）によるセマンティック検索、スニペット、引用グラフ、および全文読み取り用のarXiv（キー不要のコア機能）に加え、キーが設定されている場合はオプションでOpenAlex、Perplexity Sonar（ask）、bgpt.pro（bgpt）も利用できます。各サブコマンドはJSONを出力します。ターミナルでエラーが発生した場合は{"error","fallback"}を出力してゼロ以外の終了コードで終了するため、呼び出し元は組み込みのWebSearch/WebFetchにフォールバックできます。インストール不要、Python ≥3.9。

ループでの使い方

この機能を利用するループは、セットアップ時に以下を一度解決し、以降は再利用します。

• <lit_skill_dir> — このスキルのインストール先です。cp -r loops/* ~/.claude/skills/を実行した場合、呼び出し元のループと同じ階層に配置されます。たとえば~/.claude/skills/literature-search/です（ホスト環境に合わせて調整してください）。解決できない場合、呼び出し元はWebSearch/WebFetchにフォールバックします。このスキルへの依存によってループが完全に停止することはなく、機能が補強されるだけです。
• <lit> — 文献CLIを単一のコマンドトークンとして指定します。<lit_skill_dir>/tools/lit_search.pyです。エントリーポイントには実行権限があり、#!/usr/bin/env python3のシバンも含まれているため、python3を前置せずに直接実行できます。呼び出し間でキャッシュを再利用するには、--cache-dir <sandbox_root>/literature/.cacheをサブコマンドの後ろに追加します（グローバルオプションではなく、サブコマンドごとのオプションです）。
• <lit_py> — 実行権限を尊重しないホストで、フォールバック形式を使う場合にのみ必要です。<lit_py> <lit_skill_dir>/tools/lit_search.pyの形式で、<lit_py> = python3（任意の≥3.9インタープリター）とします。

<lit>は単一のコマンドとして呼び出し、シェルトークンを1つにしてください。 特に、zshでは引用符で囲まれていない変数は単語分割されません。そのため、python3 .../lit_search.pyの2語を変数に格納して$VARを呼び出すと、1つの長い（存在しない）ファイル名を実行しようとします。上記の実行可能な単一トークン形式を使うか、スクリプトのパスを直接呼び出すか、明示的に分割してください（zshでは${=VAR}）。

サブコマンド

サブコマンド	用途
<lit> search "<q>" [--year 2020-] [--min-citations N] [--limit N] [--source s2|openalex|both] [--sort relevance|citations|recent]	セマンティック検索 — 関連論文（タイトル、TLDR、要約、引用数、arxiv_id）。デフォルトは--source s2（関連度順）です。検索範囲を広げるにはopenalexまたはbothを追加します
<lit> snippet "<q>" [--limit N]	全文の一節を検索 — 論文を読まずに、事実や数値を原文のまま特定できます
<lit> cite <paperId> --direction references|citations|recommend	引用グラフをたどります（過去の文献／後続の文献／「類似論文」）
<lit> fulltext <arxivId> [--mode auto|latex|pdf]	1本の論文の手法や結果を詳しく読みます（HTML > LaTeX > PDF）
<lit> ask "<question>" [--model sonar|sonar-pro|sonar-reasoning]	Perplexity Sonarによる統合 — 出典付きの概説回答です（OPENROUTER_API_KEYが必要です。ない場合はWebSearchを使用してください）
<lit> bgpt "<q>" [--num N] [--days-back N]	bgpt.proによる実験結果／制限事項の構造化抽出（50件までは無料、その後はBGPT_API_KEYが必要です）
<lit> keys [--init]	APIキーの設定状況を報告します（真偽値のみ）。--initを指定するとkeys.envを作成または拡張します

S2とarXivのコア機能（search／snippet／cite／fulltext）にはキーは不要です。オプション機能（search --source openalex|both、ask、bgpt）は、キーが設定されている場合に検索範囲と統合機能を拡張します。

API キー（共有規約 — 任意、利用を妨げない）

このスキルは、プロジェクトのキー規約の正式な管理場所です（この規約を実装するコードがインストールされています）。キーはプロジェクトルートにある、Git で無視される 1 つの keys.env（作業ディレクトリから最も近い .git の祖先。該当するものがなければ CWD）に保存し、プロジェクト内のすべてのスキルで共有します。

• KEY=VALUE の形式の行。# コメント。空行は無視されます。パーミッションは 0600 です。
• 実際の OS 環境変数は常にファイルの値より優先されます（CI／上級ユーザーは export するだけで使えます）。
• すべてのキーは任意です — キーがない場合、その機能だけが WebSearch まで段階的に無効化されます。
• シークレットが会話に入ることはありません — ユーザー自身が keys.env を編集します。スキルが読み取るのはキーの有無を示す真偽値のみで、値は読み取りません。

オンボーディングの流れ：<lit> keys（設定済みのキーを報告）→ <lit> keys --init（スロットを作成／追加。追記のみで、上書きはしません。パスを表示します）→ ユーザーが keys.env を開き、必要なキーを貼り付ける（セッション内では ! $EDITOR ./keys.env）→ <lit> keys をもう一度実行してから続行します。キーがなくても利用を妨げてはいけません。

• S2_API_KEY（無料）— 設定する価値が最も高いキーです。search／snippet／cite に専用の 1 req/s が割り当てられます。
• OPENALEX_EMAIL（無料、任意のメールアドレス）— OpenAlex の「polite pool」を利用でき、--source openalex|both が高速になります。
• OPENROUTER_API_KEY（有料）— ask（Perplexity Sonar）が有効になります。設定しない場合、ask は無効です。
• BGPT_API_KEY（50 件までは無料。その後は有料）— 無料枠を超えて bgpt が利用可能になります。

制約

• 標準ライブラリのみ — 依存関係を追加したり、インストール済みであると想定したりしてはいけません。python3 だけで実行できる必要があります。
• 自己完結型 — すべてをこのフォルダー内に置きます。../ によるフォルダー外への参照や docs/ へのリンクは禁止です。
• フォールバックにフォールクローズする — ソースでエラーが発生した場合は、例外を発生させるのではなく {"error","fallback"} を出力してゼロ以外のコードで終了し、呼び出し元が適切にフォールバックできるようにします。