zotero-literature

Zotero Literature Access

Access the project's Zotero reference collection via the local API, with PDF reading from local storage.

Prerequisites

• Zotero must be running locally (API at http://localhost:23119)
• The project's CLAUDE.md should specify the Zotero collection name under a ## Literature (Zotero) section

Configuration

Each project defines its Zotero collection name in CLAUDE.md. If not specified, ask the user which collection to use.

Look for this pattern in CLAUDE.md:

## Literature (Zotero)
Collection: <COLLECTION_NAME>

Core Script

All Zotero operations use the bundled script:

${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py

This script is stdlib-only Python — no dependencies needed.

Operations

1. Find Collection Key

Before any operation, resolve the collection name to its API key:

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py find-collection "<COLLECTION_NAME>"

Returns the collection key (e.g., TY7P7TFU) needed for all other commands. Cache this key for the session.

2. List All Items

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py list-items <COLLECTION_KEY>

Returns item keys, dates, and titles for all papers in the collection.

3. Search Items

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py search-items <COLLECTION_KEY> "<query>"

Searches titles, abstracts, and author last names.

4. Read a Paper's PDF

To read a paper, first find its local PDF path:

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py find-pdf <ITEM_KEY>

This returns the local filesystem path (e.g., ~/Zotero/storage/LDXEPPJR/Author - 2024 - Title.pdf). Then use the Read tool to read the PDF directly — do not use curl to download.

The PDF path follows this structure:

~/Zotero/storage/{ATTACHMENT_KEY}/{filename}.pdf

5. Export BibTeX

Export the entire collection as a .bib file:

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py export-bibtex <COLLECTION_KEY> <output_path>

For LaTeX papers, export to the paper directory (e.g., paper/main.bib).

6. Cross-Check Citations

Verify that all \cite{} keys in .tex files have corresponding entries:

python ${CLAUDE_SKILL_ROOT}/scripts/zotero_api.py cross-check <COLLECTION_KEY> <tex_directory>

Workflow Patterns

Reading a specific paper

1. Search for the paper: search-items <key> "prompt injection"
2. Get the item key from results
3. Find its PDF: find-pdf <ITEM_KEY>
4. Read the PDF using the Read tool with the returned path

Updating bibliography for LaTeX

1. Export BibTeX: export-bibtex <key> paper/main.bib
2. Recompile: pdflatex + bibtex + pdflatex + pdflatex

Verifying all references exist

1. List items: list-items <key>
2. Cross-check against tex: cross-check <key> paper/
3. Report any missing references

Important Notes

• Always read PDFs from local Zotero storage — never download via curl
• The Zotero API is read-only for item data; to add/modify items, use Zotero directly
• Collection key may change if the user recreates the collection — always resolve by name first
• If Zotero is not running, the script will report a clear error