{"id":"2c376931-9b85-45ed-9947-90c9b6e5127e","shortId":"Ls96S3","kind":"skill","title":"ref-downloader","tagline":"Use when the user asks to batch-download all references for a paper from a DOI or local PDF with ref-downloader. Not for one-off PDFs, paper search, or Zotero import.","description":"# Ref Downloader — Agent Runbook\n\n> Slim entry for agent mode. The full 8-step manual runbook with code\n> snippets, DOI-resolution fallback chain, and PUBLISHER_MAP extension procedure\n> lives in [references/agent-runbook.md](references/agent-runbook.md). Human users see\n> [../../README.md](../../README.md).\n\n`<SKILL_DIR>` = this folder (`skills/ref-downloader` in the source repo, or wherever the user copied this skill — e.g. `~/.claude/skills/ref-downloader/`). Python scripts live in `<SKILL_DIR>/scripts/`; config files (`config.example.toml`, `config.local.toml`) live at `<SKILL_DIR>/`.\n\n## Install prerequisites (before first invocation)\n\nThe skill protocol can't manage Python deps. If `python -c \"import playwright\"` fails, the user needs:\n\n```bash\ncd \"<SKILL_DIR>\"\npip install playwright pymupdf\nplaywright install msedge          # downloads Edge driver\ncp config.example.toml config.local.toml   # then user edits [crossref].mailto\n```\n\nIf the user is developing from the source repo instead of an installed skill copy, they can also install from the repo root with `pip install -r requirements.txt -r requirements-dev.txt`.\n\n## When to invoke\n\n**Trigger phrases**:\n- \"帮我下载 [paper / DOI] 的参考文献\" / \"批量下载引用文献\" / \"把这篇论文的所有引用下载下来\"\n- \"Download all refs of [paper / DOI]\" / \"Batch-download every reference\"\n- User provides a DOI (`10.x/y` form) or local PDF path and asks for \"all references\" / \"全部参考文献\"\n\n**Don't invoke for**:\n- Downloading one arbitrary PDF (not a reference list)\n- Generic web scraping\n- Paper search / Zotero import — different tools\n\n## Primary entry\n\n```bash\npython \"<SKILL_DIR>/scripts/run_ref_downloader.py\" <DOI_OR_PDF_PATH>\n```\n\nThe wrapper handles DOI resolution (Zotero → fitz fallback), output-dir layout,\nsequential 3-stage pipeline (`extract_refs.py` → `validate_refs.py` →\n`download_refs.py`), and end-of-run cleanup.\n\n**Useful flags**:\n- `--yes` — non-interactive (CI/batch), overwrite prompts default-yes\n- `--auto` — forwarded to `download_refs.py`: skip \"press Enter\" confirm + shorter challenge wait\n- `--output-dir <path>` — override default output location\n- `--config <path>` — alternate TOML config (overrides `config.local.toml`)\n\n## Pre-flight checklist (confirm before running)\n\n1. **DOI correct?** Echo back to user: `即将下载参考文献：DOI=<doi>`\n2. **Edge fully closed?** All `msedge.exe` processes killed (Task Manager check). The script claims the user's persistent Edge profile and needs exclusive access.\n3. **Config set?** First-run users need `<SKILL_DIR>/config.local.toml` with `[crossref].mailto`. Missing config → wrapper prints a WARNING but continues with placeholder defaults.\n4. **Output location agreed?** Default for DOI input: `<cwd>/<project_name>_refs/`. For PDF input: `<pdf_dir>/<pdf_stem>_refs/`. Override with `--output-dir`.\n\n## Output layout\n\n```\n<OUTPUT_DIR>/\n├── <PROJECT_NAME>/\n│   ├── refs_raw.json           # extract_refs.py output\n│   ├── refs_validated.json     # validate_refs.py output\n│   ├── download_report.csv     # per-ref status (only on graceful completion)\n│   ├── *.pdf                   # reference PDFs\n│   └── *_SI.pdf                # supplementary files (where supported)\n└── runs/<timestamp>-round-03/\n    └── events.jsonl            # full event trace per ref\n```\n\n**Interruption note**: if the run is interrupted (Ctrl+C / Edge crash / VPN drop),\nthe root `download_report.csv` may be stale. Trust the latest\n`runs/<timestamp>/events.jsonl` + actual files in `<PROJECT_NAME>/`.\n\n## Common failure modes\n\n| Status / symptom | Meaning | Action |\n|---|---|---|\n| `manual_pending (auth_redirect)` | Bounced to institution SSO | User signs in via live Edge tab; re-run (incremental skips done refs) |\n| `manual_pending (challenge_timeout)` | Cloudflare / publisher challenge unsolved in time | Re-run interactively; solve captcha when prompted |\n| `manual_pending (elsevier_crasolve_shell)` | Elsevier viewer stuck in transition | Hot-session auto-retry usually picks it up; else manual click in live page |\n| `failed (auto)` | Generic auto path failed | Check `events.jsonl` for that ref; may need a publisher-specific patch |\n| `ignored (ignored_institution_access)` | DOI listed in `[institution].ignored_access_dois` | Skip-by-design; remove from config to retry |\n| Edge won't launch | Background `msedge.exe` still holding profile | Kill all `msedge.exe` in Task Manager, re-run |\n| `ModuleNotFoundError: playwright` | Install prereqs not done | See \"Install prerequisites\" section above |\n| `WARNING: crossref.mailto is the placeholder` | First-run config uncustomized | Edit `<SKILL_DIR>/config.local.toml` → set `[crossref].mailto` to a real email (Crossref polite pool) |\n\n## Manual / debug mode\n\nIf the wrapper fails partway, run the 3 scripts standalone for partial re-execution:\n\n```bash\npython <SKILL_DIR>/scripts/extract_refs.py <DOI>           # → refs_raw.json\npython <SKILL_DIR>/scripts/validate_refs.py <PROJECT>      # → refs_validated.json\npython <SKILL_DIR>/scripts/download_refs.py <PROJECT>      # → PDFs + download_report.csv\n```\n\nFull 8-step manual flow with code snippets, DOI-resolution fallback chain (Zotero query → fitz text → user prompt), and the procedure for extending `PUBLISHER_MAP` when encountering an unknown DOI prefix → [references/agent-runbook.md](references/agent-runbook.md).\n\n## See also\n\n- [../../README.md](../../README.md) — human-facing setup, install, usage examples\n- [references/agent-runbook.md](references/agent-runbook.md) — full manual runbook with code snippets\n- [../../docs/SUPPORTED_PUBLISHERS.md](../../docs/SUPPORTED_PUBLISHERS.md) — publisher tier matrix\n- [../../CONTRIBUTING.md](../../CONTRIBUTING.md) — adding new publisher / institution SSO\n- [../../SECURITY.md](../../SECURITY.md) — Edge profile cookie risk\n- [config.example.toml](config.example.toml) — full config schema","tags":["ref","downloader","ltczding-gif","academic-tools","agent-skills","claude-code","codex-skills","crossref","literature-review","pdf-downloader","playwright","python"],"capabilities":["skill","source-ltczding-gif","skill-ref-downloader","topic-academic-tools","topic-agent-skills","topic-claude-code","topic-codex-skills","topic-crossref","topic-literature-review","topic-pdf-downloader","topic-playwright","topic-python","topic-zotero"],"categories":["ref-downloader"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ltczding-gif/ref-downloader/ref-downloader","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ltczding-gif/ref-downloader","source_repo":"https://github.com/ltczding-gif/ref-downloader","install_from":"skills.sh"}},"qualityScore":"0.489","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 78 github stars · SKILL.md body (5,836 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:56:49.399Z","embedding":null,"createdAt":"2026-05-12T13:07:02.893Z","updatedAt":"2026-05-18T18:56:49.399Z","lastSeenAt":"2026-05-18T18:56:49.399Z","tsv":"'-03':409 '/../contributing.md':692,693 '/../docs/supported_publishers.md':687,688 '/../readme.md':74,75,670,671 '/../security.md':699,700 '/.claude/skills/ref-downloader':91 '/config.local.toml':349,594 '/events.jsonl':439 '/scripts':96 '/scripts/download_refs.py':631 '/scripts/extract_refs.py':625 '/scripts/run_ref_downloader.py':239 '/scripts/validate_refs.py':628 '1':308 '10':201 '2':317 '3':253,341,615 '4':364 '8':50,635 'access':340,537,543 'action':449 'actual':440 'ad':694 'agent':41,46 'agre':367 'also':162,669 'altern':296 'arbitrari':220 'ask':8,209 'auth':452 'auto':277,504,517,519 'auto-retri':503 'back':312 'background':558 'bash':125,237,623 'batch':11,193 'batch-download':10,192 'bounc':454 'c':118,424 'captcha':487 'cd':126 'chain':61,646 'challeng':286,474,478 'check':327,522 'checklist':304 'ci/batch':271 'claim':330 'cleanup':264 'click':512 'close':320 'cloudflar':476 'code':55,640,685 'common':443 'complet':398 'config':97,295,298,342,354,551,591,708 'config.example.toml':99,138,705,706 'config.local.toml':100,139,300 'confirm':284,305 'continu':360 'cooki':703 'copi':87,159 'correct':310 'cp':137 'crash':426 'crasolv':493 'crossref':143,351,596,602 'crossref.mailto':584 'ctrl':423 'debug':606 'default':275,292,363,368 'default-y':274 'dep':115 'design':548 'develop':149 'differ':233 'dir':250,290,381 'doi':20,58,182,191,200,243,309,316,370,538,544,643,664 'doi-resolut':57,642 'done':470,577 'download':3,12,27,40,134,186,194,218 'download_refs.py':258,280 'download_report.csv':390,431,633 'driver':136 'drop':428 'e.g':90 'echo':311 'edg':135,318,335,425,463,554,701 'edit':142,593 'els':510 'elsevi':492,495 'email':601 'encount':661 'end':261 'end-of-run':260 'enter':283 'entri':44,236 'event':412 'events.jsonl':410,523 'everi':195 'exampl':678 'exclus':339 'execut':622 'extend':657 'extens':65 'extract_refs.py':256,385 'face':674 'fail':121,516,521,611 'failur':444 'fallback':60,247,645 'file':98,404,441 'first':106,345,589 'first-run':344,588 'fitz':246,649 'flag':266 'flight':303 'flow':638 'folder':77 'form':203 'forward':278 'full':49,411,634,681,707 'fulli':319 'generic':226,518 'grace':397 'handl':242 'hold':561 'hot':501 'hot-sess':500 'human':71,673 'human-fac':672 'ignor':534,535,542 'import':38,119,232 'increment':468 'input':371,375 'instal':103,128,132,157,163,170,574,579,676 'instead':154 'institut':456,536,541,697 'interact':270,485 'interrupt':416,422 'invoc':107 'invok':177,216 'kill':324,563 'latest':437 'launch':557 'layout':251,383 'list':225,539 'live':67,94,101,462,514 'local':22,205 'locat':294,366 'mailto':144,352,597 'manag':113,326,568 'manual':52,450,472,490,511,605,637,682 'map':64,659 'matrix':691 'may':432,527 'mean':448 'miss':353 'mode':47,445,607 'modulenotfounderror':572 'msedg':133 'msedge.exe':322,559,565 'need':124,338,348,528 'new':695 'non':269 'non-interact':268 'note':417 'one':31,219 'one-off':30 'output':249,289,293,365,380,382,386,389 'output-dir':248,288,379 'overrid':291,299,377 'overwrit':272 'page':515 'paper':17,34,181,190,229 'partial':619 'partway':612 'patch':533 'path':207,520 'pdf':23,206,221,374,399 'pdfs':33,401,632 'pend':451,473,491 'per':392,414 'per-ref':391 'persist':334 'phrase':179 'pick':507 'pip':127,169 'pipelin':255 'placehold':362,587 'playwright':120,129,131,573 'polit':603 'pool':604 'pre':302 'pre-flight':301 'prefix':665 'prereq':575 'prerequisit':104,580 'press':282 'primari':235 'print':356 'procedur':66,655 'process':323 'profil':336,562,702 'prompt':273,489,652 'protocol':110 'provid':198 'publish':63,477,531,658,689,696 'publisher-specif':530 'pymupdf':130 'python':92,114,117,238,624,627,630 'queri':648 'r':171,173 're':466,483,570,621 're-execut':620 're-run':465,482,569 'real':600 'redirect':453 'ref':2,26,39,188,372,376,393,415,471,526 'ref-download':1,25 'refer':14,196,212,224,400 'references/agent-runbook.md':69,70,666,667,679,680 'refs_raw.json':384,626 'refs_validated.json':387,629 'remov':549 'repo':82,153,166 'requirements-dev.txt':174 'requirements.txt':172 'resolut':59,244,644 'retri':505,553 'risk':704 'root':167,430 'round':408 'run':263,307,346,407,420,438,467,484,571,590,613 'runbook':42,53,683 'schema':709 'scrape':228 'script':93,329,616 'search':35,230 'section':581 'see':73,578,668 'sequenti':252 'session':502 'set':343,595 'setup':675 'shell':494 'shorter':285 'si.pdf':402 'sign':459 'skill':89,109,158 'skill-ref-downloader' 'skills/ref-downloader':78 'skip':281,469,546 'skip-by-design':545 'slim':43 'snippet':56,641,686 'solv':486 'sourc':81,152 'source-ltczding-gif' 'specif':532 'sso':457,698 'stage':254 'stale':434 'standalon':617 'status':394,446 'step':51,636 'still':560 'stuck':497 'supplementari':403 'support':406 'symptom':447 'tab':464 'task':325,567 'text':650 'tier':690 'time':481 'timeout':475 'toml':297 'tool':234 'topic-academic-tools' 'topic-agent-skills' 'topic-claude-code' 'topic-codex-skills' 'topic-crossref' 'topic-literature-review' 'topic-pdf-downloader' 'topic-playwright' 'topic-python' 'topic-zotero' 'trace':413 'transit':499 'trigger':178 'trust':435 'uncustom':592 'unknown':663 'unsolv':479 'usag':677 'use':4,265 'user':7,72,86,123,141,147,197,314,332,347,458,651 'usual':506 'validate_refs.py':257,388 'via':461 'viewer':496 'vpn':427 'wait':287 'warn':358,583 'web':227 'wherev':84 'won':555 'wrapper':241,355,610 'x/y':202 'yes':267,276 'zotero':37,231,245,647 '全部参考文献':213 '即将下载参考文献':315 '帮我下载':180 '批量下载引用文献':184 '把这篇论文的所有引用下载下来':185 '的参考文献':183","prices":[{"id":"e27e1608-a6b2-4fea-8b0a-6db65d1f8433","listingId":"2c376931-9b85-45ed-9947-90c9b6e5127e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ltczding-gif","category":"ref-downloader","install_from":"skills.sh"},"createdAt":"2026-05-12T13:07:02.893Z"}],"sources":[{"listingId":"2c376931-9b85-45ed-9947-90c9b6e5127e","source":"github","sourceId":"ltczding-gif/ref-downloader/ref-downloader","sourceUrl":"https://github.com/ltczding-gif/ref-downloader/tree/main/skills/ref-downloader","isPrimary":false,"firstSeenAt":"2026-05-12T13:07:02.893Z","lastSeenAt":"2026-05-18T18:56:49.399Z"}],"details":{"listingId":"2c376931-9b85-45ed-9947-90c9b6e5127e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ltczding-gif","slug":"ref-downloader","github":{"repo":"ltczding-gif/ref-downloader","stars":78,"topics":["academic-tools","agent-skills","claude-code","codex-skills","crossref","literature-review","pdf-downloader","playwright","python","zotero"],"license":"mit","html_url":"https://github.com/ltczding-gif/ref-downloader","pushed_at":"2026-05-11T03:33:33Z","description":"Batch-download reference PDFs from a DOI or paper PDF using Crossref and your institutional Edge session.","skill_md_sha":"3c1caa21a163be9dbf007ddf3bde98fbcb9da860","skill_md_path":"skills/ref-downloader/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ltczding-gif/ref-downloader/tree/main/skills/ref-downloader"},"layout":"multi","source":"github","category":"ref-downloader","frontmatter":{"name":"ref-downloader","description":"Use when the user asks to batch-download all references for a paper from a DOI or local PDF with ref-downloader. Not for one-off PDFs, paper search, or Zotero import."},"skills_sh_url":"https://skills.sh/ltczding-gif/ref-downloader/ref-downloader"},"updatedAt":"2026-05-18T18:56:49.399Z"}}