{"slug":"papers-skill","title":"papers-skill","summary":"Skill for academic research workflows: search Semantic Scholar (200M+ papers), inspect citations, download arXiv PDFs, and extract PDF text. Bundles a self-contained Python CLI.","platform":"ChatGPT","tags":["research"],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-17T11:41:31.856149Z","repo":{"url":"https://github.com/sickn33/agentic-awesome-skills","stars":46883,"forks":6831,"license":"MIT","updatedAt":"2026-09-25T05:43:16Z"},"bodyHtml":"<hr>\n<h2>name: papers-skill\ndescription: \"Skill for academic research workflows: search Semantic Scholar (200M+ papers), inspect citations, download arXiv PDFs, and extract PDF text. Bundles a self-contained Python CLI.\"\ncategory: research\nrisk: safe\nsource: community\nsource_repo: xwmxcz/papers-skill\nsource_type: community\ndate_added: \"2026-06-11\"\nauthor: xwmxcz\ntags: [research, academic, papers, citations, arxiv, semantic-scholar, pdf]\ntools: [claude-code, antigravity, cursor, gemini-cli, codex-cli, opencode]\nlicense: \"MIT\"\nlicense_source: \"https://github.com/xwmxcz/papers-skill/blob/main/LICENSE\"</h2>\n<h1>Papers Skill</h1>\n<h2>Overview</h2>\n<p>Papers Skill turns a coding agent into a literature-research assistant. It\norchestrates a bundled Python CLI (<code>scripts/papers.py</code>) that hits the free\nSemantic Scholar and arXiv APIs, downloads arXiv PDFs, and extracts text with\nPyMuPDF. The agent decides which subcommand to invoke and how to combine\nresults into a literature scan, a deep read of one paper, an impact analysis,\nor a reading list.</p>\n<p>This skill is the Skill-mode port of the\n<a href=\"https://github.com/xwmxcz/papers-mcp\">papers-mcp</a> MCP server by the same\nauthor. Both projects share the same feature set; this one ships as a\nClaude Code plugin so it can be installed with a single command and needs no\nlong-running MCP process.</p>\n<h2>When to Use This Skill</h2>\n<ul>\n<li>Use when the user asks to search academic papers by topic, author, or venue.</li>\n<li>Use when the user names a specific paper (by DOI, arXiv ID, or title) and\nwants metadata, the abstract, the TL;DR, or its reference list.</li>\n<li>Use when the user wants to find work that <strong>cites</strong> a known paper (impact\nanalysis, follow-up tracking).</li>\n<li>Use when the user wants to download an arXiv PDF and have it summarized.</li>\n<li>Use when the user asks to build a reading list around a topic.</li>\n</ul>\n<h2>Do Not Use This Skill When</h2>\n<ul>\n<li>The user wants paywalled non-arXiv full text. This skill cannot bypass\npublisher paywalls; it can only fetch arXiv PDFs and metadata everywhere.</li>\n<li>The user wants OCR over scanned PDFs. PyMuPDF extracts embedded text only;\nscanned image-PDFs return the fallback message and need a separate OCR step.</li>\n<li>The user wants real-time citation alerts or RSS-style watching. This skill\nis request-driven.</li>\n</ul>\n<h2>How It Works</h2>\n<h3>Step 1: Verify dependencies</h3>\n<p>Three Python packages are required. The skill should check once per session,\nusing the <strong>same interpreter</strong> to import-check and install so the dependency\ncheck and install target stay in sync:</p>\n<pre><code>python -c \"import httpx, arxiv, fitz\" 2&gt;&amp;1 || python -m pip install httpx arxiv PyMuPDF\n</code></pre>\n<p>If <code>python</code> is not on PATH, fall back to <code>py</code> (Windows launcher) or the\nabsolute interpreter path — and remember to invoke pip via the same\ninterpreter, e.g. <code>py -m pip install httpx arxiv PyMuPDF</code>.</p>\n<h3>Step 2: Invoke the bundled CLI</h3>\n<p>The script lives at <code>${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py</code>\nand is bundled with this skill (no separate install needed). Always quote the\npath so it survives spaces.</p>\n<pre><code>python \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" &lt;subcommand&gt; [args]\n</code></pre>\n<h3>Step 3: Pick the right subcommand</h3>\n<table>\n<thead>\n<tr>\n<th>Subcommand</th>\n<th>Purpose</th>\n<th>Example</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>search &lt;query&gt; [--limit N]</code></td>\n<td>Semantic Scholar search, max 20</td>\n<td><code>search \"diffusion models\" --limit 5</code></td>\n</tr>\n<tr>\n<td><code>detail &lt;paper_id&gt;</code></td>\n<td>Full metadata, TL;DR, top references</td>\n<td><code>detail 10.48550/arXiv.2310.06825</code></td>\n</tr>\n<tr>\n<td><code>citations &lt;paper_id&gt; [--limit N]</code></td>\n<td>Papers citing this one, max 20</td>\n<td><code>citations &lt;id&gt; --limit 15</code></td>\n</tr>\n<tr>\n<td><code>arxiv &lt;query&gt; [--max-results N]</code></td>\n<td>arXiv preprint search, max 10</td>\n<td><code>arxiv \"RLHF\" --max-results 5</code></td>\n</tr>\n<tr>\n<td><code>download &lt;arxiv_id&gt; [--save-dir D]</code></td>\n<td>Save PDF locally</td>\n<td><code>download 2310.06825 --save-dir ./pdfs</code></td>\n</tr>\n<tr>\n<td><code>read &lt;pdf_path&gt; [--max-pages N]</code></td>\n<td>Extract PDF text via PyMuPDF</td>\n<td><code>read ./pdfs/foo.pdf --max-pages 20</code></td>\n</tr>\n</tbody>\n</table>\n<p><code>detail</code> and <code>citations</code> auto-detect the ID type: DOIs starting with <code>10.</code>\nare used as-is, bare numeric IDs of 10+ digits are treated as arXiv IDs, and\nlong hex strings are treated as Semantic Scholar <code>paperId</code>s.</p>\n<h2>Examples</h2>\n<h3>Example 1: Literature scan on a topic</h3>\n<pre><code>python \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" search \"retrieval augmented generation\" --limit 10\n</code></pre>\n<p>Present results as a ranked table with <strong># | Title | Year | Citations | ID</strong>,\nthen ask the user which papers to dig into.</p>\n<h3>Example 2: Deep-read one paper</h3>\n<pre><code># 1. Confirm match\npython \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" detail 2005.11401\n# 2. Download\npython \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" download 2005.11401 --save-dir ./pdfs\n# 3. Extract abstract + intro + conclusion\npython \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" read ./pdfs/2005.11401v4.RAG.pdf --max-pages 10\n</code></pre>\n<p>Summarize as: <strong>problem · method · key result · limitations</strong>.</p>\n<h3>Example 3: Impact analysis on an anchor paper</h3>\n<pre><code>python \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" detail 10.48550/arXiv.2005.11401\npython \"${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py\" citations 10.48550/arXiv.2005.11401 --limit 20\n</code></pre>\n<p>Cluster the citing papers by year/theme and highlight the most-cited\nfollow-ups.</p>\n<h2>Best Practices</h2>\n<ul>\n<li>✅ Always call <code>detail</code> before <code>download</code> to confirm the paper matches user\nintent. Skipping this leads to wrong PDFs being fetched.</li>\n<li>✅ Include the paper ID alongside every title in your output so the user\ncan re-query precisely.</li>\n<li>✅ Cite as <code>[FirstAuthor et al., Year] *Title* (cites: N)</code>.</li>\n<li>✅ For PDFs you download, always report the absolute save path.</li>\n<li>❌ Don't crawl. The script auto-retries 429s with exponential backoff;\ndon't pile on parallel queries.</li>\n<li>❌ Don't raise <code>--max-pages</code> to 100+ without warning the user — it can\nconsume a large amount of context.</li>\n</ul>\n<h2>Limitations</h2>\n<ul>\n<li>The skill cannot fetch full text from paywalled publishers (Elsevier,\nSpringer, Wiley, etc.). It can only read open arXiv PDFs.</li>\n<li>PyMuPDF extracts embedded text only. Scanned image-PDFs return the\nfallback message <code>PDF无法提取文本（可能是扫描件）</code>; offer the user an\nalternative version or note that OCR is required.</li>\n<li>Semantic Scholar's anonymous tier rate-limits aggressively. The script\nretries 3× with exponential backoff; persistent 429s during heavy use\nsurface as <code>搜索失败: rate limit, retries exhausted</code>.</li>\n<li>This skill does not replace environment-specific validation, testing, or\nexpert review. Stop and ask for clarification if required inputs are\nmissing.</li>\n</ul>\n<h2>Security &amp; Safety Notes</h2>\n<ul>\n<li>The CLI performs <strong>outbound HTTPS only</strong> to <code>api.semanticscholar.org</code> and\n<code>arxiv.org</code> (and the arXiv-listed mirror for the bundled <code>arxiv</code> package).\nNo authentication tokens are sent.</li>\n<li><code>download</code> writes a PDF to the directory the user specifies (default: the\ncurrent working directory). Confirm the save path with the user before\ndownloading to an unexpected location.</li>\n<li><code>read</code> opens a local PDF file with PyMuPDF — make sure the path the user\nsupplies is one they trust.</li>\n<li>No credentials or API keys are needed or stored anywhere.</li>\n</ul>\n<h2>Common Pitfalls</h2>\n<ul>\n<li><p><strong>Problem:</strong> <code>需要安装 arxiv: pip install arxiv</code> or <code>需要安装 PyMuPDF: pip install PyMuPDF</code>.\n<strong>Solution:</strong> The script returns this friendly message instead of crashing\nwhen an optional dependency is missing. Offer to run the install command.</p>\n</li>\n<li><p><strong>Problem:</strong> <code>搜索失败: rate limit, retries exhausted</code> from <code>search</code> or\n<code>detail</code> or <code>citations</code>.\n<strong>Solution:</strong> Semantic Scholar is rate-limiting. Wait ~10 seconds and\nretry once. For repeated runs, fall back to <code>arxiv</code> for arXiv-indexed work.</p>\n</li>\n<li><p><strong>Problem:</strong> <code>download</code> fails with <code>找不到 arXiv ID: …</code>.\n<strong>Solution:</strong> The user gave a non-arXiv ID (likely a DOI for a non-arXiv\npaper). Use <code>detail</code> to inspect; only papers with an <code>externalIds.ArXiv</code>\nfield can be downloaded.</p>\n</li>\n<li><p><strong>Problem:</strong> Garbled Chinese output on Windows.\n<strong>Solution:</strong> The script already forces UTF-8 stdout. If the host\nterminal is still misconfigured, set <code>PYTHONIOENCODING=utf-8</code> in the\nshell environment.</p>\n</li>\n</ul>\n<h2>Additional Resources</h2>\n<ul>\n<li>Skill home (this plugin): <a href=\"https://github.com/xwmxcz/papers-skill\">https://github.com/xwmxcz/papers-skill</a></li>\n<li>Upstream MCP server: <a href=\"https://github.com/xwmxcz/papers-mcp\">https://github.com/xwmxcz/papers-mcp</a></li>\n<li>Semantic Scholar API docs: <a href=\"https://api.semanticscholar.org/\">https://api.semanticscholar.org/</a></li>\n<li>arXiv API docs: <a href=\"https://info.arxiv.org/help/api/\">https://info.arxiv.org/help/api/</a></li>\n<li>PyMuPDF docs: <a href=\"https://pymupdf.readthedocs.io/\">https://pymupdf.readthedocs.io/</a></li>\n</ul>\n","files":[{"path":"scripts/papers.py","sizeBytes":8970,"isText":true},{"path":"SKILL.md","sizeBytes":8439,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-17T11:42:45.83313Z","sha256":"9868F8BAA13BE4F99E34992572221ABF63AF23B59C487B569DEB206B63E47403","sizeBytes":7226},"review":null,"source":{"repositoryUrl":"https://github.com/sickn33/agentic-awesome-skills","path":"skills/papers-skill","license":"MIT","commit":"f2bba339de74414b0771234cbe4f6a15258e32a3","subtreeSha":"5C07F957533C61570DAB283550C19D791CED12B61D77FBD67C316C5A8BE6D2B2","lastSyncedAt":"2026-09-25T06:48:39.853703Z"},"reviewedAt":"2026-08-17T11:44:36.018458Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/sickn33/agentic-awesome-skills/tree/main/skills/papers-skill"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sickn33-agentic-awesome-skills@llmmart"},{"target":"git","command":"git clone https://github.com/sickn33/agentic-awesome-skills.git"}]}