Search, retrieve, and analyze papers from a Zotero library using pyzotero. Defaults to the Zotero Desktop local API; falls back to the Zotero Web API when local Zotero is unavailable.
Access Model
The bundled tool (scripts/zotero_tool.py) detects which mode to use automatically. Run it with uv run --script <skill-dir>/scripts/zotero_tool.py, where <skill-dir> is the directory containing this SKILL.md — substitute the real path. This resolves correctly regardless of which harness loaded the skill or where it is installed.
Load references/access-modes.md if you need fallback rules, credential setup details, or troubleshooting for access-mode issues.
Paper-Reading Workflow
Load references/paper-reading.md for the full step-by-step workflow with exact command invocations, JSON field names, disambiguation logic, parent-item hydration for full-text search hits, and troubleshooting.
Summary of steps:
- Search:
zotero_tool.py search "query"— plain metadata search;--fulltextfor indexed content (local or web). - Identify top-level item: inspect
data.itemTypeon each hit; attachment hits from--fulltextneed parent hydration viadata.parentItem. - Choose: present concise metadata when multiple top-level papers match; ask the user only if the intended paper cannot be inferred.
- Get PDF attachment key:
zotero_tool.py children ITEM_KEY→ find child withdata.contentType == "application/pdf". - Get PDF path:
zotero_tool.py pdf ATTACHMENT_KEY→ emits{"source": ..., "path": ...}. - Convert to markdown: invoke the
mistral-pdf-to-markdownskill with the PDF path; save toNotes/PaperInMarkdown/Author_Year_ShortTitle.md. - Read and analyze: read the converted file in sections — abstract and introduction first, then targeted sections.
Library Query Commands
| Goal | Command |
|---|---|
| List libraries (user + groups) | libraries |
| Metadata search (title/creator/year) | search "query" |
| Full-text search (indexed content; local or web) | search "query" --fulltext |
| Single item | item ITEM_KEY |
| Child items / attachments | children ITEM_KEY |
| Attachment full-text retrieval (one attachment) | fulltext ATTACHMENT_KEY |
| PDF path or download | pdf ATTACHMENT_KEY |
| All collections | collections |
| All tags | tags |
| DOI-to-key index | doiindex |
BibTeX export + master-.bib sync |
bibtex --item-key KEY (or --query "text" / --doi DOI) |
Insert a citation into a draft + sync .bib |
cite --item-key KEY --tex FILE --bib PATH (or --markdown FILE) |
| Render formatted references | bibliography --item-key KEY (default APA) |
| Health / access check | health |
All commands emit JSON. Add --help to any subcommand for parameter details.
Targeting a library. By default commands act on the user's own library ("My Library"). To act on a group library instead, run libraries first to get the group ids, then pass --library <group-id> (or --library group:<id>) — e.g. search "your query" --library <group-id>. Works on search, item, children, collections, tags, fulltext, doiindex, pdf, bibtex, cite, and bibliography.
Citations & BibTeX
bibtex, cite, and bibliography generate citations from selected library items, reusing the researcher's Better BibTeX (BBT) citekeys by default (so entries stay consistent with a BBT-maintained master .bib) and falling back to Zotero's built-in translator — with a key-mismatch warning — when BBT is unreachable. They share the --item-key / --query / --doi selection flags, --library targeting, and the dedup-append .bib sync.
Load references/bibtex-citations.md for command examples, the full flag list (--bib / --tex / --markdown / --marker / --style), the BBT-vs-built-in key model and fallback semantics, JSON fields, and troubleshooting.
Configuration
Credentials are read from environment variables or, when present, from Notes/.env. They are never printed to the agent transcript. Required variables for Web API mode: ZOTERO_LIBRARY_ID, ZOTERO_LIBRARY_TYPE (default user), ZOTERO_API_KEY. Local mode needs no credentials. See references/access-modes.md for full details.
Resources
references/paper-reading.md— full workflow with command examples, JSON field guide, disambiguation, and troubleshootingreferences/access-modes.md— local vs. web access rules, credential setup, fallback logic, troubleshootingreferences/bibtex-citations.md— load for thebibtex/cite/bibliographycommands: examples, full flag list, the Better BibTeX key model and fallback semantics, group-library targeting, and troubleshootingscripts/zotero_tool.py— unified pyzotero command surface (pinned to pyzotero 1.13.0 via PEP 723 inline metadata)