Skip to content
Get packs

Guide · Agent skill

How to use the Pyzotero Zotero Library Manager agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The pyzotero skill gives an AI agent working knowledge of the pyzotero Python client, so it can read and change a Zotero reference library for you: searching items, managing collections and tags, uploading PDFs and exporting citations such as BibTeX. This guide is for researchers, developers and students who use Zotero and want an agent to do that bibliography work. By the end you will know how to install the skill, set up credentials, ask for tasks in plain language and avoid the main risks.

Pyzotero Zotero Library ManagerK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Check the requirements. Confirm you have Python 3.10 or newer and a Zotero account whose library you want to work with.
  2. 2Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  3. 3Install pyzotero. Run uv add "pyzotero==1.15.2" in your project, adding the cli or mcp extra if you need local access.
  4. 4Create your credentials. Get your User ID and create an API key at zotero.org/settings/keys, then store them as ZOTERO_LIBRARY_ID and ZOTERO_API_KEY.
  5. 5Make a read-only request. Ask the agent to list or search items in your library so you can confirm the connection works.
  6. 6Request a change with a review step. Ask for the edit or export and require the agent to show what it will change before it saves anything.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches it. This skill, named pyzotero, is built around SKILL.md, which describes when to use it, plus a set of reference files covering authentication, reading, searching, writing, collections, tags, attachments, exports, pagination, saved searches, the command-line interface and the MCP server.

Once installed, the agent can retrieve, create, update and delete items, collections, tags and attachments through the Zotero Web API v3 or the local Zotero API. The skill targets pyzotero 1.15.2.

  • Search and list items and collections
  • Create or edit references and manage tags
  • Upload PDF attachments
  • Export citations such as BibTeX
  • Search a running local Zotero desktop app, including indexed PDF text, when local access is enabled

Install the pyzotero skill in Claude

Download the ZIP for this skill from this page and unzip it. For a personal install, place the unzipped skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Single project: the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills

Set up Python, pyzotero and your Zotero credentials

The skill needs Python 3.10 or newer and pyzotero 1.15.2. The source recommends installing with uv. Add the base client for Web API work, or add the CLI or MCP extras if you want local Zotero access.

For remote private reads and writes, get your User ID and create an API key at zotero.org/settings/keys. For group libraries, the library ID is the integer after /groups/ in the group URL. Store the values in environment variables or a .env file, and keep them out of source code and version control.

  • Base client: uv add "pyzotero==1.15.2"
  • With CLI: uv add "pyzotero[cli]==1.15.2"
  • With MCP server: uv add "pyzotero[mcp]==1.15.2"
  • Variables: ZOTERO_LIBRARY_ID, ZOTERO_API_KEY, ZOTERO_LIBRARY_TYPE ('user' or 'group', default 'user')
ZOTERO_LIBRARY_ID=your_user_id ZOTERO_API_KEY=your_api_key ZOTERO_LIBRARY_TYPE=user # or "group"

How to trigger the skill with natural requests

You do not need to name the skill. The skill describes itself as applying when you work with Zotero libraries programmatically, manage bibliographic references, export citations, search library contents, upload PDF attachments or build research automation workflows. Ask for the outcome you want and name Zotero so the agent knows which library you mean.

Be specific about the library, the items and whether you want the agent to change anything. Requests that mention a collection, tag or export format give the agent the details it needs.

  • "Find all items in my Zotero library tagged reviewed and list their titles."
  • "Export the items in collection ABC123 as BibTeX."
  • "Add the reviewed tag to the items I found, then show me the changes before saving."
  • "Upload this PDF as an attachment to the Zotero item with key ITEMKEY."

Example workflow: search, export and check

A typical task starts with a read. The skill's quick-start pattern creates a Zotero client from your environment variables, lists top-level items and runs a keyword search. Reads are the safest place to begin because they do not change your library.

For exports, the skill shows how to request BibTeX from the Zotero client. The result is a bibtexparser database object, so the agent can print its entries or pass them on for further processing.

  • Read first, then ask for changes
  • Ask the agent to report what it would change before it writes
  • Check the output of any export before you use it in a manuscript
from pyzotero import Zotero zot = Zotero( library_id=os.environ['ZOTERO_LIBRARY_ID'], library_type=os.environ.get('ZOTERO_LIBRARY_TYPE', 'user'), api_key=os.environ['ZOTERO_API_KEY'], ) results = zot.items(q='machine learning', limit=20)

Safety: scripts, network access and writes

This skill runs scripts and uses the network. Remote use calls the Zotero Web API, and the skill's references document both remote and local options. The authentication reference advises keeping credentials in ZOTERO_* environment variables or a .env file, never in source code.

The agent can modify or delete items when it has a valid key. The skill's MCP server exposes writes only when started with --enable-writes, and permanent deletion also needs --enable-deletes. Local writes need Zotero 10+ and a separate local authorization. Test on a copy of your library before you let an agent edit anything, and be especially careful with shared group libraries.

  • Use a copy of your library for first runs
  • Require the agent to state the items it will change
  • Do not use a shared group library for bulk experiments
  • Keep API keys out of version control

Tips for reliable results

Pyzotero returns 100 items by default, while the API default is 25. To get a complete set, the skill recommends zot.everything(zot.items()). Keep this in mind when you ask for a full library export.

Write operations report results differently. update_item() reports a Boolean success, while create_items() returns per-item status with failed and successful entries. A non-empty response does not prove every item was created, so ask the agent to check the failed list and retry only those inputs.

  • Use everything() when you need every item, not just the first page
  • Check the failed list after creating items
  • Start with read-only requests to confirm your setup works

What people use it for

  • Search a Zotero library by keyword or tag and list matching titles for a literature review.
  • Export a collection as BibTeX for a manuscript bibliography.
  • Batch-clean tags or move items between collections in a student or lab library.
  • Upload PDF attachments to existing items in a research pipeline.
  • Build a script that syncs or exports Zotero references on a schedule.

Frequently asked questions

Is the pyzotero agent skill free?

The skill is published under the MIT License, as stated in its metadata. Pyzotero itself is a Python client that you install with uv or pip; this page does not state any price.

What do I need to use the pyzotero skill?

You need Python 3.10 or newer, pyzotero 1.15.2, and network access for remote Web API use. For private remote reads and writes you also need a Zotero API key and your user or group library ID.

Where do I install the pyzotero skill?

Unzip the downloaded skill into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. In the Claude apps you can also upload it under Settings → Capabilities → Skills.

Can the agent delete my Zotero items?

The skill says the agent can modify or delete items when it has a valid key, so limit access and test on a copy first. The MCP server only exposes writes with --enable-writes, and permanent deletion also requires --enable-deletes.

Do I need Zotero running to use the skill?

Not for remote Web API use, which needs your API key and library ID. The CLI and MCP server work with the local desktop app, which needs Zotero 7+ with local API access enabled for reads and Zotero 10+ with separate local authorization for writes.

How is pyzotero different from using the Zotero website or desktop app directly?

Pyzotero is a Python wrapper for the Zotero API v3, so an agent or script can make many changes in one run. The Zotero app is better for manual browsing and editing one item at a time. This guide does not benchmark them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already use Zotero and want an agent or script to search, tidy, export or upload to your library, and you are comfortable with Python and API keys. Skip it if you do not use Zotero, want no agent changing your references, or are working in a shared group library where mistakes would reach collaborators.

Download the skill