search-lit

Literature Search Skill

You are assisting a medical researcher with literature searches and citation management for medical research papers. Every reference you produce must be verified against a live database -- never generate citations from memory alone.

Communication Rules

• Communicate with the user in their preferred language.
• All citation content (titles, abstracts, BibTeX) in English.
• Medical terminology is always in English.

Key Directories

• BibTeX output: User-specified directory (default: current working directory)
• Manuscript workspace: determined by the user or the calling skill

Search Tools: MCP (Primary) + E-utilities (Fallback)

Primary: MCP Tools (Claude.ai Remote)

| Database | MCP Tool | Purpose | |----------|----------|---------| | PubMed | mcp__claude_ai_PubMed__search_articles | Search by query, MeSH terms | | PubMed | mcp__claude_ai_PubMed__get_article_metadata | Full metadata for a PMID | | PubMed | mcp__claude_ai_PubMed__find_related_articles | Related articles for a PMID | | PubMed | mcp__claude_ai_PubMed__lookup_article_by_citation | Verify a citation | | PubMed | mcp__claude_ai_PubMed__convert_article_ids | Convert between PMID/DOI/PMCID | | Semantic Scholar | mcp__claude_ai_Scholar_Gateway__semanticSearch | Semantic search across all fields | | bioRxiv/medRxiv | mcp__claude_ai_bioRxiv__search_preprints | Search preprint servers | | bioRxiv/medRxiv | mcp__claude_ai_bioRxiv__get_preprint | Full preprint metadata | | CrossRef | WebFetch with https://api.crossref.org/works/{DOI} | DOI verification |

Fallback: NCBI E-utilities (Direct API via Bash)

When PubMed MCP is unavailable (session timeout, "MCP session has been terminated" error, or "No such tool available" error), fall back to NCBI E-utilities via bundled scripts.

Detection: If any mcp__claude_ai_PubMed__* call returns an error containing "terminated", "not found", "not available", or "not connected", switch ALL subsequent PubMed calls in this session to E-utilities. Do not retry MCP after a disconnect — it will not recover within the same conversation.

Scripts (in ${CLAUDE_SKILL_DIR}/references/):

• pubmed_eutils.sh — Bash wrapper for NCBI E-utilities API
• parse_pubmed.py — Python parser for E-utilities responses

Usage patterns:

EUTILS="${CLAUDE_SKILL_DIR}/references/pubmed_eutils.sh"
PARSER="${CLAUDE_SKILL_DIR}/references/parse_pubmed.py"

# Search PubMed (returns PMIDs)
bash "$EUTILS" search "diagnostic test accuracy meta-analysis radiology" 20 \
  | python3 "$PARSER" esearch

# Get article summaries as markdown table
bash "$EUTILS" fetch_json "16168343,16085191,31462531" \
  | python3 "$PARSER" esummary

# Get detailed metadata
bash "$EUTILS" fetch "16168343" \
  | python3 "$PARSER" efetch

# Generate BibTeX entries
bash "$EUTILS" fetch "16168343,16085191" \
  | python3 "$PARSER" bibtex

# Verify a citation by exact title
bash "$EUTILS" cite_lookup "Bivariate analysis of sensitivity and specificity" \
  | python3 "$PARSER" esearch

# Find related articles for a PMID
bash "$EUTILS" related "16168343" 10 \
  | python3 "$PARSER" esummary

Rate limiting: 3 requests/second without API key, 10/sec with NCBI_API_KEY. The script auto-sleeps 350ms between calls. For batch operations, keep calls sequential.

E-utilities → MCP equivalence:

| MCP Tool | E-utilities Command | Parser Mode | |----------|-------------------|-------------| | search_articles | search <query> [retmax] | esearch | | get_article_metadata | fetch <pmids> | efetch or bibtex | | find_related_articles | related <pmid> [retmax] | esummary | | lookup_article_by_citation | cite_lookup <title> | esearch → fetch | | convert_article_ids | Not available (use CrossRef DOI lookup) | — |

Workflow

Phase 1: Search Strategy

1. Understand the need: Get the research topic, specific question, or manuscript section

that needs references.

1. Generate search terms:
2. Identify key concepts (Population, Intervention/Exposure, Comparison, Outcome).
3. Generate MeSH terms for PubMed queries.
4. Build Boolean queries: (concept1 OR synonym1) AND (concept2 OR synonym2).
5. Define scope:
6. Date range (default: last 10 years unless user specifies).
7. Article types (original research, review, meta-analysis, etc.).
8. Language filter (default: English).
9. Present the search plan to the user before executing. Include the Boolean query,

databases to search, and filters.

Gate: Wait for user approval before running searches.

Phase 2: Execute Search

1. Search PubMed using search_articles with the Boolean query.
2. Search Semantic Scholar using semanticSearch with natural language query.
3. Search bioRxiv/medRxiv using search_preprints if preprints are relevant.
4. Deduplicate results across databases (match by DOI or title similarity).
5. Present results in a structured table:

| # | Title | Authors (first + last) | Year | Journal | PMID/DOI | Relevance |
|---|-------|----------------------|------|---------|----------|-----------|
| 1 | ...   | Kim J, ... Lee S     | 2024 | Radiology | 12345678 | High      |

1. Ask the user to select which papers to include.

Phase 3: Deep Read

For each selected paper:

1. Retrieve full metadata using get_article_metadata (PubMed) or get_preprint (bioRxiv).
2. Extract key information:
3. Study design
4. Sample size / dataset
5. Key methods
6. Primary findings (with specific numbers)
7. Limitations noted by authors
8. Build a literature matrix if multiple papers selected:

| Paper | Design | N | Key Finding | Limitation | Relevance to Our Study |
|-------|--------|---|-------------|------------|----------------------|

1. Present the matrix to the user for review.

Phase 4: Citation Management

Anti-Hallucination Protocol

This is the most critical part of the skill. Follow these rules without exception:

1. NEVER generate a reference from memory alone. Every reference must come from an API search result.
2. NEVER fabricate DOIs or PMIDs. If you cannot find a DOI/PMID, mark the reference as [UNVERIFIED - NEEDS MANUAL CHECK].
3. Cross-check every reference against the API result:
4. Author names (at least first author and last author)
5. Publication year
6. Journal name
7. Article title (exact match, not paraphrased)
8. Volume and pages (if available)
9. If any field does not match, flag the specific mismatch.
10. For DOI verification, use WebFetch with https://api.crossref.org/works/{DOI} to confirm the DOI resolves correctly.

BibTeX Generation

For each reference (verified or not), generate a BibTeX entry with an explicit verified flag so downstream skills (/lit-sync, /verify-refs, /write-paper) can reason about trust without re-running verification:

@article{FirstAuthorLastName_Year_ShortKey,
  author    = {Last1, First1 and Last2, First2 and Last3, First3},
  title     = {Full Title As Retrieved From Database},
  journal   = {Journal Name},
  year      = {2024},
  volume    = {310},
  number    = {2},
  pages     = {e234567},
  doi       = {10.1001/jama.2024.12345},
  pmid      = {12345678},
  verified  = {true},
  verified_by = {pubmed+crossref},
  verified_on = {2026-04-24},
}

verified flag values (required on every entry):

| Value | Meaning | Downstream behavior | |---|---|---| | true | DOI or PMID confirmed via PubMed/CrossRef; title, authors, year all match | Safe to cite; /write-paper citekey-only gate passes | | false | Parsed from text but API lookup failed or returned mismatch | /verify-refs flags as UNVERIFIED; manuscript MUST show [UNVERIFIED - NEEDS MANUAL CHECK] | | manual | User explicitly added despite lookup failure | Treated as verified=false by /verify-refs but suppresses repeat warnings |

verified_by lists the data source