zotero-pdf-upload

# 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](https://www.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:
> ```bash
> 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 we...

# 📎 zotero-pdf-upload

[中文版](README_CN.md) | [GitHub](https://github.com/chenhaox/zotero-pdf-upload)

> 🤖 AI Skill — Let your LLM manage your [Zotero Web Library](https://www.zotero.org) directly: upload PDFs, create items, and match collections.

## ⚙️ Configure

You need two things: a **Zotero API Key** and your **Zotero Library URL**.

### Step 1 — Create a Zotero API Key

1. Log in to [zotero.org](https://www.zotero.org) and click **"Settings"** in the top-right corner.

2. In the Settings page, click **"Security"** in the left sidebar, then scroll down to the **Applications** section and click **"Create new private key"**.

3. Configure the key permissions:
   - **Personal Library**: ✅ Allow library access, ✅ Allow notes access, ✅ Allow write access
   - **Default Group Permissions**: Set to **Read/Write** (if you use group libraries)
   - Click **"Save Key"** to generate your `Zotero_API_Key`

4. **Copy the generated key** — you'll need it below.

### Step 2 — Get your Zotero Library URL

Open your Zotero library in a browser and copy the URL from the address bar:

- **Personal library**: `https://www.zotero.org/<your-username>/library`
- **Group library**: `https://www.zotero.org/groups/<group-id>/<group-name>/library`

For example:
```
# Personal
https://www.zotero.org/chenhaox/library

# Group
https://www.zotero.org/groups/6320165/fafu_robot/library
```

### Step 3 — Run setup

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

✅ **Done!** Restart your conversation and the LLM will automatically detect and use this skill.

> 💡 Just tell the AI: _"Upload this PDF to my Zotero collection X"_ — it will handle the rest.

---

## 🔧 What it does

- 🔗 Parse Zotero group/user URLs into `libraryType` + `libraryId`
- 📂 List and inspect existing collections
- 🎯 Heuristically match an item to an existing collection
- ✋ Require explicit approval before creating collections/ite...