pmc-official-download

Source: https://github.com/aipoch/medical-research-skills

PMC Official Literature Download Skill

Skill Objective

Converge "download PubMed literature" requests into a single legal, traceable PMC workflow:

• First determine whether the article can actually be obtained through official PMC channels
• Only use officially permitted PMC services
• After downloading, retain source, license, and timestamp information for future reproducibility

The core of this skill is not "get any full text as fast as possible" but rather "only obtain legally accessible PMC content through officially permitted methods."

Trigger Scenarios

Use this skill first when the user has requests like:

• "Help me download this PubMed article"
• "Save the PMC full text corresponding to this PMID/PMCID"
• "Batch download PMC Open Access Subset"
• "Only use official methods to download articles from PMC"
• "Help me determine if this article can be legally downloaded from PMC"

If the user mentions Sci-Hub, mirror sites, bulk web scraping, bypassing restrictions, or similar approaches, refuse those paths directly and explain feasible alternatives using official PMC methods.

Permitted Official Channels

Only use the following official PMC channels:

• PMC Cloud Service
• PMC FTP Service
• PMC OAI-PMH Service
• PMC OA Web Service
• E-utilities
• BioC API

These are services explicitly permitted by PMC for automated retrieval or downloading. Do not use any other automated scraping methods.

Workflow

Step 1: Confirm What the User Actually Needs

First confirm three things:

• Whether the input is a PMID, PMCID, DOI, or title keywords
• Whether the user wants a single full-text article, batch download, or just metadata
• Whether the target format is XML, JSON, plain text, or PDF

If the user only provides a PMID, first map it to a PMCID, because whether it can be legally downloaded from PMC depends on whether the article exists in the PMC accessible collection.

Step 2: Determine Whether Legal Download is Possible

First determine whether the article belongs to a PMC accessible collection:

• PMC Open Access Subset
• PMC Author Manuscript Collection

If not in these collections, do not attempt to bypass restrictions or look for unofficial sites.

State directly:

• This article cannot be obtained through official PMC full-text download channels
• If the user needs it, I can help them use the abstract, citation information instead, or look for other legally public sources

Step 3: Select the Official Method

Choose the most appropriate official channel by scenario:

• For single full-text articles, prefer machine-readable content via BioC API
• When retrieving XML/JSON by PMID or PMCID, prefer BioC API
• When batch-syncing a local mirror, prefer PMC OA Web Service or PMC Cloud Service
• For more general retrieval, location, and record-keeping, use E-utilities
• For batch metadata harvesting, use OAI-PMH
• When article packages, XML, PDF, media files, or supplementary materials are needed, prefer PMC FTP Service or PMC Cloud Service

Notes:

• Only download PDF when it is explicitly provided in the official article package
• Do not scrape publisher web pages or third-party hosting pages to obtain PDF
• If the current article package does not contain a PDF, inform the user honestly

Step 4: Leave an Audit Trail When Saving Locally

When downloading, save the following information whenever possible:

• Original identifier
• Source service name
• Download timestamp
• License/collection information
• Local file path

Recommended output directory:

pmc-downloads/<identifier>/

If writing JSON metadata, use UTF-8 encoding and preserve original Chinese text — do not force-escape Chinese characters.

Recommended Single-Article Download Method

If the user wants full text for a single PMID / PMCID and accepts XML or JSON, prefer the helper script bundled with this skill:

python scripts/download_pmc_bioc.py

This script only uses the official PMC BioC API and is suitable for downloading the machine-readable version of a single publicly accessible full-text article.

Recommended Batch Download Method

If the user wants to batch-pull PMC public collections, follow these principles:

• Prefer using Cloud Service, FTP Service, or OA Web Service from the official PMC dataset page
• Do not hardcode old download paths
• If the official page indicates download location or service migration, defer to the current PMC documentation

Output Format

When answering the user, include the following information whenever possible:

• Whether this article can be downloaded through official PMC channels
• Which official service was used
• The downloaded file type
• File save location
• If download is not possible, provide a clear reason

Prohibited Actions

• Using unofficial mirrors, piracy sites, or third-party full-text repositories is prohibited
• Bulk web scraping of PMC page content is prohibited
• Bypassing license restrictions is prohibited
• Treating "can access the web page" as equivalent to "can automate batch downloads" is prohibited

Failure Handling

If an official channel does not return content, troubleshoot in the following order:

1. Check if the identifier is incorrect
2. Check if the article is not in the PMC accessible collection at all
3. Check if the target format is not supported by that service
4. Check if the current article has license restrictions

If still failing, honestly inform the user of the reason it cannot be downloaded and provide official alternative paths.

Practical Pitfalls

These are the most common gotchas with this skill — pay special attention when handling:

• The citation_pdf_url on article pages is often just a PDF viewer page, not necessarily a directly saveable binary PDF
• Before actually downloading, first use PMC OA Web Service to verify whether the PMCID is open, then get the official pdf link
• Official ftp://ftp.ncbi.nlm.nih.gov/... links can usually be changed to https://ftp.ncbi.nlm.nih.gov/..., which is more stable in local environments
• After downloading, always check if the file header starts with %PDF to avoid saving HTML as PDF by mistake
• Even if a title looks like "recent 3-year OA literature," it may not actually be in PMC's Open Access collection — do not judge downloadability by title alone
• For PMID, do not assume it can directly download full text — first map to PMCID, then determine downloadability

Command Line Usage

Prefer the unified entry point — do not rely on modifying constants at the top of scripts, and do not make yourself remember two script names:

python scripts/download_pmc.py --pmcid PMC13011518 --pmcid PMC11656652 --pmcid PMC11787101
python scripts/download_pmc.py --identifier PMC11787101

If the user has already provided a set of PMCIDs, PMIDs, or download directory, pass them directly to download_pmc.py rather than temporarily modifying code. Only fall back to the underlying scripts when you explicitly need to debug BioC or PDF details separately.

When to Use

• Use this skill when the user explicitly needs to perform the core task of pmc-official-download and has provided the minimum executable input.
• Use this skill when you need a structured deliverable rather than general advice.
• Use this skill when the current task can be completed using this skill's bundled scripts, templates, or reference materials.

When Not to Use

• Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
• Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
• Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.

Required Inputs

Output Contract

• Primary output: Structured result or target file aligned with this skill's objective.
• Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
• Format requirement: Unless the user specifies otherwise, prefer stable, reviewable Markdown or JSON; if the skill's bundled script requires a fixed format, use that format.
• If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.

Failure Handling

• Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
• Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
• Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.

User Checkpoints

• Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
• Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.

Input Validation

This skill accepts requests that match the documented purpose of pmc-official-download and include enough context to complete the workflow safely.

Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:

pmc-official-download only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.

Quick Validation

• Check that key scripts, templates, or reference file paths this skill depends on exist.
• Check that the final output contains the core fields, sections, or files specified for this task.
• Check that results clearly mark assumptions, limitations, and incomplete items.