zotero-paper-reader

name	zotero-paper-reader
description	Read and analyze academic papers from Zotero library. Use when the user requests to read, access, or analyze a paper by title, author, or topic from their Zotero library. Searches Zotero when Zotero tools are available, converts PDFs to Markdown, saves to Notes/PaperInMarkdown, and provides analysis.
user-invocable	true

Zotero Paper Reader

Overview

Read and analyze academic papers directly from the Zotero library. This skill handles the complete workflow from searching Zotero to converting PDFs to readable markdown format.

When to Use

Use this skill when the user requests to:

• "Read this paper from Zotero"
• "Find and read [paper title]"
• "Access [author name] paper"
• "Get the paper about [topic]"
• "Convert [paper] from Zotero to markdown"

Workflow

Step 1: Search Zotero Library

If Zotero tools are available in the current session, use them to search for the paper:

# Search by title, author, or keywords
mcp__zotero__zotero_search_items(query="paper title or author", limit=5)

Present the search results to the user if multiple papers are found. Get the item_key from the selected paper.

If Zotero tools are not available, ask the user for one of these instead:

• a Zotero attachment key
• a local PDF path
• enough information to locate the PDF manually in local Zotero storage

Step 2: Get PDF Attachment

Retrieve the PDF attachment information:

# Get child items (attachments) for the paper
mcp__zotero__zotero_get_item_children(item_key="ITEM_KEY")

Look for the attachment with type: application/pdf and note its Key (attachment key) and Filename.

Step 3: Get PDF File (Local or Download)

Use the bundled script to get the PDF - it automatically tries local storage first, then downloads if needed:

uv run python <skill-dir>/scripts/get_zotero_pdf.py ATTACHMENT_KEY

Replace <skill-dir> with the directory that contains this SKILL.md.

The script workflow:

1. First searches local Zotero storage (~/Zotero/storage/ATTACHMENT_KEY/)
2. If found locally, returns that path
3. If not found locally, downloads from Zotero web library using API
4. Retrieves original filename from Zotero metadata and downloads to /tmp/[original_filename]

Security note: The Zotero API key and library configuration are read directly from Notes/.env by the Python script and never exposed to the LLM. Required environment variables: ZOTERO_API_KEY, ZOTERO_LIBRARY_TYPE, ZOTERO_LIBRARY_ID.

Step 4: Convert to Markdown

Use the mistral-pdf-to-markdown skill (a separate plugin) if it is installed. Explicitly invoke that skill by name and convert PATH_TO_PDF to Notes/PaperInMarkdown/CLEAN_FILENAME.md.

If that skill is not installed, either:

• use another local PDF-to-text workflow that preserves enough structure for the user's request, or
• tell the user that the richer OCR path requires the mistral-pdf-to-markdown plugin

Filename convention: Create a clean filename from the paper metadata:

• Format: Author_Year_Title.md
• Example: Du_et_al_2023_Are_Intermediary_Constraints_Priced.md
• Replace spaces with underscores, remove special characters

Step 5: Read and Analyze

Read the converted markdown file in sections. Since academic papers are often large (>25k tokens), read strategically:

• Start with abstract and introduction (first 300-500 lines)
• Search for specific sections if needed
• Read specific sections based on user interest

Provide the user with:

1. Paper metadata (title, authors, publication year)
2. Brief summary of the abstract
3. Main findings or sections of interest
4. Offer to read specific sections or search for particular content

Example Usage

User request: "Read the paper 'Are Intermediary Constraints Priced' from my Zotero library"

Workflow:

1. Search: mcp__zotero__zotero_search_items(query="Are Intermediary Constraints Priced")
2. Get attachment: mcp__zotero__zotero_get_item_children(item_key="KPRQ2DLZ")
3. Get PDF: uv run python <skill-dir>/scripts/get_zotero_pdf.py 2HSELEHX
   • Returns local path if available, or downloads and returns temp path
4. Convert: Invoke mistral-pdf-to-markdown skill to convert [PDF_PATH] → Notes/PaperInMarkdown/Du_et_al_2023_Are_Intermediary_Constraints_Priced.md
5. Read the Markdown file in chunks, starting with the abstract and introduction
6. Summarize and offer to dive deeper into specific sections

Notes

• The skill works with both local and web Zotero libraries
• Automatic Zotero discovery requires Zotero tools in the current Codex session; otherwise the user must provide an attachment key or PDF path
• For web libraries, requires ZOTERO_API_KEY, ZOTERO_LIBRARY_TYPE, and ZOTERO_LIBRARY_ID in Notes/.env
• For local libraries, Zotero local API must be enabled in Zotero preferences
• Requires Mistral API key in Notes/.env for PDF conversion
• Converted markdown files include extracted images in images/ subfolder
• Large papers (>40k tokens) should be read in sections to avoid context limits

Resources

scripts/

• get_zotero_pdf.py - Unified script that tries local storage first, then downloads from web API if needed