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.