Zotero Enhanced Library Manager

This skill provides a suite of scripts to interact with a Zotero library, covering the full document lifecycle: adding, searching, and reading. Includes enhanced metadata fetching for PDFs with DOI or arXiv IDs.

Storage Modes

The skill supports two storage configurations:

1. Zotero Cloud Storage (Default)

• - Uses Zotero's built-in cloud storage (300MB free)
• No WebDAV configuration needed
• File size limit: ~100MB per file
• Required variables: ZOTERO_USER_ID, INLINECODE1

2. WebDAV Storage

• - For users with their own WebDAV server (Synology, Nextcloud, etc.)
• No file size limits (subject to server constraints)
• Supports both imported_file (stored directly) and imported_url (referenced via WebDAV URL) attachment types
• Required variables: ZOTERO_USER_ID, ZOTERO_API_KEY, WEBDAV_URL, WEBDAV_USER, INLINECODE8

Authentication

All scripts require Zotero API credentials. Get your API key from: https://www.zotero.org/settings/keys

• - ZOTEROUSERID: Your Zotero user ID (found in profile URL)
• ZOTEROAPIKEY: Your Zotero API key
• WEBDAV_*: Only required if using WebDAV storage

1. Searching for Documents

Use scripts/search.sh to find items in the library by keyword.

Usage

# Ensure the script is executable
chmod +x scripts/search.sh

# Run the search
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/search.sh "your search query"

The script outputs a formatted list of matching items with their Key, needed for reading.

2. Reading a Document

Option A: Universal Reader (Recommended)

Use scripts/read_universal.sh to read documents from either storage mode.

Usage

CODEBLOCK1

Option B: WebDAV-only Reader

Use scripts/read.sh for WebDAV storage only (legacy).

3. Managing Notes

The skill now supports creating, reading, updating, and deleting notes in your Zotero library. Notes can be standalone or attached to parent items (documents).

Creating a Note

Use scripts/create_note.sh to create a new note with plain text content.

Usage

CODEBLOCK2

Options

• - --parent KEY: Attach note to a parent item (document key)
• INLINECODE15: Add a tag (can be used multiple times)
• INLINECODE16: Show steps without creating the note

The script automatically converts plain text to HTML for Zotero storage.

Reading a Note

Use scripts/read_note.sh to read a note and convert HTML back to plain text.

Usage

CODEBLOCK3

Output Formats

• - plain (default): Human-readable plain text
• INLINECODE19: Raw HTML content
• INLINECODE20: Full JSON item data

Updating a Note

Use scripts/update_note.sh to update existing notes with new content or tags.

Usage

CODEBLOCK4

Options

• - --replace: Replace note content (default)
• INLINECODE23: Append new content to existing note
• INLINECODE24: Add a tag (can be used multiple times)
• INLINECODE25: Remove a tag (can be used multiple times)
• INLINECODE26: Show steps without updating

The script includes version checking to prevent update conflicts.

Deleting a Note

Use scripts/delete_note.sh to delete notes safely with confirmation and backup options.

Usage

CODEBLOCK5

Safety Features

• - Confirmation prompt: Requires manual confirmation unless --no-confirm is used
• Backup option: Saves note content to ~/.zotero-backup/ before deletion
• Version checking: Prevents deletion if note was modified by another process
• Dry-run mode: Preview deletion without actually deleting

4. Adding a New Document

Option A: Universal Upload with Metadata Fetching (Recommended)

Use scripts/add_to_zotero_universal.sh for full metadata fetching and flexible storage.

Features

• - Automatic Metadata: Extracts DOI/arXiv ID, fetches metadata from Crossref/arXiv API
• Flexible Storage: Works with both Zotero cloud and WebDAV storage
• Smart Detection: Falls back to title extraction if no metadata found
• Dry-run mode: Use --dry-run to see what would be uploaded without making changes

Usage

CODEBLOCK6

Example: Adding a Paper with DOI

The universal script will:

1. 1. Extract DOI 10.1126/science.aec8352 from PDF
2. Query Crossref API for metadata (authors, journal, date, abstract, etc.)
3. Create Zotero item with complete metadata
4. Upload PDF via Zotero API (cloud) or WebDAV (if configured)

Option B: Enhanced Upload (Flexible Storage)

Use scripts/add_to_zotero_enhanced.sh for flexible storage with metadata fetching. Supports both Zotero cloud and WebDAV storage.

Option C: Basic Upload (Flexible Storage)

Use scripts/add_to_zotero.sh for flexible storage with title-only extraction. Supports both Zotero cloud and WebDAV storage.

5. Requirements

Core Dependencies

• - curl: HTTP requests
• INLINECODE36: JSON processing (for enhanced/universal scripts)
• INLINECODE37: PDF text extraction (from poppler-utils)
• INLINECODE38: File compression (for WebDAV mode)

Platform Support

All scripts are cross‑platform compatible (Linux and macOS). The universal scripts automatically detect platform‑specific commands (md5sum/md5, stat options).

Installation (Debian/Ubuntu)

CODEBLOCK7

Installation (macOS)

CODEBLOCK8

Quick Start

1. 1. Get Zotero API credentials from your Zotero settings
2. Install dependencies as shown above
3. Check dependencies (optional but recommended):

   bash scripts/check_deps.sh
   

1. 4. Test search functionality:

   ZOTERO_USER_ID="1234567" \
   ZOTERO_API_KEY="abc123def456" \
   bash scripts/search.sh "artificial intelligence"
   

1. 5. Add your first paper:

CODEBLOCK11

Changelog

v1.3.2 (2026‑03‑31)

• - Updated external services metadata in SKILL.md to resolve ClawHub scan errors
• Added external API URLs (Crossref, arXiv, Zotero API, WebDAV) to metadata for better compatibility

v1.3.1 (2026‑03‑30)

• - Fixed version conflict in Clawhub publication

v1.3.0 (2026‑03‑30)

• - Added note management support with four new scripts:

- create_note.sh: Create notes (plain text → HTML, optional parent, tags) - read_note.sh: Read notes (HTML → text, with format options) - update_note.sh: Update notes (append/replace, tag management, version checking) - delete_note.sh: Delete notes (with confirmation, backup option)

• - Implemented HTML ↔ plain text conversion for notes
• Added safety features: dry-run mode, confirmation prompts, backup before deletion
• Updated documentation with comprehensive Note Management section

v1.2.2 (2026‑03‑30)

• - Removed library organization tools (check_attachments.sh, find_duplicates.sh, analyze_tags.sh) per user request.
• Reverted documentation to focus on core metadata fetching and file management.

v1.2.1 (2026‑03‑30)

• - Added imported_url support in read_universal.sh for WebDAV‑stored PDFs.
• Implemented --dry‑run mode for add_to_zotero_universal.sh.
• Improved argument parsing and help messages.
• Updated security documentation.

v1.2.0 (2026‑03‑30)

• - Cross‑platform compatibility (Linux/macOS) with automatic detection of md5sum/md5 and stat variants.
• Added dependency checker script (check_deps.sh).
• Added OpenClaw metadata declaration for better integration.
• Added LICENSE and SECURITY.md files.
• Improved script safety headers and --help/--version flags.

Troubleshooting

"No PDF attachment found"

• - Ensure the item has an attached PDF (not just a URL)
• Check that attachment has linkMode: "imported_file" (stored directly) or linkMode: "imported_url" (referenced via WebDAV)
• If using WebDAV, the read_universal.sh script will search for both types automatically

"WebDAV authentication failed"

• - Verify WebDAV URL, username, and password
• Test WebDAV access with: INLINECODE62

"Crossref API failed"

• - Check internet connection
• Verify DOI is valid: INLINECODE63

"File too large for Zotero API"

• - Large files (>100MB) require WebDAV storage
• Set WEBDAV_URL, WEBDAV_USER, WEBDAV_PASS variables