opencite - SKILL.md Agent Skill

name: opencite description: Use this skill for "search for papers", "find citations", "look up a DOI", "get BibTeX", "download PDF", "convert PDF to markdown", "find canonical papers", "convert identifiers", "batch download papers", "configure opencite", "literature review", "find related papers", "what papers cite this", "export references", "read this paper", or mentions of opencite, Semantic Scholar, OpenAlex, PubMed, academic literature search, citation management, or paper retrieval. version: 0.1.0

OpenCite CLI

OpenCite is a CLI tool for academic literature search and citation management. It aggregates results from Semantic Scholar, OpenAlex, PubMed, arXiv, and bioRxiv/medRxiv, deduplicates them, and outputs formatted results. It also supports PDF retrieval, PDF-to-markdown conversion, and batch operations.

Installation

# Recommended
uv pip install opencite

# Alternative: run without installing
uvx opencite --version

PDF conversion support (markitdown and markit-mistral) is included by default. When MISTRAL_API_KEY is set, markit-mistral handles math, tables, and complex layouts. Otherwise, markitdown (free, local) is the fallback.

For development:

uv sync --extra dev

Research Workflow

Follow this end-to-end workflow for literature research, paper retrieval, or reading material on a topic.

1. Search for relevant papers

Choose the search strategy based on the request:

Canonical/foundational papers: uvx opencite canonical "topic" --max 10
Recent or specific papers: uvx opencite search "query" --max 20 --sort citations
Citation graph exploration: uvx opencite cite "DOI" --direction both
Combine strategies when appropriate (e.g., canonical for background + search for recent work)

2. Evaluate and select papers

Review results considering citation count, relevance, recency, and open access availability. Present a summary and confirm which papers to retrieve.

3. Download and convert

For multiple papers (preferred): Save search results as JSON and use batch-fetch:

uvx opencite search "topic" --max 10 -f json -o results.json
uvx opencite batch-fetch --from-json results.json --convert -o ./papers --summary report.json

batch-fetch --convert automatically creates this directory structure:

papers/
├── pdf/          # downloaded PDFs
└── markdown/     # converted markdown files
    └── img/      # per-paper image directories (mistral only)

For individual papers:

uvx opencite pdf "10.1234/example" -o papers/pdf/ --convert

Note: pdf --convert places the markdown file next to the PDF and does not extract images. For the organized subdirectory layout with image extraction, use batch-fetch.

4. Read and synthesize

Read the converted markdown files for deeper analysis:

Summarize key findings across papers
Identify common themes and disagreements
When using batch-fetch, markdown is in papers/markdown/ and extracted images (markit-mistral only) are in per-paper subdirectories under papers/markdown/img/
Generate BibTeX for citation: uvx opencite lookup "DOI" -f bibtex --append-bib refs.bib

Command Summary

Command	Purpose
`search`	Find papers matching a query across multiple APIs
`lookup`	Look up a specific paper by DOI, PMID, PMCID, or other identifier
`cite`	Get citing/cited-by papers for a given identifier
`canonical`	Find the most-cited, foundational papers for a topic
`pdf`	Download a PDF for a paper by identifier
`convert`	Convert a local PDF file to markdown
`ids`	Convert between identifier types (DOI, PMID, PMCID)
`batch-fetch`	Download PDFs for multiple papers with optional conversion
`config`	Manage opencite configuration (init, show, path)

For full option listings, see references/cli-reference.md.

Configuration Essentials

Initialize configuration and check resolved values:

uvx opencite config init   # create ~/.opencite/config.toml template
uvx opencite config show   # display resolved config (keys masked)

Key environment variables:

SEMANTIC_SCHOLAR_API_KEY - Semantic Scholar API
PUBMED_API_KEY - NCBI/PubMed API
OPENALEX_API_KEY - OpenAlex API (required since Feb 2026)
MISTRAL_API_KEY - Enhanced PDF-to-markdown conversion (optional)

For full configuration details including publisher tokens and loading priority, see references/api-keys-and-config.md.

Error Handling

Rate limits: Semantic Scholar has aggressive rate limiting (1 req/sec). When rate limit errors occur, wait and retry.
Missing API keys: Commands warn about missing keys but still query available sources.
Timeouts: Retry the command or try a different source with --source.
PDF not found: opencite reports which sources were tried and why each failed. Papers behind paywalls may need institutional access or publisher API tokens.

References

CLI Reference - Complete option listings for all subcommands and the Python API
Common Workflows - Worked examples for typical usage patterns
API Keys and Configuration - Configuration loading, API keys, and publisher tokens