Zotero Scholar GuideSAFE

🔬 A curated collection of 23,000+ agent skills for empirical research across 8 social science disciplines. | 精选 23,000+ AI Agent 技能库,覆盖8大社会科学学科的实证研究。CoPaper.AI 20分钟完成一篇可复现的规范实证论文,并支持用户上传 Skills。-- Maintained by CoPaper.AI from Stanford REAP.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: zotero-scholar-guide
description: "Save papers with metadata to Zotero via its API programmatically"
metadata:
  openclaw:
    emoji: "📚"
    category: "writing"
    subcategory: "citation"
    keywords: ["zotero", "reference manager", "citation management", "API", "metadata", "bibliography", "paper organization"]
    source: "https://github.com/zotero/zotero"
---

# Zotero Scholar Guide

## Overview

Zotero is the most widely used open-source reference manager in academia, offering a powerful combination of local storage, cloud sync, browser integration, and a comprehensive API. While most researchers use Zotero through its desktop application and browser connector, the Zotero API enables programmatic access that is essential for automated research workflows—saving papers from scripts, batch-importing search results, organizing libraries algorithmically, and integrating reference management into custom research pipelines.

This skill covers using the Zotero Web API to create, read, update, and organize library items programmatically. It is designed for researchers who want to automate parts of their reference management workflow: importing papers from arXiv or OpenAlex searches directly into Zotero, auto-tagging papers based on content analysis, organizing collections programmatically, and exporting citations in various formats.

The skill complements the existing `zotero-api` skill by focusing specifically on practical scholar workflows—the common patterns a researcher uses when integrating Zotero into their daily literature management.

## Authentication and Setup

### Obtaining API Credentials

1. Log in to your Zotero account at https://www.zotero.org
2. Navigate to Settings > Feeds/API (https://www.zotero.org/settings/keys)
3. Click "Create new private key"
4. Set permissions:
   - Personal Library: Read/Write access
   - Default Group Permissions: Read/Write (if you use group libraries)
   - Allow access to notes (recommended)
5. Save the API key securely

```bash
# Store your credentials as environment variables
export ZOTERO_API_KEY=your-zotero-key   # from zotero.org/settings/keys
export ZOTERO_USER_ID="your_user_id"  # Found on the API keys page
```

### Testing Your Connection

```bash
# Verify API access
curl -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items?limit=5&format=json" \
  | python3 -m json.tool | head -20
```

If you see your recent library items, authentication is working correctly.

## Saving Papers to Zotero

### Adding a Single Paper by DOI

The simplest way to add a well-cataloged paper is by DOI. Zotero can resolve DOI metadata automatically:

```python
import requests
import os

API_KEY = os.environ["ZOTERO_API_KEY"]
USER_ID = os.environ["ZOTERO_USER_ID"]
BASE_URL = f"https://api.zotero.org/users/{USER_ID}"
HEADERS = {
    "Zotero-API-Key": API_KEY,
    "Content-Type": "application/json"
}

def add_paper_by_doi(doi):
    """Resolve DOI metadata and add to Zotero."""
    # Step 1: Get metadata from DOI via Crossref
    cr_resp = requests.get(
        f"https://api.crossref.org/works/{doi}",
        headers={"User-Agent": "ResearchClaw/1.0 (mailto:[email protected])"}
    )
    cr_data = cr_resp.json()["message"]

    # Step 2: Build Zotero item
    item = {
        "itemType": "journalArticle",
        "title": cr_data.get("title", [""])[0],
        "creators": [
            {"creatorType": "author", "firstName": a.get("given", ""),
             "lastName": a.get("family", "")}
            for a in cr_data.get("author", [])
        ],
        "abstractNote": cr_data.get("abstract", ""),
        "DOI": doi,
        "url": f"https://doi.org/{doi}",
        "date": cr_data.get("published-print", {}).get("date-parts", [[""]])[0][0],
        "publicationTitle": cr_data.get("container-title", [""])[0],
        "volume": cr_data.get("volume", ""),
        "issue": cr_data.get("issue", ""),
        "pages": cr_data.get("page", ""),
        "tags": [{"tag": "auto-imported"}]
    }

    # Step 3: POST to Zotero
    resp = requests.post(
        f"{BASE_URL}/items",
        headers=HEADERS,
        json=[item]
    )

    if resp.status_code == 200:
        print(f"Added: {item['title']}")
        return resp.json()
    else:
        print(f"Error: {resp.status_code} - {resp.text}")
        return None

# Usage
add_paper_by_doi("10.1038/s41586-023-06747-5")
```

### Adding arXiv Papers

arXiv papers often lack DOIs. Use the arXiv API to fetch metadata:

```python
import feedparser

def add_arxiv_paper(arxiv_id):
    """Fetch arXiv metadata and add to Zotero."""
    feed = feedparser.parse(
        f"http://export.arxiv.org/api/query?id_list={arxiv_id}"
    )
    entry = feed.entries[0]

    item = {
        "itemType": "preprint",
        "title": entry.title.replace("\n", " "),
        "creators": [
            {"creatorType": "author",
             "firstName": name.rsplit(" ", 1)[0] if " " in name else "",
             "lastName": name.rsplit(" ", 1)[-1]}
            for name in [a.name for a in entry.authors]
        ],
        "abstractNote": entry.summary.replace("\n", " "),
        "url": entry.link,
        "date": entry.published[:10],
        "repository": "arXiv",
        "archiveID": f"arXiv:{arxiv_id}",
        "tags": [
            {"tag": "arxiv"},
            {"tag": entry.arxiv_primary_category["term"]}
        ]
    }

    resp = requests.post(
        f"{BASE_URL}/items",
        headers=HEADERS,
        json=[item]
    )
    if resp.status_code == 200:
        print(f"Added arXiv paper: {item['title'][:80]}")
    return resp

# Usage
add_arxiv_paper("2301.07041")
```

### Batch Import from Search Results

When you run a literature search and want to import all results into Zotero:

```python
def batch_import(papers, collection_key=None):
    """Import a list of paper dicts into Zotero.
    Zotero API accepts up to 50 items per request.
    """
    batch_size = 50
    for i in range(0, len(papers), ba

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.