Zotero
The plugin talks to the Zotero desktop app on this machine through its local API. The Zotero side panel shows the library, item details and a PDF reader; the user can select items or text there and send them to you. Use this plugin's tools for everything in Zotero: never read or write zotero.sqlite or the storage folder directly, and do not scrape the Zotero app.
Items are addressed by 8-character keys such as 7ERC5QFW. A PDF is its own attachment item with its own key; tools that read PDFs accept either the parent item's key or the attachment's key.
1. Orient
- Call
list_collections first in a conversation about the library. It reports whether Zotero is running, whether writes are possible, the collection tree and saved searches.
zotero_not_running: Zotero is installed but closed; ask the user to start it (the panel has an Open Zotero button). zotero_not_installed: Zotero is not on this computer; tell the user, and offer to install it (section 7) — the panel can send you a setup request with the facts it detected. local_api_disabled: tell them to enable Settings → Advanced → Allow other applications on this computer to communicate with Zotero (the panel shows the steps). Do not retry in a loop.
2. Find and read
search_library searches titles, creators and years; with mode: "everything" it also searches PDF full text, notes and annotations. Filter by collection (key or name, Parent/Child for nested), tag or savedSearch.
get_item returns metadata, abstract, notes and the user's annotations. Read it before discussing a paper.
search_annotations finds the user's own highlights and comments across the library — use it for "what did I highlight / note about X".
read_fulltext returns PDF text with --- page N --- markers (physical page numbers; printed page labels are shown when they differ). Read a range with pages (e.g. "1-3"); long documents stop at maxChars and tell you where to continue. Prefer reading the abstract, introduction and the relevant sections over dumping whole books.
find_in_pdf locates a phrase and returns page numbers with context.
When you state what a paper says, ground it in text you have read and give the page (use the printed label when quoting for a citation, e.g. "p. 15"). If you have not read the relevant part, say so or read it.
3. Show evidence in the panel
highlight marks a passage in the PDF with your comment and opens the reader there. Copy the quote from read_fulltext / find_in_pdf output; short distinctive quotes (a sentence) work best; "start … end" spans a longer passage. On quote_not_found, re-read the page and copy the text exactly.
- Highlights last for the session. Save them into Zotero only when the user wants that (
save: true, or save_highlights), because it changes their library.
open_item opens a PDF at a page or quote, or an item's details. show_items lists the papers you used under a heading — do this after answering a literature question so the user can browse the sources.
4. What the user sends from the panel
- A message ending with
Zotero items: - [KEY] Title … refers to those items; a quoted passage ends with — “Title”, page N (Zotero item KEY, PDF KEY). Use those keys directly.
- Selections the user adds with Add to chat arrive as context, not as a request — use them when the user's next message refers to "this", "these papers" or "the selected passage".
5. Citations and .bib files
- For LaTeX or Markdown documents, use
export_bib to write a .bib file into the workspace (default references.bib) from a collection and/or keys, and cite with the citation keys it returns. Never invent citation keys; rerun export_bib after adding papers. Local file paths are removed from exports.
cite returns BibTeX / BibLaTeX / CSL-JSON / RIS entries, or formatted text in a CSL style (format: "text", style: "apa", "ieee", "chicago-author-date", …) with in-text citations.
6. Changing the library
Writes go through Zotero's own permission dialog (Zotero 8 or later). The first write asks the user in Zotero to Allow, Always Allow or Deny; tell them to look at Zotero and suggest Always Allow to avoid repeated prompts. On write_denied, stop and do not retry unless asked; on writes_unsupported, explain that this Zotero version is read-only.
add_item with a DOI or arXiv id (or link) fetches metadata from doi.org / arXiv and skips papers already in the library (same DOI). arXiv PDFs are attached automatically; for other papers pass pdfUrl only for a direct, openly available PDF link, or pdfPath for a PDF in the workspace — do not try to get around paywalls. For books, reports and anything without an identifier, pass metadata with an itemType and fields.
update_item sets fields and adds/removes tags and collections; add_note writes Markdown notes (child notes or standalone); create_collection makes collections; attach_pdf adds a PDF to an existing item.
- Ask before bulk changes (many items, removing tags or collections). The plugin cannot delete items; if the user wants something deleted, tell them to do it in Zotero.
- After writing, mention what changed and where (the panel shows the item).
7. Setting up Zotero
When the user asks you to install or update Zotero — usually with the panel's message Set up Zotero for the Zotero panel, which lists the operating system, where it looked and the package managers it found — follow its steps:
- Install Zotero 7 or later with the package manager the message names:
brew install --cask zotero (Homebrew), winget install --id DigitalScholar.Zotero -e --source winget --accept-source-agreements --accept-package-agreements, or flatpak install flathub org.zotero.Zotero. Otherwise use the official installer from https://www.zotero.org/download/. Ask before using sudo.
- Open Zotero once so it creates its profile (on macOS
open -a Zotero).
- The local API switch is a checkbox in Zotero's own settings: walk the user through Settings → Advanced → Allow other applications on this computer to communicate with Zotero (on Windows and Linux the menu is Edit → Settings…). Do not edit Zotero's preference files.
- The panel checks again every few seconds and connects by itself; then call
list_collections.
1---2name: zotero3description: Work with the user's Zotero library in the Zotero side panel — search papers, read their PDFs page by page and the user's own highlights, point at evidence with highlights in the PDF, cite (BibTeX / CSL styles) and keep a .bib file in the workspace, and add or organise items (arXiv / DOI import, notes, tags, collections). Use when the user mentions Zotero, their library, papers or references they have collected, citations or a .bib file, literature questions ("what do my papers say about…", "what did I highlight…"), or when the panel sends Zotero items or a quoted passage.4metadata:5 source: https://skillmd.com/skills/zai-org/zotero6---78# Zotero910The plugin talks to the Zotero desktop app on this machine through its local API. The Zotero side panel shows the library, item details and a PDF reader; the user can select items or text there and send them to you. Use this plugin's tools for everything in Zotero: never read or write `zotero.sqlite` or the `storage` folder directly, and do not scrape the Zotero app.1112Items are addressed by 8-character keys such as `7ERC5QFW`. A PDF is its own attachment item with its own key; tools that read PDFs accept either the parent item's key or the attachment's key.1314## 1. Orient1516- Call `list_collections` first in a conversation about the library. It reports whether Zotero is running, whether writes are possible, the collection tree and saved searches.17- `zotero_not_running`: Zotero is installed but closed; ask the user to start it (the panel has an *Open Zotero* button). `zotero_not_installed`: Zotero is not on this computer; tell the user, and offer to install it (section 7) — the panel can send you a setup request with the facts it detected. `local_api_disabled`: tell them to enable *Settings → Advanced → Allow other applications on this computer to communicate with Zotero* (the panel shows the steps). Do not retry in a loop.1819## 2. Find and read2021- `search_library` searches titles, creators and years; with `mode: "everything"` it also searches PDF full text, notes and annotations. Filter by `collection` (key or name, `Parent/Child` for nested), `tag` or `savedSearch`.22- `get_item` returns metadata, abstract, notes and the user's annotations. Read it before discussing a paper.23- `search_annotations` finds the user's own highlights and comments across the library — use it for "what did I highlight / note about X".24- `read_fulltext` returns PDF text with `--- page N ---` markers (physical page numbers; printed page labels are shown when they differ). Read a range with `pages` (e.g. `"1-3"`); long documents stop at `maxChars` and tell you where to continue. Prefer reading the abstract, introduction and the relevant sections over dumping whole books.25- `find_in_pdf` locates a phrase and returns page numbers with context.2627When you state what a paper says, ground it in text you have read and give the page (use the printed label when quoting for a citation, e.g. "p. 15"). If you have not read the relevant part, say so or read it.2829## 3. Show evidence in the panel3031- `highlight` marks a passage in the PDF with your comment and opens the reader there. Copy the quote from `read_fulltext` / `find_in_pdf` output; short distinctive quotes (a sentence) work best; `"start … end"` spans a longer passage. On `quote_not_found`, re-read the page and copy the text exactly.32- Highlights last for the session. Save them into Zotero only when the user wants that (`save: true`, or `save_highlights`), because it changes their library.33- `open_item` opens a PDF at a page or quote, or an item's details. `show_items` lists the papers you used under a heading — do this after answering a literature question so the user can browse the sources.3435## 4. What the user sends from the panel3637- A message ending with `Zotero items: - [KEY] Title …` refers to those items; a quoted passage ends with `— “Title”, page N (Zotero item KEY, PDF KEY)`. Use those keys directly.38- Selections the user adds with *Add to chat* arrive as context, not as a request — use them when the user's next message refers to "this", "these papers" or "the selected passage".3940## 5. Citations and .bib files4142- For LaTeX or Markdown documents, use `export_bib` to write a `.bib` file into the workspace (default `references.bib`) from a collection and/or keys, and cite with the citation keys it returns. Never invent citation keys; rerun `export_bib` after adding papers. Local file paths are removed from exports.43- `cite` returns BibTeX / BibLaTeX / CSL-JSON / RIS entries, or formatted text in a CSL style (`format: "text"`, `style: "apa"`, `"ieee"`, `"chicago-author-date"`, …) with in-text citations.4445## 6. Changing the library4647Writes go through Zotero's own permission dialog (Zotero 8 or later). The first write asks the user in Zotero to *Allow*, *Always Allow* or *Deny*; tell them to look at Zotero and suggest *Always Allow* to avoid repeated prompts. On `write_denied`, stop and do not retry unless asked; on `writes_unsupported`, explain that this Zotero version is read-only.4849- `add_item` with a DOI or arXiv id (or link) fetches metadata from doi.org / arXiv and skips papers already in the library (same DOI). arXiv PDFs are attached automatically; for other papers pass `pdfUrl` only for a direct, openly available PDF link, or `pdfPath` for a PDF in the workspace — do not try to get around paywalls. For books, reports and anything without an identifier, pass `metadata` with an `itemType` and fields.50- `update_item` sets fields and adds/removes tags and collections; `add_note` writes Markdown notes (child notes or standalone); `create_collection` makes collections; `attach_pdf` adds a PDF to an existing item.51- Ask before bulk changes (many items, removing tags or collections). The plugin cannot delete items; if the user wants something deleted, tell them to do it in Zotero.52- After writing, mention what changed and where (the panel shows the item).5354## 7. Setting up Zotero5556When the user asks you to install or update Zotero — usually with the panel's message *Set up Zotero for the Zotero panel*, which lists the operating system, where it looked and the package managers it found — follow its steps:5758- Install Zotero 7 or later with the package manager the message names: `brew install --cask zotero` (Homebrew), `winget install --id DigitalScholar.Zotero -e --source winget --accept-source-agreements --accept-package-agreements`, or `flatpak install flathub org.zotero.Zotero`. Otherwise use the official installer from https://www.zotero.org/download/. Ask before using `sudo`.59- Open Zotero once so it creates its profile (on macOS `open -a Zotero`).60- The local API switch is a checkbox in Zotero's own settings: walk the user through *Settings → Advanced → Allow other applications on this computer to communicate with Zotero* (on Windows and Linux the menu is *Edit → Settings…*). Do not edit Zotero's preference files.61- The panel checks again every few seconds and connects by itself; then call `list_collections`.