kerim/zotero-code-execution

Overview

This skill provides a safe, code-execution pattern to run comprehensive, multi-strategy searches of a Zotero library. It fetches large candidate sets, deduplicates and ranks results in Python, and returns only a compact, relevant set to the LLM context. Use it to avoid context overload and crashes while getting thorough coverage.

How this skill works

The skill exposes a SearchOrchestrator and ZoteroLibrary helpers that run semantic, keyword, and tag-based searches in parallel. Code fetches large result pools per strategy (50–100+ items), deduplicates by item key, applies filtering rules, ranks items by relevance, and returns only the top N. All heavy processing happens in the local execution environment so the language model receives only the final, trimmed results.

When to use it

• When you need comprehensive Zotero searches without crashing the LLM context
• When combining semantic, keyword and tag searches and wanting automatic deduplication
• When searching multiple spellings, languages, or synonyms (use multi-term OR pattern)
• When you need to filter or rank results programmatically (date ranges, item types, tags)
• When iteratively refining search results or exploring topic intersections

Best practices

• Start with comprehensive_search(query, max_results=20) for most queries
• Fetch broadly then filter in code rather than limiting early (use search_limit_per_strategy to tune depth)
• For multi-term OR queries, search each term separately and merge by key to avoid Zotero treating terms as AND
• Wrap calls in try/except and return user-friendly messages on failure
• Prefer returning only top results to LLM context; keep full candidate sets inside code execution

Example use cases

• Quick literature find: comprehensive_search("embodied cognition", max_results=20) returns ranked top papers
• Recent filtered search: fetch 100 items for "machine learning" then filter by journalArticle and 2020–2025 date range
• Author scan: search titleCreatorYear for "Kahneman" and sort by date to list papers you have
• Multi-spelling lookup: run separate searches for alternate spellings or languages (e.g., Atayal and 泰雅族), deduplicate and re-rank
• Intersection search: find items appearing in both "cognition" and "learning" result sets and present common papers