zotero-skills

Zotero Skills — AI Coding Assistant Skill for Zotero CRUD

繁體中文版

Comprehensive Zotero library management via dual-API architecture (local read + web write). Works with any AI coding assistant that supports skills or custom instructions.

---

Overview

A skill that gives AI coding assistants full CRUD access to your Zotero library. Search, add, classify, annotate, and organize references programmatically — all from your terminal.

See Features below for the full list.

---

Features

Core CRUD Operations

• Search & Discovery — Full-text search, tag-based filtering, collection browsing, recent items
• Create Items — Add journal articles, books, conference papers, reports, theses, webpages with full metadata
• Update & Organize — Edit metadata, manage tags, move items between collections, batch operations
• Delete & Cleanup — Remove items, notes, collections; duplicate detection

Smart API Routing

• Dual-API architecture — Reads via fast local API (port 23119), writes via Zotero Web API
• Auto health check & fallback — Detects Zotero desktop status; seamless fallback to web-only mode
• Built-in rate limiting — safe_api_call() wrapper prevents API quota violations

Notes & Annotations

• Child notes — Attach rich HTML notes to any library item
• Reading notes — Create structured reading notes with sections
• Batch note creation — Add notes to multiple items programmatically

Collection Management

• Create & organize — Build hierarchical collection structures
• Bulk operations — Move/copy items between collections in batch
• Collection browsing — List and navigate collection trees

Integration Ready

• Framework-agnostic — Works with Claude Code, Codex CLI, Gemini CLI, Cursor, or any AI assistant
• Python library — Import zotero_client.py directly in any Python project
• JSON templates — Pre-built templates for all Zotero item types

---

Setup

Prerequisites

• Python 3.10+
• pyzotero: pip install pyzotero

API Credentials

1. API Key — Generate at https://www.zotero.org/settings/keys. Enable "Allow library access" and "Allow write access".
2. Library ID — Found on the same page under "Your userID for use in API calls"

Configuration

Copy config.example.json to config.json and fill in your credentials:

cp config.example.json config.json

{
  "zotero_api_key": "YOUR_API_KEY",
  "zotero_library_id": "YOUR_LIBRARY_ID",
  "zotero_library_type": "user",
  "collections": {
    "my_collection": "COLLECTION_KEY"
  }
}

Note: config.json is gitignored to protect your API key. Never commit credentials.

Installation

Install via the ai-research-skills Claude Code marketplace:

claude plugin marketplace add WenyuChiou/ai-research-skills
claude plugin install zotero-skills@ai-research-skills --scope user

Migrating from a previous cp -r / git clone install? SKILL.md moved from the repo root to skills/zotero-skills/SKILL.md for marketplace auto-discovery. The old cp -r zotero-skills/ ~/.claude/skills/zotero-skills/ layout no longer loads (Claude Code scans only one level deep). Remove the old copy (rm -rf ~/.claude/skills/zotero-skills) and run the marketplace install above.

---

Non-Claude CLI Adaptation

This skill was developed for Claude Code but works with any AI assistant.

CLI	How to load the skill
Claude Code	Place in ~/.claude/skills/ or .claude/skills/ — auto-loaded
Codex CLI	Pass SKILL.md as a context file via -C or include in task prompt
Gemini CLI	Include SKILL.md in system prompt or project context
Cursor / Windsurf	Add SKILL.md to .cursor/rules or equivalent rules file
Any other tool	Paste relevant sections of SKILL.md into your system prompt

---

Project Structure

~/.claude/skills/zotero-skills/        # Global install path
├── SKILL.md              # Full CRUD reference for AI assistants
├── config.example.json   # Template for API credentials
├── config.json           # Your credentials (gitignored)
├── scripts/
│   ├── zotero_client.py  # ZoteroDualClient + helpers
│   └── add_literature.py # Batch import script
├── references/
│   ├── api-reference.md  # Zotero API endpoint docs
│   └── item-types.md     # JSON templates for all item types
├── docs/                 # Example screenshots
├── README.md             # English
└── README_zh-TW.md       # 繁體中文

---

Dual-API Architecture

Zotero exposes two APIs with different capabilities. This skill routes automatically.