Zotero Find

Locating the script

The search script lives at scripts/zotero_find.py in the same directory as this SKILL.md. When installed via npx skills add, this resolves to ~/.agents/skills/zotero-find/scripts/zotero_find.py (with a symlink into ~/.claude/skills/ for Claude Code).

In all the examples below, zotero_find.py stands for that absolute path. A reliable way to find it in any runtime:

SCRIPT="$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}")")/scripts/zotero_find.py"
# or, if you know the canonical install location:
SCRIPT="$HOME/.agents/skills/zotero-find/scripts/zotero_find.py"

Step 1: Classify the query

Step 2: Run the search

Topic / keyword (default, runs metadata + full-text in parallel and merges):

uv run zotero_find.py --query "multigrid" --limit 15

Author query:

uv run zotero_find.py --query "Stomakhin" --mode metadata --limit 5

Content question (full-text only):

uv run zotero_find.py --query "vertex patch smoother" --mode fulltext --limit 10

Scoped to a collection:

uv run zotero_find.py --query "multigrid" --collection HN3XX96E --limit 10

List all collections:

uv run zotero_find.py --list-collections

Recent additions (no query needed):

uv run zotero_find.py --recent 10

Filter by tag:

uv run zotero_find.py --query "flow" --tag "CFD"

Filter by year (2020 onward):

uv run zotero_find.py --query "multigrid" --since 2020

Combine filters:

uv run zotero_find.py --query "multigrid" --tag "FEM" --since 2022 --limit 10

Step 3: Read the JSON output

The script prints JSON to stdout with this shape:

{
  "query": "multigrid",
  "mode": "both",
  "collection": null,
  "count": 7,
  "results": [
    {
      "key": "DFXGQV8D",
      "title": "Multigrid p-Robustness at Jacobi Speeds...",
      "creators": ["Wichrowski"],
      "year": "2025",
      "itemType": "preprint",
      "collections": ["HN3XX96E"],
      "abstract": "Vertex-patch smoothers are essential...",
      "match": "metadata+fulltext"
    },
    ...
  ]
}

The match field is the ranking signal:

• metadata+fulltext — found in both searches; highest confidence, top of list
• metadata — title/creator match; precise
• fulltext — mentions the term inside the PDF; present in --mode fulltext or --mode both

Results are pre-sorted by confidence. Trust the order.

Step 4: Collection scoping (conditional)

Only scope to a collection if the query mentions a domain keyword that might match a collection name. Otherwise skip this step.

1. Run --list-collections
2. Client-side match the collection names against the query (substring or fuzzy match)
3. If a relevant collection is found, ask the user: "I see a 'Multigrid Methods' collection — should I search there, or across your whole library?"
4. If scoping, re-run the search with --collection <KEY>

Skip scoping entirely when: the query is very specific (exact title, author, citekey) or the user says "across my whole library".

Step 5: Present

Scannable list, one item per line block. Include the 8-character Zotero key, author(s), year, title, and the match mode:

Found 3 items:

1. Wichrowski (2025) — Multigrid p-Robustness at Jacobi Speeds: Efficient Matrix-Free Implementation... DFXGQV8D · match: metadata + fulltext · collection: Multigrid Methods

2. Ghia et al. (1982) — High-Re solutions for incompressible flow using the Navier-Stokes equations and a multigrid method FA87NP3W · match: metadata + fulltext

3. Zhang et al. (2010) — Chebyshev pseudospectral multigrid... DEF456 · match: fulltext only (mentions multigrid in a cited section)

Always include the 8-character Zotero key. zotero-read and zotero-compare need it. Do not extract PDF content in this skill — that's zotero-read's job.

Fallback tips

• Compound queries often miss. If --query "Hu MLS-MPM" returns nothing, break it up: try --query "Hu" and --query "MLS-MPM" separately.
• If metadata returns nothing, try --mode fulltext — the term may only exist inside PDF text.
• Sanity-check connectivity with any trivial query (e.g., --query "the" --limit 3). If that fails, verify ZOTERO_API_KEY and ZOTERO_USER_ID.
• HTTP 403 → wrong/expired API key. HTTP 404 → wrong user ID. HTTP 429 → rate-limited; wait and retry.

Exit codes

• 0 — success
• 1 — HTTP error (network, auth, not-found)
• 2 — missing env vars or invalid arguments