Zotero Enhanced

Manages the Zotero library. Supports adding new PDF documents with automatic metadata fetching (Crossref/arXiv), searching for existing items, reading attach...

Security Scan

The skill's files, declared requirements, and runtime instructions are consistent with a Zotero library manager that fetches metadata and handles WebDAV; nothing in the package indicates hidden endpoints, unexplained credential requests, or behavior outside that purpose.

Purpose & Capability

Name/description (manage Zotero library, add/search/read notes, fetch Crossref/arXiv metadata) match the code and declared requirements. Required env vars are Zotero credentials (and optional WebDAV vars) which are appropriate for the stated functionality. Required binaries (curl, jq, pdftotext, zip/unzip, md5sum|md5) align with script operations.

Instruction Scope

Runtime instructions and scripts stay within the stated purpose (calling Zotero, Crossref, arXiv, optional WebDAV). Scripts read/write local files (temporary files in /tmp; delete_note.sh may create backups under $HOME/.zotero-backup). This is expected for import/backup operations, but users should be aware that backups are written to their home directory and that the skill will send data (PDFs, DOIs) to the listed external services.

Install Mechanism

No remote install/download is performed by the skill (no install spec). All code is bundled with the skill; there are no downloads from untrusted URLs or archive extraction steps. This is low risk from an install-mechanism perspective.

Credentials

The only required credentials are ZOTERO_USER_ID and ZOTERO_API_KEY (primaryEnv: ZOTERO_API_KEY), with optional WEBDAV_* vars for WebDAV. This is proportionate. Minor note: scripts use other standard env/state (HOME for backups, /tmp); these are reasonable but not explicitly listed in requires.config. Also scripts call optional tools (xmllint, stat) that are not listed in the top-level required bins.

Persistence & Privilege

always:false and user-invocable:true. The skill does not request permanent elevated presence or modify other skills or system-wide agent settings. Its filesystem writes are limited to temporary files and an optional backup directory in the user's home.

Assessment

This package appears to do what it says: manage Zotero items, fetch metadata from Crossref/arXiv, and optionally use WebDAV. Before installing, consider: (1) Only provide ZOTERO_API_KEY and ZOTERO_USER_ID from a trusted Zotero account; the skill will use them to create/read/update items. (2) If you use WebDAV, only point WEBDAV_URL to servers you control/trust — files are uploaded/downloaded to that endpoint. (3) The scripts write temporary files to /tmp and (if you request backups) create files under $HOME/.zotero-backup — review and secure/clean those as needed. (4) Minor inconsistencies: some scripts reference xmllint/stat behavior that isn't listed in the required binaries, and SECURITY.md claims 'set -euo pipefail' though many scripts set -e and pipefail but not -u; these are implementation hygiene issues rather than indicators of malice. If you need higher assurance, request a signed release or a maintainer contact and review the full untruncated scripts (xmllint/other optional dependencies) before use.

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, ZOTERO_API_KEY

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, WEBDAV_PASS

Authentication

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

• ZOTERO_USER_ID: Your Zotero user ID (found in profile URL)
• ZOTERO_API_KEY: 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

chmod +x scripts/read_universal.sh

# For Zotero cloud storage:
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/read_universal.sh "ITEM_KEY"

# For WebDAV storage (add WebDAV variables):
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
WEBDAV_URL="<url>" \
WEBDAV_USER="<user>" \
WEBDAV_PASS="<pass>" \
bash scripts/read_universal.sh "ITEM_KEY"

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

chmod +x scripts/create_note.sh

# Create a standalone note:
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/create_note.sh "My important research notes"

# Create a note attached to a document:
bash scripts/create_note.sh --parent "ITEM_KEY" "Meeting notes about this paper"

# Create a note with tags:
bash scripts/create_note.sh --tag research --tag to-read "Follow up on this paper"

Options

• --parent KEY: Attach note to a parent item (document key)
• --tag TAG: Add a tag (can be used multiple times)
• --dry-run: 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

chmod +x scripts/read_note.sh

# Read as plain text (default):
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/read_note.sh "NOTE_KEY"

# Read as HTML:
bash scripts/read_note.sh --format html "NOTE_KEY"

# Read as JSON (full item data):
bash scripts/read_note.sh --format json "NOTE_KEY"

Output Formats

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

Updating a Note

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

Usage

chmod +x scripts/update_note.sh

# Replace note content:
echo "New content" | \
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/update_note.sh --replace "NOTE_KEY"

# Append to existing content:
echo "Additional notes" | \
bash scripts/update_note.sh --append "NOTE_KEY"

# Add tags:
bash scripts/update_note.sh --tag important --tag to-read "NOTE_KEY"

# Remove tags:
bash scripts/update_note.sh --remove-tag obsolete "NOTE_KEY"

Options

• --replace: Replace note content (default)
• --append: Append new content to existing note
• --tag TAG: Add a tag (can be used multiple times)
• --remove-tag TAG: Remove a tag (can be used multiple times)
• --dry-run: 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

chmod +x scripts/delete_note.sh

# Delete with confirmation:
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/delete_note.sh "NOTE_KEY"

# Delete without confirmation (use with caution):
bash scripts/delete_note.sh --no-confirm "NOTE_KEY"

# Backup before deleting:
bash scripts/delete_note.sh --backup "NOTE_KEY"

# Dry-run to see what would be deleted:
bash scripts/delete_note.sh --dry-run "NOTE_KEY"

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

chmod +x scripts/add_to_zotero_universal.sh

# Zotero cloud storage (no WebDAV needed):
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
bash scripts/add_to_zotero_universal.sh "/path/to/paper.pdf"

# WebDAV storage:
ZOTERO_USER_ID="<user_id>" \
ZOTERO_API_KEY="<api_key>" \
WEBDAV_URL="<url>" \
WEBDAV_USER="<user>" \
WEBDAV_PASS="<pass>" \
bash scripts/add_to_zotero_universal.sh "/path/to/paper.pdf"

Example: Adding a Paper with DOI

The universal script will:

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
• jq: JSON processing (for enhanced/universal scripts)
• pdftotext: PDF text extraction (from poppler-utils)
• zip: 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)

sudo apt-get update
sudo apt-get install -y curl jq poppler-utils zip

Installation (macOS)

brew install curl jq poppler zip

Quick Start

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
   

4. Test search functionality:

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

5. Add your first paper:

   ZOTERO_USER_ID="1234567" \
   ZOTERO_API_KEY="abc123def456" \
   bash scripts/add_to_zotero_universal.sh "~/Downloads/paper.pdf"
   

Changelog

v1.3.5 (2026‑04‑27)

• Fixed Chinese error text in add_to_zotero_universal.sh (get_filesize function)
• Enhanced create_note.sh HTML conversion: handles **bold**, bullet lists (-, *, numbered), and inline line breaks (<br>)
• Enhanced read_note.sh HTML→plaintext conversion: decodes <br>, <strong>, <b>, <ul>/<li>, and HTML entities

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: curl -u user:pass "https://your.webdav.server/"

"Crossref API failed"

• Check internet connection
• Verify DOI is valid: curl "https://api.crossref.org/works/10.1126/science.aec8352"

"File too large for Zotero API"

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