菜单
Resolve paper identifiers, fetch the PDF and metadata, and prepare inputs for paper asset creation. Use when you need to download a research paper from partial identifiers.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Interactively register one or more project metrics in meta/metrics/, grounded in project/description.md. Use during project setup or any time a new measurement needs to be tracked across tasks.
Create a new not-started task folder with task.json and task_description.md. Use when any skill or workflow needs to create a new task.
Run an interactive brainstorming session to review state and choose next actions.
One-shot interactive onboarding for a newly forked Glite ARF template. Shows the safety acknowledgement, installs dependencies, runs doctor.py, chains into create-project-description, provisions the paid services the project declared, then invokes the four meta/ sub-skills. Use once per fork, right after cloning.
Interactively scaffold a new asset type under meta/asset_types/, grounded in project/description.md. Creates a specification.md stub patterned on the built-in asset types. Use during project setup when a custom asset kind is needed; accept "none for now" to skip.
Interactively add one or more entries to meta/categories/, grounded in project/description.md. Use during project setup or any time a new cross-cutting tag is needed.
| name | download_paper |
| description | Resolve paper identifiers, fetch the PDF and metadata, and prepare inputs for paper asset creation. Use when you need to download a research paper from partial identifiers. |
| model | claude-sonnet-4-6 |
Version: 1
Given partial paper identifiers (any combination of title, DOI, authors, year, arXiv ID, PMID), retrieve the full-text content of the paper in the best available format.
{{ title }} — paper title (optional if DOI or other ID provided){{ doi }} — Digital Object Identifier (optional){{ authors }} — author names, comma-separated (optional){{ year }} — publication year (optional){{ arxiv_id }} — arXiv identifier (optional){{ pmid }} — PubMed identifier (optional){{ output_dir }} — directory to save the downloaded fileAt least one of title, doi, or arxiv_id must be provided. More identifiers improve resolution
accuracy.
Read before starting:
arf/styleguide/python_styleguide.md — if writing helper scriptsIf any temporary helper scripts are created during execution, delete them before completing the skill. Do not leave throwaway code in the repository.
This skill is not a simple downloader. It is a version-aware scholarly resolver. The agent identifies the work precisely, collects every known identifier, then searches for the best accessible version across all available channels. When the published version is unavailable, preprints, accepted manuscripts, working papers, and structured XML are all valid and valuable alternatives.
Prefer machine-readable formats over PDF when available. For an AI agent, structured XML/TEI/JATS or plain text is more useful than a PDF that requires extraction.
Format preference ranking:
Version preference ranking:
Build a complete metadata record before attempting any download. The more identifiers collected, the higher the success rate in later phases.
https://api.crossref.org/works/{doi}) to get full
metadata: title, authors, year, ISSN, publisher, DOI prefix, and any relation fields linking to
preprints.query.bibliographic endpoint with title + author + year filter:
https://api.crossref.org/works?query.bibliographic={title}+{author}&filter=from-pub-date: {year}-01-01,until-pub-date:{year}-12-31&rows=3.
Take the top match. Verify by fuzzy-matching the returned title against the input title
(similarity > 0.85)./graph/v1/paper/search?query={title}) — returns
paperId, DOI, arXiv ID, PMID.https://api.openalex.org/works?search={title}&filter= publication_year:{year}) for
additional ID coverage.title (normalized: lowercase, stripped punctuation for matching)doi and doi_prefix (e.g., 10.1371 for PLOS, 10.1016 for Elsevier)pmid / pmcidarxiv_idopenalex_idsemantic_scholar_idauthors (list of names)yearvenue (journal or conference name)publisher (from CrossRef member field — more reliable than DOI prefix for routing)preprint_doi (if CrossRef has-preprint relation exists)https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0/?ids={id}&format=json) to check for a PMC
version. Batch up to 200 IDs per request.10.5555 prefix for cross-listed
materials from other publishers (e.g., IEEE). If the DOI prefix is 10.5555, do not use it for
downstream retrieval — instead, search by title to find the real publisher DOI (e.g., an IEEE DOI
starting with 10.1109).Batch optimization: When resolving multiple papers, use Semantic Scholar POST /paper/batch (up
to 500 IDs per request) and OpenAlex pipe-separated DOI filter
(GET /works?filter=doi:{doi1}|{doi2}|{doi3}&per_page=100, up to 50 DOIs).
Query the major OA aggregators. Fire these in parallel — first success with a usable PDF/text URL wins.
GET https://api.unpaywall.org/v2/{doi}?email={your_email}. Check
best_oa_location.url_for_pdf. If no direct PDF, check all entries in oa_locations[] — try
each URL. Note the version field (publishedVersion / acceptedVersion / submittedVersion).GET https://api.openalex.org/works/doi:{doi}. Check
open_access.oa_url, best_oa_location, and iterate all locations[]. OpenAlex also exposes
fulltext_origin and may provide TEI XML access for some papers.GET https://api.semanticscholar.org/graph/v1/paper/{id}?fields=openAccessPdf,isOpenAccess.
Check openAccessPdf.url.message.link[] for entries with intended-application: "text-mining". These may provide
direct full-text access (XML or PDF).GET https://api.opencitations.net/index/v2/metadata/{doi}.
Check the oa_link field for a direct OA URL. Free, no auth, 1B+ citation links indexed.If Phase 2 returned no usable URL, try constructing the PDF URL directly from the DOI and publisher
identity. Use the doi_prefix and publisher from the canonical record to route.
Fully open-access publishers (always free — try these URL patterns first):
10.1371): https://journals.plos.org/{journal}/article/file?id={doi}&type=printable10.3390): append /pdf to article URL (e.g.,
https://www.mdpi.com/2073-8994/11/10/1189/pdf)10.3389): https://www.frontiersin.org/articles/{doi}/pdfhttps://link.springer.com/content/pdf/{doi}.pdfMajor subscription publishers (free for OA articles only):
10.1016): https://www.sciencedirect.com/science/article/pii/{PII}/pdf for OA
articles. TDM API: GET https://api.elsevier.com/content/article/doi/{doi}?httpAccept=text/xml
(requires ELSEVIER_API_KEY).10.1038, 10.1007): https://link.springer.com/content/pdf/{doi}.pdf for
OA articles. Also check for SharedIt read-only links at https://rdcu.be/{hash} — these provide
view access even for paywalled articles.10.1002): https://onlinelibrary.wiley.com/doi/pdfdirect/{doi} for OA articles.10.1109): https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber={article_number}.
IEEE Access journal is fully OA.10.1145): https://dl.acm.org/doi/pdf/{doi}. ACM Author-izer service lets authors post
free-access links.10.1080): https://www.tandfonline.com/doi/pdf/{doi}10.1177): https://journals.sagepub.com/doi/pdf/{doi}10.1021): https://pubs.acs.org/doi/pdf/{doi}. ACS AuthorChoice articles are CC-BY.Note: DOI prefix alone is not always reliable for publisher identification — Elsevier alone has 26+
prefixes. The CrossRef member field from Phase 1 is the authoritative publisher identifier. Use
prefix as a fast hint, fall back to CrossRef member for routing.
If Phases 2-3 did not yield full text, try domain-specific repositories.
GET https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/ BioC_json/{PMCID}/unicode
for structured full text.GET https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/fullTextXML for JATS
XML. Also try direct PDF: https://europepmc.org/articles/{pmcid}?pdf=render.Entrez.efetch(db="pmc", id=PMCID, rettype="full", retmode="xml").https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&id={pmid}&cmd=llinks
to get third-party free full-text links registered with NCBI. Publishers and repositories
register these links directly — a source most agents miss.s3://pmc-oa-opendata/) over FTP.arxiv_id is known: download directly from https://arxiv.org/pdf/{arxiv_id}.pdf or
https://export.arxiv.org/pdf/{arxiv_id}.arxiv_id is unknown: search by title via
http://export.arxiv.org/api/query?search_query=ti:{title}&max_results=3. Verify match by
title similarity + author overlap.GET https://api.biorxiv.org/details/biorxiv/{doi}/na/json./pubs/ endpoint to find preprint-to-published mappings:
GET https://api.biorxiv.org/pubs/biorxiv/{published_doi}.https://www.biorxiv.org/content/{doi}v{version}.full.pdf.https://papers.ssrn.com/sol3/Delivery.cfm/SSRN_ID{id}.pdf?abstractid={id}.https://osf.io/preprints/{provider}/{id}/download.https://aclanthology.org/{id}.pdf (all computational linguistics)https://proceedings.neurips.cc/paper_files/paper/{year}/file/{hash}-Paper.pdfhttps://proceedings.mlr.press/v{volume}/{author}{suffix}/{author}{suffix}.pdfhttps://openaccess.thecvf.com/ (CVPR 2013 onward)https://ojs.aaai.org/ (OJS-based, supports OAI-PMH)https://www.ijcai.org/proceedings/{year}/{number}.pdfhttps://jmlr.org/papers/ (all open access)https://api.openreview.net/GET https://api.adsabs.harvard.edu/v1/search/query?q={query}. API key required. Full-text links
via /resolver/{bibcode}/esource. Covers 15M+ records.GET https://inspirehep.net/api/literature?q={query}. No
auth required. PDF links in metadata.documents[].url. Covers 1.5M+ records.GET https://api.ies.ed.gov/eric/?search={query}&format=json. PDFs at
https://files.eric.ed.gov/fulltext/{ED_number}.pdf. ~1.5M records, ~25% full text.GET https://www.osti.gov/api/v1/records?title={query}.
Covers journal articles and technical reports. OAI-PMH also available.Search aggregators that index institutional repositories, author deposits, and funder-mandated copies.
GET https://api.core.ac.uk/v3/search/works?q={title}. CORE
aggregates 40M+ full-text papers from 10,000+ institutional repositories. Check results for
downloadUrl or direct PDF links.GET https://api.archives-ouvertes.fr/search/?q={title}&fq=submitType_s:file&fl=uri_s,files_s.
Filter for records that actually have deposited files using submitType_s:file. PDF in
fileMain_s field or at https://hal.science/{halId}/document.GET https://zenodo.org/api/records?q={title}. Check file attachments in record metadata. Direct
file download at https://zenodo.org/records/{id}/files/{filename}?download=1.https://api.base-search.net/ uses Solr query syntax. Requires IP whitelisting — request
access via their contact form. Key fields: dctitle: (title), dcauthor: (author), dclink:
(document URL), dcoa:1 (OA filter).https://doaj.org/oai.article.
The Dublin Core relation field contains direct full-text URLs. If a paper is in a DOAJ-indexed
journal, this is a reliable path to a legal PDF.If the published version is paywalled, actively hunt for preprint or accepted manuscript versions.
relation fields for has-preprint / is-preprint-of links discovered in Phase
1./pubs/ endpoint with the published DOI to find a linked preprint.locations[] — it often lists preprint server copies that other services miss.https://dissem.in/api/) — query by DOI or title+authors+date. Returns OA
classification and pdf_url when available. Also indicates self-archiving policy.If structured APIs have not yielded the paper, search the open web.
scholarly Python library: scholarly.search_pubs(title). Check
eprint_url for free PDF links. Scholar often finds PDFs on author homepages, lab websites, and
university course pages that no API indexes.
"{exact paper title}" filetype:pdf using a
web search API. This surfaces PDFs on university servers, personal pages, and course materials.
Also try "{author name}" "{paper title}" filetype:pdf site:edu for faculty-hosted copies.https://scholar.archive.org/): Full-text search over 25M+ open
papers. Built on the Fatcat open catalog (api.fatcat.wiki/v0/). Also check the Wayback Machine
for cached versions of known publisher URLs:
GET https://archive.org/wayback/available?url={publisher_url}. For raw PDFs from the archive,
use the id_ suffix: https://web.archive.org/web/{timestamp}id_/{original_url}.https://pub.orcid.org/v3.0/{orcid}/works, requires OAuth2 /read-public token, 24 req/sec) to
find author work listings with URLs to self-archived copies.Some publisher sites display full text in HTML but restrict PDF download. HTML pages also often contain machine-readable pointers to the PDF that are invisible to casual browsing.
<script type="application/ld+json"> block in the HTML. If it contains
"isAccessibleForFree": false, the article is paywalled on this site — skip directly to the next
phase instead of wasting time parsing the page. Many publishers embed this structured data for
Google indexing.citation_pdf_url meta tag — parse the HTML <head> for
<meta name="citation_pdf_url" content="...">. This is the standard mechanism used by Google
Scholar, Unpaywall, and Zotero to discover PDFs. If present, download directly from that URL.
Also check related tags: citation_title, citation_doi, citation_authors to verify you are
on the correct article page.citation_pdf_url is found but the full article text is present in the page body, extract
the article text using content-extraction techniques (main content detection, stripping
navigation/ads). Note: some "soft paywalls" load full text in the DOM but hide it behind CSS
overlays or JavaScript modals — check the raw HTML, not just the rendered view.If the major APIs and aggregators failed, try less conventional but still structured sources:
https://oatd.org/, 7M+ theses from 1,100+ institutions) and NDLTD.https://openreview.net/) — all submissions are openly
hosted.If every method above has failed, do not give up. Stop following the playbook. Use the canonical record from Phase 1 — title, authors, year, venue, topic — and think creatively about where this specific paper's text might exist. Consider the field, the authors, the institution, the funding source, the publication venue, the time period, and any other clue. There are no prescribed steps here. Improvise. Try anything that might work.
Throughout Phases 2-10, collect all discovered URLs into a ranked candidate list using the scoring system below. Do not stop at the first URL found — gather candidates from multiple sources, then work through the list from highest to lowest score. This resilience matters because the top-ranked URL may be temporarily down, geo-blocked, or rate-limited.
Content-Type header is application/pdf. Verify the file starts with
%PDF- magic bytes and contains an %%EOF marker (truncated PDFs lack it). Check file size >
10 KB (a typical paper is 100KB-5MB). Extract text from the first page using pymupdf or
pdfplumber and fuzzy-match the extracted title against the canonical title (similarity >
0.80). For stronger verification, run pdf2doi against the downloaded file to extract the
embedded DOI from text/metadata and compare it against the canonical DOI.{{ output_dir }} with filename format:
{first_author_last_name}_{year}_{short_title_slug}.{ext} (e.g.,
vaswani_2017_attention_is_all_you_need.pdf).status: "success" | "partial" | "not_found"file_path: path to the saved file (if downloaded)format: "pdf" | "xml" | "text" | "html"version: "published" | "accepted" | "submitted" | "preprint" | "working_paper" |
"unknown"source: URL or API name where the file was obtainedconfidence: float 0.0-1.0 (based on title match, author overlap, year match)canonical_record: the full metadata record built in Phase 1all_attempted_sources: list of sources tried and their statusAll API keys are stored as environment variables in .env (loaded automatically via direnv). Read
keys from environment variables at runtime using os.environ. NEVER hardcode keys in source
files.
Before starting, check which keys are available. Skip services whose required keys are missing — do not fail, just move to the next source in the cascade.
| Environment Variable | Service | Required? |
|---|---|---|
SCHOLAR_EMAIL | CrossRef, Unpaywall | Yes — mailto: for CrossRef polite pool and email param for Unpaywall |
OPENALEX_API_KEY | OpenAlex | Yes — required since Feb 2025, free at openalex.org |
SEMANTIC_SCHOLAR_API_KEY | Semantic Scholar | Recommended — free at semanticscholar.org |
CORE_API_KEY | CORE | Required for CORE — free at core.ac.uk |
NCBI_API_KEY | PMC / PubMed | Optional — raises rate limit 3→10 req/sec |
ELSEVIER_API_KEY | Elsevier / ScienceDirect | Optional — free at dev.elsevier.com |
SPRINGER_API_KEY | Springer Nature | Optional — free at dev.springernature.com |
Services that need no key at all: arXiv, bioRxiv, medRxiv, Europe PMC, Zenodo, HAL, Dissemin, OSF, DOAJ, Internet Archive, OpenCitations, INSPIRE-HEP, ORCID (public data).
If SCHOLAR_EMAIL is not set, abort with a clear error — it is the minimum required credential for
this skill.
| Service | Auth | Rate Limit |
|---|---|---|
| CrossRef | SCHOLAR_EMAIL | 50 req/sec (polite) |
| Unpaywall | SCHOLAR_EMAIL | 100K req/day |
| OpenAlex | OPENALEX_API_KEY | 100K credits/day |
| Semantic Scholar | SEMANTIC_SCHOLAR_API_KEY | 1 req/sec |
| CORE | CORE_API_KEY | 5 req/10 sec |
| OpenCitations | None | Be polite |
| arXiv | None | Use export subdomain |
| bioRxiv/medRxiv | None | Be polite |
| PMC / NCBI | NCBI_API_KEY | 3-10 req/sec |
| Europe PMC | None | Generous |
| NASA ADS | API key required | Per plan |
| INSPIRE-HEP | None | Be polite |
| ORCID | OAuth2 /read-public | 24 req/sec |
| Zenodo | None | 60-100 req/hour |
| HAL | None | Be polite |
| Dissemin | None | Be polite |
| OSF | None | 100 req/hour |
| DOAJ | None | Be polite |
| Google Scholar | None (no official API) | Rate-limited by IP |
All services expect a descriptive User-Agent header with SCHOLAR_EMAIL. Implement exponential
backoff with jitter (base 1s, max 30s, factor 2x) on HTTP 429/5xx responses. Use a circuit breaker:
if a source fails >5 times in 5 minutes, skip it for 30 minutes. Cache all API responses keyed by
DOI (lowercase, URL-decoded) — never re-fetch the same identifier.
| Library | Purpose |
|---|---|
habanero | CrossRef API client (DOI lookup, title-to-DOI) |
unpywall | Unpaywall API (OA PDF discovery by DOI) |
pyalex | OpenAlex API (works, authors, OA locations) |
semanticscholar | Semantic Scholar API (paper search, OA PDF) |
arxiv | arXiv search + PDF/source download |
biopython | Bio.Entrez for PubMed/PMC efetch/esearch |
pyeuropepmc | Europe PMC search + full-text XML retrieval |
scholarly | Google Scholar search (use as last resort) |
paperscraper | Multi-preprint server search (arXiv/bioRxiv) |
sickle | OAI-PMH harvesting from institutional repositories |
pymupdf | PDF text extraction and validation |
pdf2doi | Reverse-extract DOI from a downloaded PDF for verification |
findpapers | Multi-database parallel search (arXiv, IEEE, OpenAlex, PubMed, Scopus) |
httpx | Async HTTP client for parallel API calls |
When multiple versions are found, score candidates to pick the best:
Pick the candidate with the highest total score. On ties, prefer the source with higher trust ranking: publisher > PMC > major repository > preprint server > personal page > other.
status, source, version, confidence, and
all_attempted_sources fields populated.status is "success": a validated file exists at file_path with confirmed title match
(confidence > 0.80).status is "not_found": at least 10 distinct sources were attempted (documented in
all_attempted_sources), including Unpaywall, OpenAlex, Semantic Scholar, CrossRef, at least one
preprint server, and at least one repository aggregator.{{ output_dir }} with matching DOI — check for
existing files first.