How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/agents365-ai/365-skills --skill zotero-dev-rulesBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Zotero Dev Rules
Zotero is an open-source reference manager. Developers extend it three ways: the Web API (https://api.zotero.org) for online libraries, plugins / the internal JavaScript API for the desktop client, and translators (JS scrapers/converters). Citations come from CSL styles via citeproc-js. This skill mirrors <https://www.zotero.org/support/dev> so you can answer Zotero dev questions and build integrations without re-fetching.
When to use this skill
- Reading from / writing to a Zotero library over the Web API (items, collections, tags, searches).
- File attachment upload, full-library or partial syncing, streaming (WebSocket) updates, OAuth.
- Building or debugging a Zotero plugin (7–10 bootstrapped era; Zotero 10 migration notes included); scripting the client via its JavaScript API / Run JavaScript.
- Finding an existing open-source plugin with similar functionality (to study its code) before building a new one.
- Writing or fixing a translator (web/import/export/search) and testing it in Scaffold.
- Creating or editing CSL citation styles; working with citeproc-js / citeproc-node.
Reference index — load the file you need
| File | Covers |
|---|---|
references/web-api.md | Base URL, auth/API keys, versioning, read requests, write requests, batch, file upload, item types/fields, syncing algorithm, streaming API, OAuth |
references/client-and-plugins.md | Internal JavaScript API (Zotero.Items/Item/Search/DB/Notifier), Run JavaScript, plugin development (Zotero 7 bootstrap/manifest), Zotero 10 migration notes, client coding entry points |
references/translators.md | Translator metadata block, detectWeb/doWeb/doImport/doExport/doSearch, scraping helpers (text/attr/ZU), HTTP requests, calling other translators, Scaffold/testing |
references/citation-styles.md | CSL, citeproc-js / citeproc-node, style repository, style editing, type mapping |
references/plugin-gallery.md | Snapshot of the zotero-chinese plugin-store registry (137 plugins by tag + deprecated list) — find similar open-source plugins and study their code before building |
Cheat sheet — Web API
# Read (public library needs no key). HTTPS only. Always pin the version.
curl -H "Zotero-API-Version: 3" -H "Zotero-API-Key: <KEY>" \
"https://api.zotero.org/users/<userID>/items?format=json&limit=25"
# Library prefix: /users/<userID> or /groups/<groupID>
# Common params: format=json|atom|bib|keys|versions, include=bib,citation, q=, itemType=, tag=,
# sort=, direction=, limit=1..100 (def 25), start=, since=<version>
# Response headers: Last-Modified-Version, Total-Results, Link (rel=next/last), Backoff
# Rate limits: honor Backoff; on 429 wait per Retry-After.
# Write (key with write access). Up to 50 objects/request. Must carry a version.
curl -X POST -H "Zotero-API-Key: <KEY>" -H "Content-Type: application/json" \
-H "If-Unmodified-Since-Version: <libVersion>" \
-d '[{"itemType":"book","title":"..."}]' \
"https://api.zotero.org/users/<userID>/items"
# PUT replaces (omitted fields cleared); PATCH merges (only changed fields). 412 = version mismatch.// Client internal JS API (Run JavaScript / plugin). Most DB/disk/network calls are async.
let item = new Zotero.Item('journalArticle');
item.setField('title', 'Example');
item.setCreators([{ creatorType: 'author', firstName: 'Jane', lastName: 'Doe' }]);
await item.saveTx(); // async, own transaction
let items = ZoteroPane.getSelectedItems(); // window scopeKey endpoints: /itemTypes /itemFields /itemTypeFields?itemType= /itemTypeCreatorTypes?itemType= /creatorFields /items/new?itemType= · full schema: https://api.zotero.org/schema.
Hard rules
- Always pin the API version with
Zotero-API-Version: 3(production) — never rely on the default.
Pass keys via the Zotero-API-Key header (or Authorization: Bearer), not the key= query param.
- Every write must carry a version (
If-Unmodified-Since-Versionheader or per-objectversion).
Missing → 428; mismatch → 412 Precondition Failed (re-fetch, merge, retry). Batch max 50 objects.
- Respect rate limits: obey the
Backoffheader proactively; on429waitRetry-Afterand slow down. - `mtime` is in milliseconds, not seconds. File upload is a 3-step flow (authorize → S3 → register);
new attachment uses If-None-Match: *, replacement uses If-Match: <previous-md5>.
- Client JS API is async:
awaitsaveTx()/getAsync()/Zotero.DB.executeTransaction(...).
Use saveTx() for single saves; wrap batches in one transaction. Get the Zotero object via chrome://zotero/content/include.js.
- Translators: metadata block + functions + test cases;
detectWebreturns a type /"multiple"/
false; finish items with item.complete(). Use promise helpers (requestText/JSON/Document). Licensed AGPL v3; submit via PR to zotero/translators. Test in Scaffold.
- Syncing is version-based: treat the library version as an opaque monotonic integer; use
?format=versions + ?since= to diff, store pristine JSON snapshots for 3-way merge, restart the pass if Last-Modified-Version changes mid-sync. New local objects start at version 0.
- Citation styles use CSL + citeproc-js; submit styles to the
citation-style-language/stylesrepo
per its CONTRIBUTING guidelines — don't hand-roll a citation formatter.



