zotero-pdf-upload

name	zotero-pdf-upload
description	Upload PDFs and manage items in a Zotero Web Library. Supports both personal and group libraries. Use when a user wants to add papers/PDFs to Zotero, organize collections, or manage their Zotero library through the API.

zotero-pdf-upload

Use this skill for direct Zotero workflows that must stay safe, explicit, and reusable.

First-time setup check (do this BEFORE any Zotero operation)

Before running any command, check if config.json exists in the skill root directory.

If config.json does NOT exist, stop and inform the user:

This skill is not configured yet. You need to set it up first.

What you need to prepare:

1. Zotero API Key — Create one at zotero.org/settings/keys
   • Go to Settings → Security → Create new private key
   • Enable: Allow library access, Allow notes access, Allow write access
   • If using group libraries, set Default Group Permissions to Read/Write
   • Click "Save Key" and copy the generated key
2. Zotero Library URL — Open your library in a browser and copy the URL:
   • Personal: https://www.zotero.org/<your-username>/library
   • Group: https://www.zotero.org/groups/<group-id>/<group-name>/library

Run this one-line setup command from the skill directory:

python scripts/setup.py "<YOUR_LIBRARY_URL>" "<YOUR_API_KEY>"

Do NOT proceed with any Zotero operations until config.json has been created.

Included resources

• scripts/zotero_workflow.py: CLI entrypoint for parse/inspect/match/create operations.
• scripts/zotero_client.py: Zotero API client, URL parser, secret loading, collection matching, item creation, PDF upload.
• tests/smoke_test_zotero_pdf_upload.py: no-network smoke tests.
• references/config.example.json: runtime config template (uses unified url field for both group and personal URLs).
• references/item.example.json: item metadata sample.
• references/approval-flow.md: approval checkpoints and write safety policy.

Required operating policy

1. Start with read-only steps (parse-url, list-collections, choose-collection).
2. If collection matching is weak or missing, return pending-new-collection-approval.
3. Create collections only via explicit action (create-collection --approve-create).
4. Create items only via explicit action (create-item --approve-write).
5. Only upload PDF if explicitly requested and config allows it.

Secret handling

Load Zotero API key in this order (safe default):

1. Environment variable: zotero.apiKeyEnv (default ZOTERO_API_KEY)
2. Secret file path: zotero.apiKeyPath
3. Inline config value: zotero.apiKey (least preferred)

Never print full API keys in output.

Security note: when resolving a personal library URL (username-based, no numeric ID), the skill calls GET https://api.zotero.org/keys/{apiKey} to look up the userID. This is the standard Zotero API pattern — the key appears in the URL and may be visible in server access logs. Use a least-privilege key and prefer env/file loading over inline config.

Core commands

Run from skill directory.

1) Parse a Zotero URL

python scripts/zotero_workflow.py parse-url --url "https://www.zotero.org/groups/6320165/my-group/library"

Personal library URL:

python scripts/zotero_workflow.py parse-url --url "https://www.zotero.org/myusername/library"

2) List collections (read-only)

python scripts/zotero_workflow.py list-collections --config ./tmp.config.json

Optional matching context:

python scripts/zotero_workflow.py list-collections \
  --config ./tmp.config.json \
  --title "Practical Alignment Evaluation for LLM Agents" \
  --tags alignment llm

3) Choose collection (read-only, no auto-create)

python scripts/zotero_workflow.py choose-collection \
  --config ./tmp.config.json \
  --item-json references/item.example.json

• If matched: status matched-existing-collection.
• If not matched: status pending-new-collection-approval + suggested name.

4) Explicitly create collection (write)

python scripts/zotero_workflow.py create-collection \
  --config ./tmp.config.json \
  --name "LLM Safety" \
  --approve-create

5) Explicitly create item metadata (write)

python scripts/zotero_workflow.py create-item \
  --config ./tmp.config.json \
  --item-json references/item.example.json \
  --auto-match-collection \
  --approve-write

Optional PDF attachment:

python scripts/zotero_workflow.py create-item \
  --config ./tmp.config.json \
  --item-json references/item.example.json \
  --collection-key ABCD1234 \
  --attach-pdf /path/to/paper.pdf \
  --approve-write

Approval points to enforce

• Never call write subcommands without explicit human confirmation.
• Do not auto-create missing collections during matching.
• If matching confidence is weak, stop and ask whether to create/select a collection.
• Treat attachment upload failure as reportable; do not silently ignore.

Smoke test

python tests/smoke_test_zotero_pdf_upload.py