A comprehensive, context-aware skill that enables advanced, multi-strategy searching of your Zotero library through the Zotero MCP (Model Context Protocol) server. Designed for output as a plain markdown formatted outline, suitable for pasting into Logseq. Also offers side-by-side translation of Chinese titles and abstracts for improved English language search within Logseq. Works intelligently in both Claude Desktop and Claude Code.
This is a universal Claude skill that teaches Claude how to search your Zotero reference library intelligently and comprehensively, adapting to the environment:
- In Claude Code: Uses autonomous agents for comprehensive multi-step searches
- In Claude Desktop: Uses safe batched searches with conversation crash protection
- For plain markdown outline format: Suitable for pasting into Logseq with side-by-side Chinese-English translations
Instead of simple one-off searches, Claude learns to:
- Use semantic/AI-powered search to find conceptually related papers
- Try multiple search angles with different phrasings and synonyms
- Combine search methods (semantic + keyword + tags + full-text + annotations)
- Iteratively refine searches based on results
- Ask clarifying questions when your query is ambiguous
- Adapt strategy based on environment (agents in Code, batching in Desktop)
- Format as plain markdown outline with proper structure and translations for Logseq
The Zotero MCP server provides powerful semantic search capabilities, but using it effectively requires:
- Understanding multiple search strategies (semantic vs. keyword vs. tag-based)
- Knowing when to use each search method
- Trying multiple variations and phrasings
- Searching across metadata, full-text, notes, and annotations
- Claude Desktop: Avoiding response limits that can crash conversations
- Claude Code: Leveraging agents for autonomous comprehensive searches
Without guidance, Claude might:
- Use only one search method and miss relevant papers
- Try only one search phrase and return incomplete results
- In Desktop: Request too many results at once (causing crashes)
- In Code: Not utilize agents for complex multi-step searches
- Not explore alternative search angles
This skill provides Claude with:
- Environment detection - Automatically detects Claude Code vs Claude Desktop
- Mandatory multi-angle search strategies (minimum 3 semantic + 3 keyword variations)
- Safe batching guidelines for Desktop (limit=10 per search to prevent crashes)
- Agent-based patterns for Code (comprehensive autonomous searches)
- Comprehensive search patterns combining multiple methods
- Iterative refinement workflows to improve results
- Plain markdown outline formatting suitable for Logseq with Chinese/English translation support
- Context-Aware Operation: Detects environment and adapts search strategy
- Claude Code: Launches autonomous agents for multi-step comprehensive searches
- Claude Desktop: Uses safe batched searches with crash protection
- Semantic-First Discovery: AI-powered conceptual search to find related work
- Multi-Strategy Search: Combines semantic, keyword, tag-based, and full-text methods
- Iterative Refinement: Analyzes initial results and refines search strategy
- Safety-First Design: Built-in protections against Claude Desktop crash bugs
- Comprehensive Coverage: Searches metadata, full-text PDFs, annotations, and notes
- Logseq Integration: Formats bibliographies for Logseq with proper outline hierarchy
- Translation Support: Handles Chinese-English bilingual content
- Semantic Search - Conceptual similarity using AI embeddings
- Keyword Search - Traditional text matching with variations
- Advanced Search - Multi-criteria filtering (author + keyword + year)
- Tag Search - Leverage your existing Zotero tags
- Full-Text Search - Search within PDF contents
- Annotation Search - Find your highlights and notes
- Collection Search - Navigate your Zotero collections
- Agent-Based Searches: Autonomous multi-step search execution
- No Limit Restrictions: Can retrieve comprehensive results safely
- Parallel Searches: Multiple search strategies executed simultaneously
- Intelligent Synthesis: Agents deduplicate and prioritize results
- Safe Batching: limit=10 per search to prevent crashes
- Iterative Presentation: Progressive result display with user confirmation
- Multi-Angle Coverage: Multiple small searches instead of large ones
- Crash Protection: Built-in safeguards against conversation deletion
- Plain Markdown Outline: Nested bullets (no markdown headers), suitable for pasting into Logseq
- Compact Citations: Author(s), Year. Title format
- No Bold Styling: Plain text throughout
- Chinese-English Support: Side-by-side titles and abstracts for improved English search
- Automatic Translation: English translations of Chinese content
- Zotero Links: Clickable zotero:// URLs for each item
- Thematic Organization: Grouped by categories (no summary sections)
- Zotero Desktop with your reference library
- Zotero MCP Server installed and configured
- Repository: https://github.com/54yyyu/zotero-mcp
- Follow their installation instructions
- Claude Desktop and/or Claude Code with MCP support
- The Zotero MCP server configured in your Claude MCP settings
- Download the latest release zip file
- Open Claude Desktop
- Go to Settings → Skills
- Click "Import Skill" and select the downloaded zip file
- Clone or download this repository
- Copy the skill folder to
~/.claude/skills/zotero-mcp/ - Restart Claude Code or reload skills
- Clone or download this repository:
git clone https://github.com/kerim/zotero-mcp-skill.git
- Copy the
SKILL.mdfile to your Claude skills directory - Restart Claude or reload skills
Claude automatically activates this skill when you need to:
- Search your Zotero library for papers or references
- Explore a research topic in your collection
- Find related work on a concept or theme
- Locate specific authors or papers
- Search through your annotations and notes
- Generate formatted bibliographies for Logseq
Conceptual Discovery:
"Find papers about embodied cognition"
- Claude Code: Launches agent → comprehensive multi-strategy search → curated results
- Claude Desktop: Multiple semantic/keyword/tag searches (limit=10 each) → combined results
Author Search:
"What do I have by Susan Carey?"
- Claude Code: Agent searches author + citations + concepts
- Claude Desktop: Batched searches by author + notes + semantic concepts
Complex Topic:
"Research about skill transfer in mathematical reasoning"
- Claude Code: Agent cross-references multiple concepts → thematic synthesis
- Claude Desktop: Combined semantic/keyword searches → manual synthesis
Bibliography Generation:
"Create a Logseq bibliography for all papers on Indigenous language policy"
→ Claude searches comprehensively → retrieves metadata → formats with:
- Logseq outline hierarchy (no headers)
- Compact citations (Author, Year. Title)
- Chinese/English bilingual support
- No bold styling
- Zotero links
- Analyze query → Detect search type
- Launch agent → Autonomous comprehensive search
- Agent executes → Multiple strategies in parallel
- Agent synthesizes → Deduplication and prioritization
- Present findings → Curated results with context
- Analyze query → Determine approach
- Execute batched searches → 5-10 searches with limit=10
- Combine results → Merge and deduplicate
- Refine if needed → Alternative angles for poor results
- Present findings → Results with search path explanation
This skill enforces a "search comprehensively, not narrowly" philosophy:
- Never settle for one search - Always try multiple angles
- Never use one search term - Always try variations and synonyms
- Always combine methods - Semantic + keyword + tags + full-text
- Always check tags first - Discover user's tagging conventions
- Always refine iteratively - Analyze results and adjust strategy
- Always ask when unclear - Clarifying questions for vague queries
- Adapt to environment - Use agents in Code, batching in Desktop
For any user query, Claude will try AT MINIMUM:
- 3 semantic search variations (different phrasings)
- 3 keyword variations (synonyms, related terms)
- 1 tag search (after checking available tags)
- 1 full-text/annotation search (if applicable)
You can customize this skill by editing SKILL.md:
- Modify default search limits (Claude Desktop: currently limit=10)
- Add domain-specific search patterns
- Adjust search variation requirements
- Add custom presentation preferences
- Customize markdown outline formatting rules
- Adjust agent prompts (Claude Code only)
The skill will check and update your Zotero semantic search database when needed using:
zotero_get_search_database_status- Check database statuszotero_update_search_database- Update with latest items
This skill teaches Claude to use these Zotero MCP server tools:
| Tool | Purpose | Desktop Limit | Code (Agent) |
|---|---|---|---|
zotero_semantic_search |
AI-powered conceptual search | 10 | No limit |
zotero_search_items |
Keyword matching | 10 | No limit |
zotero_advanced_search |
Multi-criteria filtering | 10 | No limit |
zotero_get_tags |
Discover available tags | - | - |
zotero_search_by_tag |
Tag-based filtering | 10 | No limit |
zotero_search_notes |
Search annotations/notes | 10 | No limit |
zotero_get_annotations |
Retrieve highlights | 10 | No limit |
zotero_get_item_fulltext |
Access full-text content | - | - |
zotero_get_item_metadata |
Retrieve item metadata | - | - |
zotero_get_collections |
List collections | - | - |
zotero_get_recent |
Recent additions | 10 | No limit |
- Hard limit defaults - All searches use limit=10 by default
- Batched iteration - Multiple small searches instead of large ones
- Interactive fallback - Progressive result presentation
- Crash prevention - Never exceeds limit=20 in a single call
- Agent sandboxing - Agents run searches independently
- Parallel execution - Multiple searches simultaneously
- Intelligent synthesis - Agents deduplicate and prioritize
- No conversation risk - Agents don't cause UI crashes
Claude will:
- Try broader search terms
- Use more general concepts
- Remove filters
- Search related fields/disciplines
- Ask clarifying questions
Claude will suggest:
zotero_update_search_database
Claude will automatically:
- Too many: Add filters (tags, date ranges, collections)
- Too few: Broaden terms, try synonyms, search alternative angles
If you experience conversation deletion:
- The skill enforces limit=10 by default to prevent this
- Ensure you're using the latest version of this skill
- Report persistent issues to both this repo and Zotero MCP server
Contributions welcome! To improve this skill:
- Fork this repository
- Make your changes to
SKILL.md - Test with both Claude Desktop and Claude Code
- Submit a pull request
- Domain-specific search patterns (medical, legal, etc.)
- Additional search failure recovery strategies
- Integration with other Zotero MCP features
- Result presentation templates
- Language-specific search variations
- Additional markdown outline formatting styles
- More agent task patterns
- Zotero MCP Server: https://github.com/54yyyu/zotero-mcp
- Model Context Protocol: https://modelcontextprotocol.io/
- Claude Desktop: https://claude.ai/download
- Claude Code: https://docs.claude.com/claude-code
MIT License - see LICENSE file for details
- Built for the Zotero MCP Server by @54yyyu
- Developed for Claude Desktop and Claude Code
- Semantic search powered by Claude's embedding models
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Zotero MCP Server Issues: https://github.com/54yyyu/zotero-mcp/issues
Made for researchers who want comprehensive, intelligent search of their Zotero libraries - whether in Claude Desktop or Claude Code.