Zotero

Manage Zotero reference libraries via the Web API. Search, list, add items by DOI/ISBN/PMID (with duplicate detection), delete/trash items, update metadata and tags, export in BibTeX/RIS/CSL-JSON, batch-add from files, check PDF attachments, cross-reference citations, find missing DOIs via CrossRef, and fetch open-access PDFs. Supports --json output for scripting. Use when the user asks about academic references, citation management, literature libraries, PDFs for papers, bibliography export, or Zotero specifically.

Security Scan

The skill's requirements and runtime instructions match its stated purpose (Zotero library management); the requested credentials and behaviors are proportionate and there are no signs of hidden exfiltration or unrelated privileges.

Purpose & Capability

Name/description (Zotero management) align with required env vars (ZOTERO_API_KEY, ZOTERO_USER_ID) and the included Python script that calls the Zotero Web API and external bibliography services (CrossRef, Unpaywall, Semantic Scholar). No unrelated credentials or odd binaries are requested.

Instruction Scope

SKILL.md instructions are narrowly scoped to Zotero operations (list/search/add/update/delete/export, PDF fetching, DOI lookups). Optional CROSSREF_EMAIL is documented and used for polite CrossRef requests. Commands reference files and URLs only where necessary (batch-add reads an identifier file; fetch-pdfs downloads OA PDFs). There are no instructions to read arbitrary system files, harvest unrelated environment variables, or transmit data to unexpected endpoints.

Install Mechanism

No install spec — instruction-only skill with a bundled Python script (scripts/zotero.py). This is low-risk compared with arbitrary downloads. The included script has no external dependency installs and uses standard library urllib; shipping a script is expected for CLI-style skills. Note: because code is included, users should review it before trusting.

Credentials

Only Zotero-specific credentials are required (ZOTERO_API_KEY and ZOTERO_USER_ID or ZOTERO_GROUP_ID). CROSSREF_EMAIL is optional and justified. The number and naming of env vars are proportional to the functionality described.

Persistence & Privilege

Skill does not request always:true and is user-invocable; it does not claim to modify other skills or system-wide agent settings. It runs on demand and requires the user to provide API credentials to operate.

Assessment

This skill appears coherent and limited to managing Zotero libraries. Consider the following before installing: 1) Only provide a Zotero API key with the minimum necessary permissions (create a write-restricted key if you only need read access). 2) The script will send your API key over the network to api.zotero.org (this is required for the functionality) — only use it if you trust the skill source. 3) The fetch-pdfs commands may download PDFs and optionally upload them to your Zotero storage; review and use --dry-run and --download-dir first. 4) Although the code is small and uses the Python standard library, you should review scripts/zotero.py if you want to be certain there is no unwanted behavior (the package source/homepage is unknown). 5) Because the skill is not always-enabled, it won't run automatically — you must invoke it (or grant the agent permission to invoke it).

Zotero Skill

Interact with Zotero personal or group libraries via the REST API v3.

Setup

Requires two environment variables:

ZOTERO_API_KEY   — Create at https://www.zotero.org/settings/keys/new
ZOTERO_USER_ID   — Found on the same page (numeric, not username)

For group libraries, set ZOTERO_GROUP_ID instead of ZOTERO_USER_ID.

Optional env var for CrossRef/Unpaywall polite pool (improves DOI lookup success rate):

CROSSREF_EMAIL   — Your email (optional; uses fallback if unset)

If credentials are missing, tell the user what's needed and link them to the key creation page.

CLI Script

All operations use scripts/zotero.py (Python 3, zero external dependencies).

python3 scripts/zotero.py <command> [options]

Commands

Command	Description	Example
items	List top-level items	zotero.py items --limit 50
search	Search by query	zotero.py search "cognitive load"
get	Full item details + attachments	zotero.py get ITEMKEY
collections	List all collections	zotero.py collections
tags	List all tags	zotero.py tags
children	List attachments/notes for item	zotero.py children ITEMKEY
add-doi	Add item by DOI (dedup enabled)	zotero.py add-doi 10.1234/example
add-isbn	Add item by ISBN (dedup enabled)	zotero.py add-isbn 978-0-123456-78-9
add-pmid	Add item by PubMed ID	zotero.py add-pmid 12345678
delete	Move items to trash (recoverable by default)	zotero.py delete KEY1 KEY2 --yes
update	Modify item metadata/tags	zotero.py update KEY --add-tags "new"
export	Export as BibTeX/RIS/CSL-JSON	zotero.py export --format bibtex
batch-add	Add multiple items from file	zotero.py batch-add dois.txt --type doi
check-pdfs	Report which items have/lack PDFs	zotero.py check-pdfs
crossref	Match citations vs library	zotero.py crossref bibliography.txt
find-dois	Find & add missing DOIs via CrossRef	zotero.py find-dois --limit 10
fetch-pdfs	Fetch open-access PDFs for items	zotero.py fetch-pdfs --dry-run

Global Flags

• --json — JSON output instead of human-readable (works with items, search, get)

Common Options

• --limit N — Max items to return (default 25)
• --sort FIELD — Sort by dateModified, title, creator, date
• --direction asc|desc — Sort direction
• --collection KEY — Filter by or add to collection
• --type TYPE — Filter by item type (journalArticle, book, conferencePaper, etc.)
• --tags "tag1,tag2" — Add tags when creating items
• --force — Skip duplicate detection on add commands

Workflows

Add a paper by DOI

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review"
# Warns if already in library. Use --force to override.

Duplicate detection: translates DOI to metadata, searches library by first author, compares DOI fields.

Bulk add from a file

# One identifier per line, # for comments
python3 zotero.py batch-add dois.txt --type doi --tags "imported"

Skips duplicates. Reports summary: added/skipped/failed.

Export bibliography

python3 zotero.py export --format bibtex --output refs.bib
python3 zotero.py export --format csljson --collection COLLKEY

Update tags/metadata

python3 zotero.py update ITEMKEY --add-tags "important" --remove-tags "unread"
python3 zotero.py update ITEMKEY --title "Corrected Title" --date "2024"
python3 zotero.py update ITEMKEY --doi "10.1234/example"
python3 zotero.py update ITEMKEY --url "https://example.com/paper"
python3 zotero.py update ITEMKEY --add-collection COLLKEY

Delete items

python3 zotero.py delete KEY1 KEY2 --yes           # Trash (recoverable, default)
python3 zotero.py delete KEY1 --permanent --yes    # Permanent delete

Cross-reference citations

python3 zotero.py crossref my-paper.txt

Extracts Author (Year) patterns from text and matches against library.

Find missing DOIs

# Dry run (default) — show matches without writing anything
python3 zotero.py find-dois --limit 20

# Actually write DOIs to Zotero
python3 zotero.py find-dois --apply

# Filter by collection
python3 zotero.py find-dois --collection COLLKEY --apply

Scans journalArticle and conferencePaper items missing DOIs, queries CrossRef, and matches by title similarity (>85%), exact year, and first author last name. Dry run by default — use --apply to write. Only patches the DOI field; never touches other metadata. 1s delay between CrossRef requests (polite pool with mailto).

Fetch open-access PDFs

# Dry run — show which PDFs are available and from where
python3 zotero.py fetch-pdfs --dry-run --limit 10

# Fetch and attach as linked URLs (no storage quota used)
python3 zotero.py fetch-pdfs --limit 20

# Also save PDFs locally
python3 zotero.py fetch-pdfs --download-dir ./pdfs

# Upload to Zotero storage instead of linked URL
python3 zotero.py fetch-pdfs --upload --limit 10

# Only try specific sources
python3 zotero.py fetch-pdfs --sources unpaywall,semanticscholar

Tries three legal OA sources in order: Unpaywall → Semantic Scholar → DOI content negotiation. By default creates linked URL attachments (no Zotero storage quota needed). Use --upload for full S3 upload to Zotero storage. Use --download-dir to also save PDFs locally.

Sources: unpaywall, semanticscholar, doi (default: all three)

Rate limits: 1s between Unpaywall/Semantic Scholar requests, 2s between DOI requests.

Scripting with JSON

python3 zotero.py --json items --limit 100 | jq '.items[].DOI'
python3 zotero.py --json get ITEMKEY | jq '.title'

Notes

• Zero dependencies — Python 3 stdlib only (urllib, json, argparse)
• Write operations require an API key with write permissions
• If Zotero translation server is down (503), DOI lookups fall back to CrossRef
• Input validation: DOIs must be 10.xxxx/... format. Item keys are 8-char alphanumeric (e.g., VNPN6FHT). ISBNs must be valid checksums.
• check-pdfs fetches all items; for large libraries (500+), this may be slow
• fetch-pdfs also processes all items — use --collection to scope for large libraries
• Rate limits are generous; batch-add includes 1s delay between items
• For common errors and troubleshooting, see references/troubleshooting.md