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. 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

1. 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:
CODEBLOCK0

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.
• INLINECODE6: Zotero API client, URL parser, secret loading, collection matching, item creation, PDF upload.
• INLINECODE7: no-network smoke tests.
• INLINECODE8: runtime config template (uses unified url field for both group and personal URLs).
• INLINECODE10: item metadata sample.
• INLINECODE11: approval checkpoints and write safety policy.

Required operating policy

1. 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. 1. Environment variable: zotero.apiKeyEnv (default ZOTERO_API_KEY)
2. Secret file path: INLINECODE20
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

CODEBLOCK1

Personal library URL:

CODEBLOCK2

2) List collections (read-only)

CODEBLOCK3

Optional matching context:

CODEBLOCK4

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

CODEBLOCK5

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

4) Explicitly create collection (write)

CODEBLOCK6

5) Explicitly create item metadata (write)

CODEBLOCK7

Optional PDF attachment:

CODEBLOCK8

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

CODEBLOCK9