Zotero (overview)
This skill enables safe, repeatable programmatic access to a user's Zotero account (personal and group libraries) using Zotero API keys. It provides example scripts, a small Python client wrapper around pyzotero, a CLI example, and guidance for secure configuration and packaging as an AgentSkill.
Triggers (must be present in description)
Activate this skill when the user asks things like: "search my Zotero for X", "add a note to item ", "upload PDF to Zotero", "create item in Group library ", or any request explicitly referencing Zotero library management.
Preconditions
The user provides a Zotero API key (developer key) and the target userID and/or groupID(s).
Credentials are resolved with the following priority (first match is used):
- Command-line argument flags (e.g.,
--user 12345 or --group 99999)
- Environment variables:
ZOTERO_API_KEY, ZOTERO_USER_ID, ZOTERO_GROUP_ID
ZOTERO_API_KEY is required (must be set as an environment variable or passed explicitly). Do NOT store raw keys in the repository.
Implementation uses the pyzotero Python library by default. A Node.js variant can be added later if desired.
If environment variables are set, no user input is needed—the skill executes automatically with the configured credentials.
Supported features
- Search items by title, creator/author, tags, year, fulltext, or arbitrary field combinations; supports sorting and pagination.
- Create new items (journalArticle, book, conferencePaper, thesis, etc.) with standard Zotero metadata fields (title, creators, date, abstractNote, tags, publicationTitle, DOI, ISBN, extra, etc.).
- Update item metadata by sending a field-level patch/diff.
- Add / edit / delete item-level notes (Zotero item notes). PDF internal annotations/highlights are out-of-scope (advanced extension).
- Upload attachments (local PDF) and link attachments (external URLs) to items; include attachment metadata (title, contentType).
- Delete single items or perform batch operations (with explicit confirmation and dry-run options).
- List available groups and collections for the authenticated key.
- Logging of key operations to local logs (no API keys or full PDF contents in logs by default).
Bundled resources (recommended)
scripts/
- pyzotero_client.py — lightweight wrapper around pyzotero with functions: auth, search_items, create_item, update_item, add_note, upload_attachment, delete_items, list_groups, list_collections.
- cli.py — example CLI: zotero search|create|update|note|upload|delete — accepts JSON input or flags.
- install.sh - installs pyzotero and dependencies in a virtual environment; includes instructions for setting ZOTERO_API_KEY.
references/
- zotero-api.md — concise Zotero Web API reference (endpoints used, rate limits, common error codes).
- usage-examples.md — mapping from natural-language triggers to API actions and sample payloads.
- security.md — recommendation to store API key in environment variables or a local secrets manager; do not commit keys.
assets/
- config.example.json — example configuration (no keys): { api_key_env: "ZOTERO_API_KEY", user_id: null, group_ids: [] }
Design & implementation notes
- Default language: Python (pyzotero). All write operations require an explicit confirmation flag (e.g., --yes) to avoid accidental destructive changes.
- Batch delete defaults to a dry-run; a second confirmation is required to execute.
- Attachment upload flow: POST to /users//items//children with file data, then update parent-child relationships as required (see zotero-api.md).
- Error handling: API errors are translated into readable messages including suggested recovery actions (retry, check permissions, check rate limits).
- Logging: by default logs to ~/.config/zotero-skill/logs/operations.log. Logs omit ZOTERO_API_KEY and do not store full PDF contents.
Example natural-language triggers
When environment variables (ZOTERO_API_KEY, ZOTERO_USER_ID, ZOTERO_GROUP_ID) are configured, the skill executes automatically without additional user prompts:
- "Search my Zotero for 'deep learning' and sort by year"
- "Add a note to item 12345: 'Expand methods section with ablation study'"
- "Upload /home/user/papers/foo.pdf as an attachment to item 67890"
- "Create a new journalArticle in Group library 99999 with title X, authors Y, DOI Z"
When using the CLI without ZOTERO_USER_ID or ZOTERO_GROUP_ID set, you can override via arguments:
python cli.py search --q "term" --user 12345 (overrides ZOTERO_USER_ID env var)
Security
Required environment variables (in the execution environment):
export ZOTERO_API_KEY="<your_api_key_here>"
export ZOTERO_USER_ID="<your_user_id>" # For personal library (optional if using groups)
export ZOTERO_GROUP_ID="<your_group_id>" # For group library (optional if using personal)
Do not commit real keys to source control. Prefer OS keyrings or secret managers for long-term storage.
Once these environment variables are set, the skill will use them automatically without requiring user input.
Notes for integrators
- If a JavaScript/Node implementation is required, add a node/ subfolder and provide equivalent wrappers and examples.
- Advanced feature: support parsing and syncing PDF annotations or highlights — requires downloading PDFs and using annotation parsers and is out-of-scope for initial release.
1---2name: zotero-23description: Zotero integration for both personal and Group libraries. search items (title/author/tags/year/fulltext/combined queries), create/update/delete items and metadata, add/edit item-level notes, perform bulk operations, and sync attachments (upload PDF or link URL). Trigger when user asks to search their Zotero, add or modify an item/note, upload attachments, or manage group libraries.4metadata:5 source: https://skillmd.com/skills/modbender/zotero-26 clawdbot:7 primaryEnv: ZOTERO_API_KEY8 requires:9 env:10 - ZOTERO_API_KEY11 - ZOTERO_USER_ID12 - ZOTERO_GROUP_ID13 config:14 requiredEnv:15 - ZOTERO_API_KEY16 example: "config = { env = { ZOTERO_API_KEY = \"xxxx\"; ZOTERO_USER_ID = \"12345\"; }; };"17---1819# Zotero (overview)2021This skill enables safe, repeatable programmatic access to a user's Zotero account (personal and group libraries) using Zotero API keys. It provides example scripts, a small Python client wrapper around pyzotero, a CLI example, and guidance for secure configuration and packaging as an AgentSkill.2223## Triggers (must be present in description)2425Activate this skill when the user asks things like: "search my Zotero for X", "add a note to item <id>", "upload PDF to Zotero", "create item in Group library <id>", or any request explicitly referencing Zotero library management.2627## Preconditions2829- The user provides a Zotero API key (developer key) and the target userID and/or groupID(s).30- **Credentials are resolved with the following priority** (first match is used):31 1. Command-line argument flags (e.g., `--user 12345` or `--group 99999`)32 2. Environment variables: `ZOTERO_API_KEY`, `ZOTERO_USER_ID`, `ZOTERO_GROUP_ID`33 34- `ZOTERO_API_KEY` is **required** (must be set as an environment variable or passed explicitly). Do NOT store raw keys in the repository.35- Implementation uses the pyzotero Python library by default. A Node.js variant can be added later if desired.36- If environment variables are set, no user input is needed—the skill executes automatically with the configured credentials.3738## Supported features3940- Search items by title, creator/author, tags, year, fulltext, or arbitrary field combinations; supports sorting and pagination.41- Create new items (journalArticle, book, conferencePaper, thesis, etc.) with standard Zotero metadata fields (title, creators, date, abstractNote, tags, publicationTitle, DOI, ISBN, extra, etc.).42- Update item metadata by sending a field-level patch/diff.43- Add / edit / delete item-level notes (Zotero item notes). PDF internal annotations/highlights are out-of-scope (advanced extension).44- Upload attachments (local PDF) and link attachments (external URLs) to items; include attachment metadata (title, contentType).45- Delete single items or perform batch operations (with explicit confirmation and dry-run options).46- List available groups and collections for the authenticated key.47- Logging of key operations to local logs (no API keys or full PDF contents in logs by default).4849## Bundled resources (recommended)5051- scripts/52 - pyzotero_client.py — lightweight wrapper around pyzotero with functions: auth, search_items, create_item, update_item, add_note, upload_attachment, delete_items, list_groups, list_collections.53 - cli.py — example CLI: zotero search|create|update|note|upload|delete — accepts JSON input or flags.54 - install.sh - installs pyzotero and dependencies in a virtual environment; includes instructions for setting ZOTERO_API_KEY.5556- references/57 - zotero-api.md — concise Zotero Web API reference (endpoints used, rate limits, common error codes).58 - usage-examples.md — mapping from natural-language triggers to API actions and sample payloads.59 - security.md — recommendation to store API key in environment variables or a local secrets manager; do not commit keys.6061- assets/62 - config.example.json — example configuration (no keys): { api_key_env: "ZOTERO_API_KEY", user_id: null, group_ids: [] }6364## Design & implementation notes6566- Default language: Python (pyzotero). All write operations require an explicit confirmation flag (e.g., --yes) to avoid accidental destructive changes.67- Batch delete defaults to a dry-run; a second confirmation is required to execute.68- Attachment upload flow: POST to /users/<userID or groupID>/items/<itemKey>/children with file data, then update parent-child relationships as required (see zotero-api.md).69- Error handling: API errors are translated into readable messages including suggested recovery actions (retry, check permissions, check rate limits).70- Logging: by default logs to ~/.config/zotero-skill/logs/operations.log. Logs omit ZOTERO_API_KEY and do not store full PDF contents.7172## Example natural-language triggers7374When environment variables (`ZOTERO_API_KEY`, `ZOTERO_USER_ID`, `ZOTERO_GROUP_ID`) are configured, the skill executes automatically without additional user prompts:7576- "Search my Zotero for 'deep learning' and sort by year"77- "Add a note to item 12345: 'Expand methods section with ablation study'"78- "Upload /home/user/papers/foo.pdf as an attachment to item 67890"79- "Create a new journalArticle in Group library 99999 with title X, authors Y, DOI Z"8081When using the CLI without `ZOTERO_USER_ID` or `ZOTERO_GROUP_ID` set, you can override via arguments:82- `python cli.py search --q "term" --user 12345` (overrides ZOTERO_USER_ID env var)8384## Security8586- Required environment variables (in the execution environment):8788 ```bash89 export ZOTERO_API_KEY="<your_api_key_here>"90 export ZOTERO_USER_ID="<your_user_id>" # For personal library (optional if using groups)91 export ZOTERO_GROUP_ID="<your_group_id>" # For group library (optional if using personal)92 ```9394- Do not commit real keys to source control. Prefer OS keyrings or secret managers for long-term storage.95- Once these environment variables are set, the skill will use them automatically without requiring user input.9697## Notes for integrators9899- If a JavaScript/Node implementation is required, add a node/ subfolder and provide equivalent wrappers and examples.100- Advanced feature: support parsing and syncing PDF annotations or highlights — requires downloading PDFs and using annotation parsers and is out-of-scope for initial release.