AgentSkillsCN

zotero-api-skill

Zotero HTTP API 辅助工具，可用于下载、获取、搜索、创建以及更新 Zotero 项目。适用于以编程方式同步或管理 Zotero 项目；默认使用 ZOTERO_USER 和 ZOTERO_API_KEY 环境变量。

SKILL.md
--- frontmatter
name: zotero-api-skill
description: Zotero HTTP API helper for downloading, fetching, searching, creating, and updating Zotero items. Use when syncing or managing Zotero items programmatically; defaults to ZOTERO_USER and ZOTERO_API_KEY environment variables.

Zotero API Skill

Overview

Use scripts/zotero_cli.py to perform deterministic Zotero API operations: download items to disk, fetch a single item, search items, create new items, or write updated metadata back to Zotero. The script reads ZOTERO_USER (user ID) and ZOTERO_API_KEY from the environment unless overridden by flags.

Quick Start

Download all items (skip attachments by default):

bash
zotero-api-skill/scripts/zotero_cli.py download --output-dir ./output

Fetch a single item as JSON:

bash
zotero-api-skill/scripts/zotero_cli.py get --key ABCD1234

Update an item from a JSON file:

bash
zotero-api-skill/scripts/zotero_cli.py update --key ABCD1234 --input ./output/ABCD1234/original.json

Search items by query:

bash
zotero-api-skill/scripts/zotero_cli.py search --query "transformer retrieval" --limit 10

Create an item from data JSON:

bash
zotero-api-skill/scripts/zotero_cli.py create --input ./new_item.json --data-only

Tasks

Download items

Use download to save each item into its own directory under --output-dir. The script writes original.json and a dated original-MM-DD.json snapshot.

Common options:

  • •--limit: page size for Zotero API pagination.
  • •--max-items: stop after N items.
  • •--include-attachments: include attachment items.
  • •--start: start offset for pagination.
  • •--no-snapshot: skip the dated snapshot file.

Fetch a single item

Use get with --key to print the item JSON to stdout, or pass --output to save it to a file.

Search items

Use search with --query to run a Zotero quicksearch. Optional filters: --qmode, --item-type, --tag, --start, --limit.

Create items

Use create with --input to POST new item data. The input file can be:

  • •A list of data objects (array), or
  • •A single data object, or
  • •A list of full Zotero items (with a top-level data field).

Update item metadata

Use update with --key and --input to PUT item metadata. The input file can be:

  • •A full Zotero item JSON (with a top-level data field), or
  • •A data-only object (set --data-only to force this).

Prefer updating from a freshly fetched item so required fields like itemType, key, and version stay consistent.

Notes

  • •The script uses Zotero API version 3 and retries on transient HTTP errors.
  • •If you need the same update flow as the repo, edit the data payload and use update to write back.