zotero-search

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.8.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

## 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` |
| `--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.

## Output Format

Search results include:

```json
{
  "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).

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