/paper-search-pro

name: paper-search-pro
description: "Find academic papers across up to 8 sources (OpenAlex / Semantic Scholar / CrossRef / PubMed / arXiv for English, OpenReview for AI venues, plus native-Chinese retrieval via NSSD 国家哲社文献中心 + yiigle 中华医学期刊) with adjustable depth — Quick scan (5 min) to Audit prep (3 hr). Use when the user wants to find papers, run a literature search, gather references, scope a research topic, search Chinese-language / 中文原生 literature (中文文献/中文核心/CSSCI/C刊/国内研究/国内文献/中华××期刊/心理学报/经济研究), or filter results by journal tier (中科院分区/一区/几区, Q1, JCR/SJR quartile, 影响因子/impact factor, 期刊分区, 顶刊/top journal, '按分区筛'), or export paste-ready professional search strategies / 检索式 for external databases (PubMed / WOS / Scopus / Embase / 知网 CNKI / 万方 / SinoMed — '写检索式', '导出检索式', 'WOS 检索式', '知网专业检索', 'search strategy', 'boolean search strategy'). Triggers on search verbs ('find papers', 'literature search', 'papers about X'), review types ('scoping review', 'systematic review', 'SR prep', 'literature review', 'lit review', 'help me write a lit review'), Chinese ('找文献', '找论文', '论文搜索', '学术检索', '文献检索', '文献综述', '综述前期', '求文献', '中文文献', '中文核心', 'CSSCI', 'C刊', '国内研究', '找中文的'). Outputs Shadcn HTML report + BibTeX/RIS/CSV + PRISMA-S log. Do NOT use for: concept explanations ('what is X' / 'X 是什么', e.g. '影响因子怎么算'), writing ('帮我写' / 'help me write a paragraph'), single-paper interpretation or PDF download with metadata (use paper-downloader-portable), or when the user already has a literature set (use literature-set-review)."
license: Apache-2.0
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
metadata:
  author: Bo
  version: 2.5.0
  vendored-from: futurehouse/paper-qa (Apache 2.0)

paper-search-pro

Multi-source literature search with adjustable depth. Four tiers, five data sources orchestrated by you (the main agent). Python helpers handle deterministic work; LLM classification is delegated to parallel Inline SubAgents — no external API key required.

When to use this skill

• User wants to find academic papers / 找文献 / 论文搜索
• User is preparing a literature review, systematic review (SR), scoping review, or meta-analysis
• User wants to scope research on a topic for a thesis / proposal / coursework / news story
• User asks "what research exists on X" / "find me papers about Y"
• User uploads a query that suggests literature gathering (PICO, SPIDER, MeSH, RCT, etc.)

When NOT to use

• User wants to **read** a specific paper (use PDF reader / download tool)
• User wants to **summarize** a single known paper (use a summarizer)
• User wants to **download** PDFs given DOIs (use `paper-downloader-portable`)
• User already has a literature set and wants to write a review (use `literature-set-review` / `factor-outcome-review`)
• User wants concept explanation, not papers ("what is prospect theory" → just answer)

---

🤖 Called by another agent / headless mode

**If you are an agent driving this Skill for your own reasoning (not for a human who wants an HTML report)**, do NOT hand-run the 14-STEP recipe below. There is a single structured-data channel built for you:

PYTHONPATH=$PSP_HOME python3 -m scripts.agent_search "<query>" > result.json

One command runs the whole deterministic core — multi-strategy retrieve → dedup → heuristic relevance score (computed for every paper) → saturation signal → quota snapshot → per-paper journal metric — and prints **one JSON envelope** (no HTML, no PRISMA, no LLM classification SubAgent). The human path below is unaffected. That command gives you a deterministic **floor**, not the finished job — agent mode is *not* meant to stop at the machine output; `references/agent_mode.md` is where you layer your own semantic judgement on top to reach human-recipe quality (the command guarantees the floor; you supply the quality).

📖 **Read `references/agent_mode.md`** for the full envelope schema, every flag (`--verify`, `--min-relevance`, `--quartile`, `--min-impact`, …), the relevance formula, error codes / exit codes, and source selection. This is the SSOT for agent callers — everything else in this section is just the pointer to it.

Everything from here down is the **human-facing 14-STEP recipe** (HTML report + exports). Use it when the consumer is a person.

---

🔥 Execution discipline (read before running anything)

Four invariants govern every step — ignoring them is the dominant failure mode in real sessions:

• **A — NEVER `cd` into the Skill directory.** `cd $PSP_HOME` rebinds `./` to the Skill asset folder, so `./paper-search-results/...` lands inside the Skill instead of the user's workspace (and a re-install wipes it). Run every helper from the user's PWD: `PYTHONPATH=$PSP_HOME python3 -m scripts.<name> … > "$SEARCH_DIR/..."`. `$PSP_HOME` (STEP 0) is the install dir; `$SEARCH_DIR` (STEP 0) is an absolute path under the user's PWD.
• **B — Dispatch classifier SubAgents in parallel.** STEP 6 puts up to 5 `Task` blocks in one assistant message; serial dispatch inflates Standard tier from ~10 to ~17 min. The worked example lives in STEP 6 — it is not repeated elsewhere.
• **C — Announce every skip.** If you skip a STEP (budget / empty data / user choice), say *what* you skipped, *why*, *what's lost*, and *how to recover* (e.g. "re-run at `--tier deep`"). Skipping is fine; surprising the user is not.
• **D — Read a step's cited reference when that step is non-trivial for this case.** Each STEP names a `references/<file>.md` carrying edge cases not duplicated here. You won't read all of them every run, nor should you — but skipping the reference for a step you are *actually about to run* is where boundary knowledge (dict-vs-list shapes, enrich-not-search, DOI casing) gets lost. Read the one in front of you.

---

Architecture at a glance

You (main agent) drive the workflow per this SKILL.md.
Python helpers do deterministic work — NO LLM inside, NO external API key.

  L1 OpenAlex (primary)  → deep top-100 multi-strategy
  L2