read-research-paper

研究論文を読む

他の2つのスキルが行うこと：

スキル	機能
get-research-paper	トピックに関する実在する論文を検索します
research-paper	新しい論文を執筆します
read-research-paper（このスキル）	論文を1本読み、興味深く紹介します

URL、arXiv ID、DOI、または貼り付けたテキストを渡してください。視覚的で、 複数の層からなる形式で出力します。技術的な深掘り＋平易な英語＋マインドマップ＋ 手法のフローチャート＋主要な発見のインフォグラフィック＋比較表＋ 関連研究のタイムラインを含みます。

このファイルはエントリーポイントです。より詳しいガイダンスはトピック フォルダーにあり、必要に応じて読み込まれます。

---

1. 起動するタイミング

スラッシュコマンド

コマンド	機能
/read-research-paper <input>	視覚的な形式で完全に出力します（デフォルト）
/read-paper <input>	エイリアス
/explain-paper <input>	同じ内容を、平易な英語の解説を追加して出力します
/visualize-paper <input>	同じ内容を、文章よりも視覚表現を重視して出力します
/tldr-paper <input>	1ページのインフォグラフィック要約のみを出力します

<input> には次のいずれかを指定できます：

• URL：https://arxiv.org/abs/2403.01234、https://doi.org/...、 https://example.com/paper.pdf、ジャーナルのランディングページなど
• arXiv ID：2403.01234 または cs.LG/0701002
• DOI：10.1145/3589334
• 貼り付けたテキスト：論文の要旨または全文
• ローカルファイル：サポートされる任意の形式（以下を参照）。

サポートされるファイル形式

このスキルは入力として、次のいずれかの形式を読み取ります：

形式	拡張子	使用ライブラリ	常に利用可能？
Markdown	.md、.markdown	stdlib	はい
プレーンテキスト	.txt	stdlib	はい
LaTeX	.tex、.latex	stdlib + regex de-LaTeX	はい
JSON	.json	stdlib	はい
HTML	.html、.htm	beautifulsoup4（または regex）	はい（regex にフォールバック）
CSV / TSV	.csv、.tsv	pandas（または stdlib）	はい（基本機能は stdlib で利用可能）
RTF	.rtf	striprtf（または regex）	はい（regex にフォールバック）
PDF	.pdf	pdfplumber / pypdf	いずれかをインストール
DOCX	.docx	python-docx	インストールが必要
PPTX	.pptx	python-pptx	インストールが必要
XLSX	.xlsx、.xls	pandas + openpyxl	インストールが必要
EPUB	.epub	ebooklib	インストールが必要
画像	.png、.jpg、.tiff、.bmp	pytesseract + PIL	インストールが必要（OCR）

すべてを一度にインストールするコマンド：

pip install pdfplumber python-docx python-pptx pandas openpyxl \
            beautifulsoup4 striprtf ebooklib pytesseract Pillow

（画像を使う場合は、Tesseract OCR もシステム全体にインストールしてください。）

リーダーは toolchains/read_any_file.py です。セルフテスト：

python toolchains/read_any_file.py --self-test
python toolchains/read_any_file.py --list-formats

完全なリファレンス：sources/file-formats.md。

共通オプション

オプション	デフォルト	効果
--depth	standard	quick / standard / deep
--audience	mixed	academic / technical / general / mixed
--visuals	auto	auto / max / minimal / none
--include-figures	true	論文独自の図を抽出／再作成します
--cache	true	ローカルキャッシュを使用します（再度依頼された場合は自動入力）
--language	en	平易な英語で出力します
--out	./<paper-slug>/	作業ディレクトリ
--with-related	false	関連研究について get-research-paper を実行します
--with-handoff	false	research-paper 用に bibliography.yaml を出力します

自然言語のパターン

• 「この研究論文を読んで 」
• 「この論文を説明して 」
• 「この論文を図解して 」
• 「この論文を理解したい 」
• 「この論文を要約して 」
• 「この論文を一言でまとめて 」
• 「この論文は何を述べていますか 」

起動しないケース

次の場合は起動しないでください。

• トピックに関する論文を探す依頼（get-research-paper に振り分けます）。
• 新しい論文を書く依頼（research-paper に振り分けます）。
• 論文形式の入力ではない文章の貼り付け（「この記事をどうぞ…」など）。
• 特定の論文に言及していない、あるトピックに関する気軽な質問。

---

2. 出力仕様

実行するたびに、次のものが生成されます。

1. paper-visual.md — 中心となる成果物です。複数の層で構成されます。
   • 冒頭に1ページのインフォグラフィック（マインドマップ＋主要な数値）。
   • 5～8文のTL;DR。
   • 5～10文の平易な英語での要約。
   • セクションごとの解説。各セクションの冒頭に、平易な英語での1段落の説明を置き、その後に抽出／生成したビジュアルを含む技術的な内容を続けます。
   • 手法のフローチャート（Mermaid）。
   • 主な調査結果のインフォグラフィック（論文の主要な数値を示すグラフ）。
   • ベースラインとの比較表（該当する場合）。
   • 関連研究のタイムライン（参考文献が利用できる場合）。
   • 「これが重要な理由」のフッター。
2. paper-data.json — タイトル、著者、年、要旨、セクション、図、表、主要な数値、参考文献を含む、抽出したメタデータの構造化データです。スキーマは schemas/visual-paper.json にあります。
3. figures/ — 生成されたグラフ／図／マインドマップを、PNG、SVG、Mermaid のソースとして格納します。
4. cache/<paper-id>.json — 再利用用のキャッシュです。
5. Known-gaps.md — 取得／解析できなかった項目を記録します。

--with-handoff が設定されている場合は、research-paper スキルですぐに使える bibliography.yaml も生成されます。

--with-related が設定されている場合、オーケストレーターは論文の主要なトピックについて get-research-paper を実行し、関連研究のセクションの準備を行います。

---

3. 運用原則

0. 今日の日付を基準にします。 入力が特定の URL／DOI／パスではなく、トピック形式のクエリの場合は、まず今日の実際の日付を確認します（date -u +%Y-%m-%d、実行時のコンテキスト、またはユーザーへの確認を利用します）。特定の論文が入力された場合は、鮮度チェックで論文の発表日と今日の日付を比較し、古い知見にフラグを付けます。プロトコルの全文は instructions/freshness.md にあります。
1. ごまかしません。 URL にアクセスできない場合や PDF を解析できない場合は、その旨を伝えます。[FETCH FAILED — fallback to cache | model knowledge | corpus] を付けて、Known-gaps.md に記載します。
2. すべてをキャッシュします。 取得に成功した論文はすべて ~/.agents/skills/read-research-paper/cache/ に保存されます。再度質問された場合は、すぐに回答できます。
3. コーパスを同梱します。 トピック形式のクエリが入力された場合は、正典となる論文を集めた小規模なコーパス（corpus/anchor-papers.yaml）を最初に検索します。
4. ビジュアルを標準にします。 最低限、マインドマップ 1 点、手法のフローチャート 1 点、主な知見の図 1 点、比較表 1 点を生成します。
5. 二つの表現レベルを用意します。 すべてのセクションに、平易な英語の内容と技術的な内容の両方を含めます。技術的な深さを削ることはせず、より簡単な表現を併記します。
6. 解釈を誠実に伝えます。 知見を誇張しません。論文自体が示す確実性の度合いに合わせます。論文が断定を避けている場合は、論文のビジュアルでも断定を避けます。

---

4. トップレベルのワークフロー

intake → fetch → parse → extract-figures-and-data →
plan-visuals → render → assemble → cache → output

各フェーズには、それぞれ専用のプレイブックがあります。パイプラインの概要は workflows/ingestion.md を参照してください。

---

5. ソースの検出

このスキルは入力の種類を自動で検出します。

入力パターン	パス
arxiv.org/abs/...	arXiv API
\d{4}\.\d{4,5} (bare arXiv ID)	arXiv API
doi.org/... or 10\..../...	Crossref → URL → fetch
*.pdf (URL or local path)	PDF extraction
Journal landing page URL	URL scrape + Crossref enrichment
Pasted text (no URL)	Treat as paper body; build structure heuristically

workflows/ingestion.md §1 を参照してください。

---

6. 三段階のフォールバック

1. Local cache (~/.agents/skills/read-research-paper/cache/)
   ├── Hit  → return immediately (instant)
   └── Miss → next tier

2. Live fetch (arXiv API / Crossref / WebFetch / PDF parser)
   ├── Success → render + cache
   └── Fail    → next tier

3. Bundled corpus (corpus/anchor-papers.yaml)
   ├── Hit  → return + flag as "from bundled corpus"
   └── Miss → next tier

4. Model knowledge
   ├── Confident → render + flag every fact [UNVERIFIED — offline]
   └── Not confident → fail honestly with a Known-gaps entry

表示された論文がどこから取得されたものかユーザーが把握できるよう、段階を移行するたびに Known-gaps.md に記録します。

---

7. ビジュアルのレンダリング計画

すべての論文について、このスキルは次のものを生成します。

ビジュアル	ソース	レンダラー
マインドマップ	論文の構成（セクションと主要なアイデア）	Mermaid mindmap
手法のフローチャート	手法のセクション	Mermaid flowchart
主な知見のインフォグラフィック	結果の見出しとなる数値	利用可能な場合は matplotlib、そうでなければ Markdown テーブル
比較表	論文独自のベンチマーク表	Markdown テーブル
関連研究のタイムライン	参考文献とその発表年	Mermaid gantt 形式のタイムライン
著者ネットワーク	著者と所属機関	Mermaid flowchart（小規模）
概念マップ	論文の用語	Mermaid mindmap
図のキャプション再作成	元の図（抽出可能な場合）	新しいキャプションを付けてそのまま利用

判断ロジックについては、workflows/visualization.md を参照してください。

---

8. キャッシュのアーキテクチャ

キャッシュの保存先：

~/.agents/skills/read-research-paper/cache/
├── manifest.json              # index of all cached papers
├── arxiv/
│   ├── 2403.01234.json
│   └── 2005.11401.json
├── doi/
│   ├── 10.1145_3589334.json
│   └── ...
├── url/
│   └── <sha256-hash>.json
└── topics/
    └── <topic-slug>.json      # topic → list of cached paper IDs

ユーザーが特定の論文ではなくトピックについて質問した場合は、オンラインで取得する前に、キャッシュの topics/ インデックスを最初に検索します。

キャッシュのスキーマについては、workflows/caching.md を参照してください。

---

9. 同梱コーパス

corpus/ に含まれています。

• anchor-papers.yaml — 主要なトピック（Transformer、RAG、RLHF、対照学習、RCT の方法論、PRISMA など）を網羅する、影響力の大きい代表的な論文を約 30 件収録しています。
• topics-index.yaml — トピックのキーワードと代表論文を対応付けています。

ユーザーがコーパスに収録されている論文を尋ねた場合、このスキルはコーパス内のバージョンを使用します（オフラインでも常に利用可能です）。ユーザーは corpus/user/ にファイルを追加して、コーパスを拡張できます。

---

10. エラー処理

• URL が解決できない → arXiv ID の抽出、DOI の検索の順に試し、その後 Known-gaps.md に記載します。
• PDF を解析できない → 警告を表示し、要旨のみの形式に切り替えます。
• モデルが図を抽出できない → Mermaid による代替図を生成します。
• 結果に主要な数値がない → 定性的な結果を使用します。
• ウェブツールが利用できない → キャッシュ、コーパス、モデルの知識の順に使用します。

全項目の一覧：workflows/ingestion.md §10。

---

11. 次に確認する場所

• 取り込みを計画する → workflows/ingestion.md
• ビジュアルを選ぶ → workflows/visualization.md
• キャッシュプロトコル → workflows/caching.md
• 平易な英語のレイヤー → prompts/plain-english.md
• マインドマップの生成 → prompts/generate-mindmap.md
• 出力形式 → templates/visual-paper.md
• 同梱コーパス → corpus/
• 取得ツール → toolchains/fetch_paper.py、toolchains/extract_pdf.py

このスキルは他の 2 つのスキルを補完しますが、利用に必須ではありません。

• get-research-paper → 論文を探す
• research-paper → 論文を執筆する
• read-research-paper → 論文を読む（このスキル）