Zotero Search Skill

Search and retrieve documents from a local Zotero library using the pyzotero CLI. Extends to Semantic Scholar for discovering related papers, citations, and references beyond the local collection.

Prerequisites

• Zotero desktop application running with local API enabled
• pyzotero CLI installed (pip install pyzotero[cli] or uv tool install "pyzotero[cli]@latest" if they have uv in their $PATH). The Pyzotero version must be >=1.9.0
• Test connection: pyzotero test

Quick Start

If the user has uvx in their path, you can prefix these commands with uvx --from "pyzotero[cli]@latest"

# Basic search
pyzotero search -q "climate change" --json

# Search specific collection
pyzotero search -q "neural" --collection ABC123 --json

# Full-text search (searches PDF contents)
pyzotero search -q "methodology" --fulltext --json

# Filter by item type
pyzotero search -q "adaptation" --itemtype journalArticle --json

# Paginate through results
pyzotero search -q "climate" --limit 20 --offset 20 --json

# Filter by tag
pyzotero search -q "review" --tag "to-read" --json

Local Search Options

Option	Description	Example
-q	Search query (required)	-q "machine learning"
--collection	Limit to collection key	--collection ABC123
--itemtype	Filter by type	--itemtype journalArticle
--fulltext	Search PDF contents	--fulltext
--limit	Max results	--limit 50
--offset	Skip N results (for pagination)	--offset 20
--tag	Filter by tag	--tag "to-read"
--json	JSON output (required for local search)	--json

Item Types

Common types: journalArticle, book, bookSection, conferencePaper, report, thesis, preprint

Run pyzotero itemtypes for the full list.

Collections

Run pyzotero listcollections to see all collections with their keys and names.

Direct Item Access

Retrieve specific items directly by key:

# Get a single item by key
pyzotero item ABC123 --json

# Get child items (attachments, notes) for a parent item
pyzotero children ABC123 --json

# Get multiple items at once (batch lookup)
pyzotero subset ABC123 DEF456 GHI789 --json

The subset command is more efficient than multiple item calls when fetching several items.

Tags

List and filter by tags in your library:

# List all tags in library
pyzotero tags

# List tags with usage counts (JSON output)
pyzotero tags --json

# Search filtered by tag
pyzotero search -q "methodology" --tag "important" --json

Full-Text Content

Extract indexed full-text content from attachments:

# Get full-text content from an attachment
pyzotero fulltext ATTACHMENT_KEY

Note: The fulltext command requires the key of an attachment item (PDF, etc.), not the parent item. Use pyzotero children PARENT_KEY --json first to find attachment keys.

Output Format

Search results include:

{
  "count": 12,
  "items": [
    {
      "key": "ABC123",
      "itemType": "journalArticle",
      "title": "Paper Title",
      "creators": ["Author One", "Author Two"],
      "date": "2023-06-15",
      "publication": "Journal Name",
      "doi": "10.1234/example",
      "pdfAttachments": ["file:///path/to/paper.pdf"]
    }
  ]
}

Key fields: title, creators, date, publication, doi, abstractNote, pdfAttachments

Semantic Scholar Integration

Extend beyond local library with Semantic Scholar commands:

Command	Purpose	Example
related	Find similar papers	pyzotero related --doi "10.1234/..."
citations	Find citing papers	pyzotero citations --doi "10.1234/..."
references	Find referenced papers	pyzotero references --doi "10.1234/..."
s2search	Search S2 by keyword	pyzotero s2search -q "topic"

Note: Semantic Scholar commands output JSON by default and do not require (or support) the --json flag.

Key Options

• --min-citations N: Filter to papers with N+ citations
• --sort citations: Sort by citation count (most cited first)
• --check-library/--no-check-library: Cross-reference with local Zotero

Finding Influential Work

# Search for highly-cited papers on a topic
pyzotero s2search -q "deep learning" --sort citations --min-citations 100

# Find seminal works related to a paper you have
pyzotero related --doi "10.1234/example" --min-citations 200

# Find influential papers citing a foundational work
pyzotero citations --doi "10.1234/example" --min-citations 50

Cross-Referencing

All Semantic Scholar results include inLibrary: true/false indicating whether each paper exists in local Zotero (matched by DOI).

Performance tip: Use --no-check-library for faster results when you don't need cross-referencing, or use the DOI index caching pattern (see references/semantic-scholar.md) for efficient repeated lookups.

For detailed Semantic Scholar documentation, see references/semantic-scholar.md.

Research Assistant Behaviour

After presenting search results:

1. Analyse patterns: Identify themes, temporal patterns, coverage gaps
2. Suggest next steps: Offer to cluster results, find gaps, create reading lists
3. Respect preferences: Act like a diligent postdoc, not overeager

For detailed output formatting and proactive analysis patterns, see references/output-guidelines.md.

Error Handling

Error	Solution
Connection error	Ensure Zotero desktop is running
Empty results	Try broader terms, remove filters, use --fulltext
Paper not found (S2)	DOI may not be indexed; try s2search by title
Rate limit exceeded (S2)	Wait a moment and retry

Reference Files

For detailed guidance beyond this quick reference:

Semantic Scholar

• references/semantic-scholar.md - Complete S2 command reference, workflows for finding seminal works, literature expansion patterns

Research Analysis

• references/research-patterns.md - Thematic clustering, gap analysis, trajectory analysis, reading list prioritisation, methodology surveys

Output and Presentation

• references/output-guidelines.md - Result formatting by count, proactive analysis patterns, common usage examples

Technical Recipes

• references/jq-recipes.md - Set operations (intersection, union, difference), temporal filtering, processing recipes for grouping, counting, extracting