SKILL.md
name: zotpilot description: >- Use when user mentions Zotero, academic papers, citations, literature reviews, research libraries, or wants to search/organize their paper collection. Also triggers on "find papers about...", "what's in my library", "organize my papers", "who cites...", "tag these papers". Always use this skill for Zotero-related tasks. license: MIT compatibility:
- Python 3.10+
- Zotero desktop (installed and run at least once)
ZotPilot
All script paths are relative to this skill's directory.
Step 1: Check readiness
Python command: Use python3 on Linux/macOS. On Windows, use python.
Run: python3 scripts/run.py status --json (Windows: python scripts/run.py status --json)
Parse the JSON output and follow the FIRST matching branch:
- Command fails entirely → Prerequisites (see
references/setup-guide.md) config_existsis false → First-Time Setup (seereferences/setup-guide.md)errorsis non-empty → First-Time Setup (note:warningslike API key not in env are OK if key was passed toregister)index_readyis false ordoc_countis 0 → go to Index below- All green → go to Research
Inline fallback (if agent cannot access references/):
python3 scripts/run.py setup --non-interactive --provider gemini
python3 scripts/run.py register
# Restart your AI agent, then ask again.
If any errors: run python3 scripts/run.py doctor for diagnostics.
Index (if doc_count = 0)
MCP tools are now available. Index the user's papers:
python3 scripts/run.py index
Indexing takes ~2-5 seconds per paper. Documents over 40 pages are skipped by default.
After indexing, check for "Skipped N long documents" — offer to index them with --max-pages 0.
Research (daily use)
Tool selection — pick the RIGHT tool first
| User intent | Tool | Key params |
|---|---|---|
| Find specific passages or evidence | search_papers |
query, top_k=10, section_weights, required_terms |
| Survey a topic / "what do I have on X" | search_topic |
query, num_papers=10 |
| Find a known paper by name/author | search_boolean |
query, operator="AND" |
| Find data tables | search_tables |
query |
| Find figures | search_figures |
query |
| Read more context around a result | get_passage_context |
doc_id, chunk_index, window=3 |
| See all papers | get_library_overview |
limit=100, offset=0 |
| Paper details | get_paper_details |
item_key |
| Who cites this? | find_citing_papers |
doc_id |
| Tag/organize one paper | add_item_tags, add_to_collection |
item_key |
| Batch tag/organize many papers | batch_tags, batch_collections |
items or item_keys, action |
| Search external databases for new papers | search_academic_databases |
query, limit=20 |
| Add a paper by DOI/arXiv/URL | add_paper_by_identifier |
identifier |
| Batch add papers from search results | ingest_papers |
papers (from search_academic_databases) |
Workflow chains
Literature review: search_topic → get_paper_details (top 5) → find_references → search_papers with section_weights
"What do I have on X?": search_topic(num_papers=20) → report count, year range, key authors, top passages
Organize by theme (batch): search_topic → create_collection → batch_collections(action="add", item_keys=[...]) → batch_tags(action="add", items=[...])
Find specific paper: search_boolean first (exact terms) → fallback to search_papers (semantic) → get_paper_details
Find and add new papers: search_academic_databases → review candidates with user → ingest_papers → index_library
Organize library (classification advisor): get_library_overview + list_collections + list_tags → analyze themes via search_topic → diagnose issues (uncategorized papers, inconsistent tags, oversized collections) → propose collection hierarchy + tag normalization → interview user for confirmation → batch_collections + batch_tags(add/remove) to execute
Output formatting
- Lead with paper title, authors, year, citation key
- Quote the relevant passage directly
- Include page number and section name
- Group results by paper, not by chunk
- Render table content as markdown tables
- NEVER dump raw JSON to the user
Error recovery
| Error | Fix |
|---|---|
| Empty results | Try broader query, or search_boolean for exact terms. Check get_index_stats |
| "GEMINI_API_KEY not set" | Expected if key was passed to register. Only re-run setup if provider is wrong |
| "ZOTERO_API_KEY not set" | Write ops need Zotero Web API credentials — see references/setup-guide.md |
| "Document has no DOI" | Cannot use citation tools for this paper |
| "No chunks found" | Paper not indexed — run index_library(item_key="...") |
Write operations (tags, collections)
Write tools require Zotero Web API credentials (ZOTERO_API_KEY + ZOTERO_USER_ID).
If missing, see Configure Zotero Web API in references/setup-guide.md.
Single-item: add_item_tags, set_item_tags, remove_item_tags, add_to_collection, remove_from_collection, create_collection
Batch (max 100 items): batch_tags(action="add|set|remove"), batch_collections(action="add|remove")
Partial failures are reported per-item without rollback.
For detailed parameter reference, see references/tool-guide.md.
For common issues and fixes, see references/troubleshooting.md.