uv: Read the uv skill and follow its Setup instructions to ensure
uv is installed and on PATH.
User Notification: If .licenses/pubmed_database_LICENSE.txt does not
already exist in the workspace root directory then (1) prominently notify
the user to check the terms at https://pubmed.ncbi.nlm.nih.gov/disclaimer/
and https://www.ncbi.nlm.nih.gov/home/about/policies/ and to always check
the license of the papers retrieved by the skill for any restrictions, then
(2) create the file recording the notification text and timestamp.
.env file: Make sure the .env file exists in your home directory.
Create one if it does not exist.
NCBI_API_KEY (optional): Raises the NCBI E-utilities rate limit from 3
to 10 requests/second. The skill works without it, but a key is recommended
if the user plans many queries or encounters a 429 error. You can register
for a key for free at https://www.ncbi.nlm.nih.gov/account/settings/. You
MUST use the safe credentials protocol in the credentials skill to
check for and request this key if this skill looks relevant to the user's
request.
USER_EMAIL (optional): Identifies the caller to NCBI (recommended by
their Terms of Use). You MUST use the safe credentials protocol in the
credentials skill to check for and request this credential if this skill
looks relevant to the user's request.
This skill provides CLI access to the NCBI PubMed and PubMed Central APIs via
scripts/pubmed_api.py — a single CLI with 10 functions covering search, fetch,
linking, full text, spelling, discovery, citation matching, and caching.
Core Rules
API Use: Always use the provided wrapper which
manages rate limits automatically and prevents API abuse. Setting the
environment variable raises the rate limit from 3 to 10
requests/second. Querying the API any other way (e.g. via curl, wget, or
hand-written code) is strictly forbidden.
scripts/pubmed_api.py
NCBI_API_KEY
JSON Processing: Use jq to filter and transform JSON output (or python
equivalents if jq is not available) to prevent hallucinations and context
overflow.
Temporary Files: To avoid polluting the working directory with JSON
files, use a temporary directory inside the current directory. When running
multiple agents or tasks in parallel, ensure each uses a unique subdirectory
name (e.g., tmp_$TASK_ID/) to avoid file collisions.
Notification: If this skill is used, ensure this is mentioned in the
output AND list the URLs of all papers that were used in producing the
output.
Structure of the skill folder
SKILL.md - This file
scripts/pubmed_api.py - The skill CLI
references/ - Directory with detailed function specifications
advanced-linking.md
advanced-search.md
bulk-workflows.md
citation-matching.md
cross-database-linking.md
fetch-and-resolve.md
search-and-discovery.md
utilities.md
CLI Usage
uv run scripts/pubmed_api.py <output_file> <function_name> <required_args> [--flag value ...]
Positional Arguments: Arguments are positional; list arguments are
passed as comma-separated strings without spaces (e.g.
"35113657,31234568").
Flag Options: Optional arguments can be passed as --flag value instead
of positional args.
Output Handling: On success, JSON is written to output_file. On error,
the process exits with a non-zero code and no output file is written.
When processing larger result sets (>10 abstracts):
Filter Early: Use jq to verify keywords in abstracts before reading
the full JSON into context.
Slimming: Extract only title and abstract fields unless explicitly
instructed otherwise. Author lists and metadata contribute to noise.
Bulk Operations (N > 10): Avoid fetching or processing IDs one-by-one.
The API and History Server are designed for bulk retrieval. Fetch all data
in a single turn and use shell pipelines to slim the results before
reading into context. This prevents turn exhaustion and context overflow.
Grounding: Never use internal knowledge to provide specific identifiers
(PMIDs, CIDs, Gene IDs) if no results are found. Report the tool's output
accurately to ensure results are grounded in the current database state.
Search Termination: When asked to find papers that may not exist, limit
exploration to 3–5 high-quality, varied search queries. If no results match
after these attempts, conclude that no papers meet the criteria rather than
continuing to iterate — unless explicitly instructed to be thorough.
Functions
⚠️ MANDATORY: You MUST read the linked reference file for a function
group before calling any function in that group. The tables below only
describe what each function does — not how to call it. Argument names,
argument order, flags, and output schemas are only documented in the
reference files. Do NOT guess or infer arguments from function names. If
you call a function without first reading its reference, you will produce
incorrect invocations.
When working with more than ~10 PMIDs, avoid processing IDs one-by-one.
Upload them to the NCBI History Server via cache_results_history to get a
session handle (webenv + query_key), then pass that handle to
fetch_article_abstracts or find_linked_biological_data for a single bulk
call. Chain with jq shell pipelines to slim results before reading into
context. This prevents turn exhaustion and context overflow. See the reference
for complete workflow recipes (search→fetch, cross-db exploration, citation
resolution, and bulk retrieval with data slimming).
cache_results_history: Upload PMIDs to the NCBI History Server for bulk
retrieval.
