research-lit skill

Research Literature Review

Research topic: $ARGUMENTS

Constants

• PAPERLIBRARY** — Local directory containing user's paper collection (PDFs). Check these paths in order:

1. papers/ in the current project directory
2. literature/ in the current project directory
3. Custom path specified by user in CLAUDE.md under ## Paper Library

• MAXLOCALPAPERS = 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, gemini, openalex, all. Full source table and selection rules: see ## Data Sources below.
• ARXIVDOWNLOAD = false — When true, download top 3-5 most relevant arXiv PDFs to PAPERLIBRARY after search. When false (default), only fetch metadata (title, abstract, authors) via arXiv API — no files are downloaded.
• ARXIVMAXDOWNLOAD = 5 — Maximum number of PDFs to download when ARXIV_DOWNLOAD = true.

💡 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 (IEEE, ACM, etc.)

- /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. All are optional — if a source is not configured or not requested, skip it silently.

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, gemini, openalex, all.
• If not specified: Default to all — search every available source in priority order (semantic-scholar, deepxiv, exa, gemini, and openalex are excluded from all; they must be explicitly listed).

Examples:

/research-lit "diffusion models"                                    → all (default, no S2)
/research-lit "diffusion models" — sources: all                     → all (default, no S2)
/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 + S2 API (IEEE/ACM venue papers)
/research-lit "topic" — sources: deepxiv                            → DeepXiv only
/research-lit "topic" — sources: all, deepxiv                       → default sources + DeepXiv
/research-lit "topic" — sources: all, semantic-scholar              → all + S2 API
/research-lit "topic" — sources: exa                               → Exa only (broad web + content extraction)
/research-lit "topic" — sources: all, exa                          → default sources + Exa web search
/research-lit "topic" — sources: gemini                            → Gemini only (AI-powered broad disc

Source Table

Graceful degradation: If no MCP servers are configured, the skill works exactly as before (local PDFs + web search). Zotero and Obsidian are pure additions.

Workflow

Step 0a: Search Zotero Library (if available)

Skip this step entirely if Zotero MCP is not configured.

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:

• Title, authors, year, venue
• User's annotations/highlights (if any)
• Tags the user assigned
• 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)

Skip this step entirely if Obsidian MCP is not configured.

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:

• Note title and path
• User's summary/insights
• Links to other notes (research graph)
• 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 MAXLOCALPAPERS):

• Read first 3 pages (title, abstract, intro)
• Extract: title, authors, year, core contribution, relevance to topic
• Flag papers that are directly related vs tangentially related

1. Build local knowledge base: Compile summaries into a "papers you already have" section. This becomes the starting point — external search fills the gaps.

📚 If the user has a comprehensive local collection, the external search can be more targeted (focus on what's missing).

⚠️ If all three PAPERLIBRARY paths miss, say so before moving on** — do not skip silently. A user whose PDFs live in a reference manager (Zotero, Mendeley, ...) otherwise assumes — sources: all covered them. Emit:

WARN: local contributed nothing — no PDFs found in papers/, literature/, or a configured paper library. To include yours, add a "## Paper Library" heading to CLAUDE.md followed by the directory path.

Then continue to Step 1.

Step 1: Search (external)

• Use WebSearch to find recent papers on the topic
• Check arXiv, Semantic Scholar, Google Scholar
• Focus on papers from last 2 years unless studying foundational work
• De-duplicate: Skip papers already found in Zotero, Obsidian, or local library

arXiv API search (runs when — sources: is unset, contains web or all; no download by default — arXiv API is part of the Priority-4 Web tier, see Source Table above):

Policy D2 tracking discipline (orchestrator-managed): the executor (you, the LLM) maintains an in-context list of contributing sources. For helper-backed bash sources (arxiv, semantic-scholar, deepxiv, exa, openalex), a source contributes iff its bash block ran its helper successfully (helper resolved AND invocation exited 0; note: the helper exiting 0 with an empty result list still counts as "ran" — downstream relevance ranking is what decides whether the user actually sees content). For non-helper sources (zotero / obsidian / local PDF / WebSearch / Gemini), the contribution rule is stated in the Step-1 finalization block below — these are tracked separately because they don't emit D2 contribution: log lines from bash. Sources that were not requested via — sources: do not count. At the end of Step 1 (before "Optional PDF download"), if zero sources contributed, surface a D2 empty-aggregate error and stop. (See integration-contract.md §2 Policy D2 — the in-context tracking replaces a shared bash accumulator because SKILL bash blocks are executed as separate shells; state does not survive.)

Resolve $ARXIV_FETCHER via the canonical chain (Policy D2 — this source contributes to the multi-source aggregate; warn-and-continue on failure, never abort the whole aggregate):

# Canonical strict-safe resolver (see shared-references/integration-contract.md §2).
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
ARXIV_FETCHER=".aris/tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER="tools/arxiv_fetch.py"
[ -f "$ARXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"; }
[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER=""

if [ -n "$ARXIV_FETCHER" ]; then
  # Search arXiv API for structured results (title, abstract, authors, categories).
  # Wrap with if/then/else so set -e doesn't abort the SKILL.
  if python3 "$ARXIV_FETCHER" search "QUERY" --max 10; then
    echo "D2 contribution: arxiv (helper invocation exit 0)" >&2
  else
    echo "WARN: arxiv_fetch.py invocation failed; D2 aggregate continues with WebSearch results." >&2
  fi
else
  echo "WARN: arxiv_fetch.py not resolved; falling back to 

Record-keeping: track the D2 contribution: … lines emitted by

each source's bash block. They form the contributing-source list

the orchestrator uses for the Step-1 finalization gate below.

WebSearch (Priority 4) is treated as having contributed iff

WebSearch was requested (no — sources: filter, or the list