---

name: zotero-interface description: Comprehensive Zotero reference management interface for searching, retrieving metadata, and accessing full text of academic papers. Use when Claude needs to work with Zotero bibliographic databases for searching papers by topic/author/keywords, retrieving bibliographic metadata in APA7/other formats, accessing full text content, creating literature reviews/summaries, or managing academic references and citations.

Zotero Interface Skill

Overview

This skill provides comprehensive interface capabilities for working with Zotero reference management software through opencode's Zotero tools. It enables searching academic literature, retrieving bibliographic metadata, accessing full text content, and creating organized literature summaries.

Available Tools

1. zotero_cloud_zotero_search_items / zotero_local_zotero_search_items

Search for items in your Zotero library.

Parameters:

• query: Search query string
• qmode: Query mode - "titleCreatorYear" (default) or "everything"
• tag: Optional tag filter (supports boolean searches)
• limit: Maximum results (default: 10)

Usage:

// Use local for faster access to local Zotero database
zotero_local_zotero_search_items({
  query: "situated learning",
  qmode: "everything", 
  limit: 20
})

// Use cloud for remote access or when local Zotero isn't running
zotero_cloud_zotero_search_items({
  query: "situated learning",
  qmode: "everything", 
  limit: 20
})

When to use: Initial literature searches, finding papers by topic/author.

2. zotero_cloud_zotero_item_metadata / zotero_local_zotero_item_metadata

Get detailed metadata for a specific Zotero item.

Parameters:

• item_key: Zotero item key (from search results)

Returns: Title, authors, publication details, abstract, identifiers (DOI, URL, ISBN), tags.

When to use: Getting complete bibliographic information for citation formatting.

3. zotero_cloud_zotero_item_fulltext / zotero_local_zotero_item_fulltext

Get full text content of a Zotero item.

Parameters:

• item_key: Zotero item key

Returns: Full text content when available (may return error if not accessible).

When to use: Reading paper content for analysis, summarization, or extraction.

Cloud vs Local Tools

OpenCode provides two sets of Zotero tools for different use cases:

zotero_cloud_* Tools

• Purpose: Access Zotero via web API
• When to use:
  • Remote access to Zotero library
  • When local Zotero application isn't running
  • Accessing cloud-synced libraries
• Performance: Slower (network requests)
• Availability: Always available if Zotero web API is configured

zotero_local_* Tools

• Purpose: Direct access to local Zotero database
• When to use:
  • Faster local access
  • Direct database queries
  • Offline operation
  • Bulk processing
• Performance: Faster (direct SQLite access)
• Requirements: Local Zotero installation with database file

Tool Selection Guide

// Recommended pattern: Try local first, fallback to cloud
function searchZotero(query, options = {}) {
  try {
    // Try local first for speed
    return zotero_local_zotero_search_items({ query, ...options });
  } catch (localError) {
    // Fallback to cloud if local fails
    return zotero_cloud_zotero_search_items({ query, ...options });
  }
}

// Or choose based on use case
const useLocal = true; // Set based on your needs
const searchTool = useLocal ? zotero_local_zotero_search_items : zotero_cloud_zotero_search_items;
const results = searchTool({ query: "your search" });

Common Workflows

Workflow 1: Literature Search and Summary

1. Search for papers on a topic
2. Retrieve metadata for relevant items
3. Format references in APA7 or other styles
4. Access full text for detailed reading
5. Create structured summaries

Workflow 2: Citation Management

1. Search for specific papers by title/author
2. Extract bibliographic metadata
3. Format references for papers/reports
4. Create reference lists in proper citation style

Workflow 3: Literature Review Creation

1. Comprehensive search on research topic
2. Retrieve abstracts and metadata
3. Read full text of key papers
4. Create thematic summaries
5. Generate structured literature reviews

Best Practices

Search Strategies

• Start with broad searches using qmode: "everything"
• Refine with qmode: "titleCreatorYear" for precise matches
• Use tag filters for categorized searches
• Limit results to manageable numbers (10-20 for initial review)

Metadata Handling

• Always check for complete metadata (authors, date, publication)
• Extract DOI/URL for proper citation formatting
• Note abstract availability for quick screening
• Check for attached PDFs in storage directory

Full Text Access

• Full text retrieval may fail for some items
• Check Zotero storage directory for PDF attachments
• Use pdftotext command-line tool to extract text from PDFs
• Path: ~/Zotero/storage/

Reference Formatting

APA7 Format Examples:

• Journal article: Author, A. A., & Author, B. B. (Year). Title. Journal, Volume(Issue), Pages. DOI
• Book: Author, A. A. (Year). Title. Publisher.
• Chapter: Author, A. A., & Author, B. B. (Year). Chapter title. In E. E. Editor (Ed.), Book title (pp. xx-xx). Publisher.

Error Handling

Common Issues

1. Full text not accessible: Use PDF extraction from storage directory
2. Incomplete metadata: Cross-reference with identifiers (DOI/URL)
3. Search returns attachments: Search again with qmode: "titleCreatorYear" for main items
4. Item keys not found: Verify key format and search again
5. Tool not found errors: Ensure you're using correct tool names (zotero_cloud_* or zotero_local_* prefixes)
6. Local tools failing: Check if local Zotero is running and database is accessible
7. Cloud tools failing: Verify Zotero web API configuration and internet connection

PDF Extraction Commands

# Find PDFs in Zotero storage
find ~/Zotero/storage -name "*.pdf" -type f | head -20

# Extract text from PDF
pdftotext "/path/to/pdf" - | head -100

Examples

Example 1: Search and Format References

// Search for papers using local tools (faster)
const results = zotero_local_zotero_search_items({
  query: "machine learning",
  qmode: "titleCreatorYear",
  limit: 5
});

// Get metadata for each
results.forEach(item => {
  const metadata = zotero_local_zotero_item_metadata({
    item_key: item.key
  });
  // Format APA7 reference
});

// Alternative using cloud tools
const cloudResults = zotero_cloud_zotero_search_items({
  query: "machine learning",
  qmode: "titleCreatorYear",
  limit: 5
});

Example 2: Create Literature Summary

// Search topic using cloud tools (works remotely)
const papers = zotero_cloud_zotero_search_items({
  query: "artificial intelligence ethics",
  qmode: "everything"
});

// Retrieve abstracts and key info
const summaries = papers.map(paper => {
  const meta = zotero_cloud_zotero_item_metadata({
    item_key: paper.key
  });
  return {
    title: meta.title,
    authors: meta.authors,
    year: meta.date,
    abstract: meta.abstract
  };
});

// For local access with fallback
function getPaperMetadata(itemKey) {
  try {
    return zotero_local_zotero_item_metadata({ item_key: itemKey });
  } catch (error) {
    return zotero_cloud_zotero_item_metadata({ item_key: itemKey });
  }
}

Integration with Other Skills

Obsidian Integration

• Create literature notes in Obsidian markdown format
• Use wikilinks for paper connections
• Add tags for categorization
• Save to ~/Obsidian/Inbox/ or appropriate vault location

PDF Skill Integration

• Use PDF skill for advanced PDF processing
• Extract tables, images, or specific sections
• Combine with Zotero metadata

Storage Location

• Zotero database: ~/Zotero/zotero.sqlite
• PDF attachments: ~/Zotero/storage/
• Use find commands to locate specific papers

Quick Reference

Common Commands

# List PDFs in Zotero storage
find ~/Zotero/storage -name "*.pdf" -type f | head -30

# Search for specific author papers
find ~/Zotero/storage -name "*.pdf" -type f -exec basename {} \; | grep -i "author name"

# Extract text from PDF
pdftotext "path/to/pdf" - | head -200

Search Patterns

• Author search (local): zotero_local_zotero_search_items({query: "Smith", qmode: "titleCreatorYear"})
• Topic search (cloud): zotero_cloud_zotero_search_items({query: "topic keywords", qmode: "everything"})
• Tag filter (local with fallback):

try {
  zotero_local_zotero_search_items({query: "search", tag: "review"});
} catch {
  zotero_cloud_zotero_search_items({query: "search", tag: "review"});
}