Papers Skill turns a coding agent into a literature-research assistant. It
orchestrates a bundled Python CLI (scripts/papers.py) that hits the free
Semantic Scholar and arXiv APIs, downloads arXiv PDFs, and extracts text with
PyMuPDF. The agent decides which subcommand to invoke and how to combine
results into a literature scan, a deep read of one paper, an impact analysis,
or a reading list.
This skill is the Skill-mode port of the
papers-mcp MCP server by the same
author. Both projects share the same feature set; this one ships as a
Claude Code plugin so it can be installed with a single command and needs no
long-running MCP process.
wants metadata, the abstract, the TL;DR, or its reference list.
analysis, follow-up tracking).
publisher paywalls; it can only fetch arXiv PDFs and metadata everywhere.
scanned image-PDFs return the fallback message and need a separate OCR step.
is request-driven.
Three Python packages are required. The skill should check once per session,
using the same interpreter to import-check and install so the dependency
check and install target stay in sync:
python -c "import httpx, arxiv, fitz" 2>&1 || python -m pip install httpx arxiv PyMuPDF
If python is not on PATH, fall back to py (Windows launcher) or the
absolute interpreter path — and remember to invoke pip via the same
interpreter, e.g. py -m pip install httpx arxiv PyMuPDF.
The script lives at ${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py
and is bundled with this skill (no separate install needed). Always quote the
path so it survives spaces.
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" <subcommand> [args]
| Subcommand | Purpose | Example |
|---|---|---|
search <query> [--limit N] | Semantic Scholar search, max 20 | search "diffusion models" --limit 5 |
detail <paper_id> | Full metadata, TL;DR, top references | detail 10.48550/arXiv.2310.06825 |
citations <paper_id> [--limit N] | Papers citing this one, max 20 | citations <id> --limit 15 |
arxiv <query> [--max-results N] | arXiv preprint search, max 10 | arxiv "RLHF" --max-results 5 |
download <arxiv_id> [--save-dir D] | Save PDF locally | download 2310.06825 --save-dir ./pdfs |
read <pdf_path> [--max-pages N] | Extract PDF text via PyMuPDF | read ./pdfs/foo.pdf --max-pages 20 |
detail and citations auto-detect the ID type: DOIs starting with 10.
are used as-is, bare numeric IDs of 10+ digits are treated as arXiv IDs, and
long hex strings are treated as Semantic Scholar paperIds.
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" search "retrieval augmented generation" --limit 10
Present results as a ranked table with # | Title | Year | Citations | ID,
then ask the user which papers to dig into.
# 1. Confirm match
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" detail 2005.11401
# 2. Download
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" download 2005.11401 --save-dir ./pdfs
# 3. Extract abstract + intro + conclusion
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" read ./pdfs/2005.11401v4.RAG.pdf --max-pages 10
Summarize as: problem · method · key result · limitations.
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" detail 10.48550/arXiv.2005.11401
python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" citations 10.48550/arXiv.2005.11401 --limit 20
Cluster the citing papers by year/theme and highlight the most-cited
follow-ups.
detail before download to confirm the paper matches userintent. Skipping this leads to wrong PDFs being fetched.
can re-query precisely.
[FirstAuthor et al., Year] *Title* (cites: N).don't pile on parallel queries.
--max-pages to 100+ without warning the user — it canconsume a large amount of context.
Springer, Wiley, etc.). It can only read open arXiv PDFs.
fallback message PDF无法提取文本(可能是扫描件); offer the user an
alternative version or note that OCR is required.
retries 3× with exponential backoff; persistent 429s during heavy use
surface as 搜索失败: rate limit, retries exhausted.
expert review. Stop and ask for clarification if required inputs are
missing.
api.semanticscholar.org andarxiv.org (and the arXiv-listed mirror for the bundled arxiv package).
No authentication tokens are sent.
download writes a PDF to the directory the user specifies (default: thecurrent working directory). Confirm the save path with the user before
downloading to an unexpected location.
read opens a local PDF file with PyMuPDF — make sure the path the usersupplies is one they trust.
需要安装 arxiv: pip install arxiv or 需要安装 PyMuPDF: pip install PyMuPDF.Solution: The script returns this friendly message instead of crashing
when an optional dependency is missing. Offer to run the install command.
搜索失败: rate limit, retries exhausted from search ordetail or citations.
Solution: Semantic Scholar is rate-limiting. Wait ~10 seconds and
retry once. For repeated runs, fall back to arxiv for arXiv-indexed work.
download fails with 找不到 arXiv ID: ….Solution: The user gave a non-arXiv ID (likely a DOI for a non-arXiv
paper). Use detail to inspect; only papers with an externalIds.ArXiv
field can be downloaded.
Solution: The script already forces UTF-8 stdout. If the host
terminal is still misconfigured, set PYTHONIOENCODING=utf-8 in the
shell environment.