research-lit

Research Literature Review

Research topic: $ARGUMENTS

Constants

• PAPER_LIBRARY — Local directory containing user's paper collection (PDFs). Check these paths in order:
• papers/ in the current project directory
• literature/ in the current project directory
• Custom path specified by user in AGENTS.md under ## Paper Library
• MAX_LOCAL_PAPERS = 20 — Maximum number of local PDFs to scan (read first 3 pages each). If more are found, prioritize by filename relevance to the topic.
• SOURCES = all — Which literature sources to search. Options: zotero, obsidian, local, web, semantic-scholar, deepxiv, exa, all. Full source table and selection rules: see ## Data Sources below.
• ARXIV_DOWNLOAD = false — When true, download top 3-5 most relevant arXiv PDFs to PAPER_LIBRARY after search. When false (default), only fetch metadata (title, abstract, authors) via arXiv API — no files are downloaded.
• ARXIV_MAX_DOWNLOAD = 5 — Maximum number of PDFs to download when ARXIV_DOWNLOAD = true.
• REVIEWER_BACKEND = codex — Default reviewer route for optional literature synthesis cross-checks. Use --reviewer: oracle-pro only when explicitly requested; if Oracle is unavailable, warn and continue with Codex xhigh or local synthesis.

💡 Overrides:

- /research-lit "topic" — paper library: ~/my_papers/ — custom local PDF path

- /research-lit "topic" — sources: zotero, local — only search Zotero + local PDFs

- /research-lit "topic" — sources: web — only search the web (skip all local)

- /research-lit "topic" — sources: web, semantic-scholar — also search Semantic Scholar for published venue papers

- /research-lit "topic" — sources: all, deepxiv — use default sources plus DeepXiv

- /research-lit "topic" — arxiv download: true — download top relevant arXiv PDFs

- /research-lit "topic" — arxiv download: true, max download: 10 — download up to 10 PDFs

Data Sources

This skill checks multiple sources in priority order.

Source Selection

Parse $ARGUMENTS for a — sources: directive:

• If — sources: is specified: Only search the listed sources (comma-separated). Valid values: zotero, obsidian, local, web, semantic-scholar, deepxiv, exa, all.
• If not specified: Default to all — search every available source in priority order (semantic-scholar, deepxiv, and exa are excluded from all; they must be explicitly listed).

Examples:

/research-lit "diffusion models"                        → all (default)
/research-lit "diffusion models" — sources: all         → all
/research-lit "diffusion models" — sources: zotero      → Zotero only
/research-lit "diffusion models" — sources: zotero, web → Zotero + web
/research-lit "diffusion models" — sources: local       → local PDFs only
/research-lit "topic" — sources: obsidian, local, web   → skip Zotero
/research-lit "topic" — sources: web, semantic-scholar  → web + Semantic Scholar API
/research-lit "topic" — sources: deepxiv                → DeepXiv only
/research-lit "topic" — sources: all, deepxiv           → default sources + DeepXiv
/research-lit "topic" — sources: all, semantic-scholar  → default sources + Semantic Scholar API
/research-lit "topic" — sources: exa                    → Exa only (broad web + content extraction)
/research-lit "topic" — sources: all, exa               → default sources + Exa web search

Source Table

| Priority | Source | ID | How to detect | What it provides | |----------|--------|----|---------------|-----------------| | 1 | Zotero (via MCP) | zotero | Try calling any mcp__zotero__* tool — if unavailable, skip | Collections, tags, annotations, PDF highlights, BibTeX, semantic search | | 2 | Obsidian (via MCP) | obsidian | Try calling any mcp__obsidian-vault__* tool — if unavailable, skip | Research notes, paper summaries, tagged references, wikilinks | | 3 | Local PDFs | local | Glob: papers/**/*.pdf, literature/**/*.pdf | Raw PDF content (first 3 pages) | | 4 | Web search | web | Always available (WebSearch) | arXiv, Semantic Scholar, Google Scholar | | 5 | Semantic Scholar API | semantic-scholar | $S2_FETCHER resolves (canonical name semantic_scholar_fetch.py, per integration-contract §2 Codex chain) | Published venue papers (IEEE, ACM, Springer) with structured metadata: citation counts, venue info, TLDR. Only runs when explicitly requested | | 6 | DeepXiv CLI | deepxiv | $DEEPXIV_FETCHER resolves (canonical name deepxiv_fetch.py, per integration-contract §2) and deepxiv CLI present | Progressive paper retrieval: search, brief, head, section, trending, web search. Only runs when explicitly requested | | 7 | Exa Search | exa | $EXA_FETCHER resolves (canonical name exa_search.py, per integration-contract §2); fetcher handles exa-py SDK + API key internally | AI-powered broad web search with content extraction (highlights, text, summaries). Covers blogs, docs, news, companies, and research papers beyond arXiv/S2. Only runs when explicitly requested |

If the user explicitly requests Zotero or Obsidian and that source is not configured, stop and tell the user how to enable it. Only sources that were not requested may be skipped silently.

Workflow

Step 0a: Search Zotero Library (if available)

If the user explicitly requested Zotero and the Zotero MCP is not configured, stop and ask the user to configure it. Otherwise skip this step entirely.

Try calling a Zotero MCP tool (e.g., search). If it succeeds:

1. Search by topic: Use the Zotero search tool to find papers matching the research topic
2. Read collections: Check if the user has a relevant collection/folder for this topic
3. Extract annotations: For highly relevant papers, pull PDF highlights and notes — these represent what the user found important
4. Export BibTeX: Get citation data for relevant papers (useful for /paper-write later)
5. Compile results: For each relevant Zotero entry, extract:
6. Title, authors, year, venue
7. User's annotations/highlights (if any)
8. Tags the user assigned
9. Which collection it belongs to

📚 Zotero annotations are gold — they show what the user personally highlighted as important, which is far more valuable than generic summaries.

Step 0b: Search Obsidian Vault (if available)

If the user explicitly requested Obsidian and the Obsidian MCP is not configured, stop and ask the user to configure it. Otherwise skip this step entirely.

Try calling an Obsidian MCP tool (e.g., search). If it succeeds:

1. Search vault: Search for notes related to the research topic
2. Check tags: Look for notes tagged with relevant topics (e.g., #diffusion-models, #paper-review)
3. Read research notes: For relevant notes, extract the user's own summaries and insights
4. Follow links: If notes link to other relevant notes (wikilinks), follow them for additional context
5. Compile results: For each relevant note:
6. Note title and path
7. User's summary/insights
8. Links to other notes (research graph)
9. Any frontmatter metadata (paper URL, status, rating)

📝 Obsidian notes represent the user's processed understanding — more valuable than raw paper content for understanding their perspective.

Step 0c: Scan Local Paper Library

Before searching online, check if the user already has relevant papers locally:

1. Locate library: Check PAPER_LIBRARY paths for PDF files

`` Glob: papers/**/*.pdf, literature/**/*.pdf ``

1. De-duplicate against Zotero: If Step 0a found papers, skip any local PDFs already covered by Zotero results (match by filename or title).

1. Filter by relevance: Match filenames and first-page content against the research topic. Skip clearly unrelated papers.

1. Summarize relevant papers: For each relevant local PDF (up to MAX_LOCAL_PAPERS):
2. Read fir