Research Skill
API Keys Required
This skill works best with these optional API keys configured in ~/.env :
Feature API Key Get It From
Perplexity Research PERPLEXITY_API_KEY
https://perplexity.ai/settings/api
Gemini Research GOOGLE_API_KEY
https://aistudio.google.com/app/apikey
Works without API keys:
-
Claude-based research (uses built-in WebSearch)
-
Basic web fetching (uses built-in WebFetch)
Workflow Routing
Multi-Source Research Workflows
When user requests comprehensive parallel research: Examples: "do research on X", "research this topic", "find information about Y", "investigate this subject" → READ: ${PAI_DIR}/skills/research/workflows/conduct.md
→ EXECUTE: Parallel multi-agent research using available researcher agents
When user requests Claude-based research (FREE - no API keys): Examples: "use claude for research", "claude research on X", "use websearch to research Y" → READ: ${PAI_DIR}/skills/research/workflows/claude-research.ts
→ EXECUTE: Intelligent query decomposition with Claude's WebSearch
When Claude WebSearch fails or returns poor results (fallback): Examples: WebSearch returned nothing, stale results, rate-limited, user says "use gemini" → EXECUTE: Launch gemini-researcher agent via Task tool with the failed query → NOTE: Also use as parallel second opinion when confidence is low
When user requests Perplexity research (requires PERPLEXITY_API_KEY): Examples: "use perplexity to research X", "perplexity research on Y" → READ: ${PAI_DIR}/skills/research/workflows/perplexity-research.ts
→ EXECUTE: Fast web search with query decomposition via Perplexity API
When user requests interview preparation: Examples: "prepare interview questions for X", "interview research on Y" → READ: ${PAI_DIR}/skills/research/workflows/interview-research.md
→ EXECUTE: Interview prep with diverse question generation
Content Retrieval Workflows
When user indicates difficulty accessing content: Examples: "can't get this content", "site is blocking me", "CAPTCHA blocking" → READ: ${PAI_DIR}/skills/research/workflows/retrieve.md
→ EXECUTE: Content retrieval via WebFetch
When user provides YouTube URL: Examples: "get this youtube video", "extract from youtube URL" → READ: ${PAI_DIR}/skills/research/workflows/youtube-extraction.md
→ EXECUTE: YouTube content extraction
When user requests web scraping: Examples: "scrape this site", "extract data from this website" → READ: ${PAI_DIR}/skills/research/workflows/web-scraping.md
→ EXECUTE: Web scraping techniques and tools
Content Enhancement Workflows
When user requests content enhancement: Examples: "enhance this content", "improve this draft" → READ: ${PAI_DIR}/skills/research/workflows/enhance.md
→ EXECUTE: Content improvement and refinement
When user requests knowledge extraction: Examples: "extract knowledge from X", "get insights from this" → READ: ${PAI_DIR}/skills/research/workflows/extract-knowledge.md
→ EXECUTE: Knowledge extraction and synthesis
Multi-Source Research
Three Research Modes
QUICK RESEARCH MODE:
-
User says "quick research" → Launch 1 agent per researcher type
-
Timeout: 2 minutes
-
Best for: Simple queries, straightforward questions
STANDARD RESEARCH MODE (Default):
-
Default for most research requests → Launch 3 agents per researcher type
-
Timeout: 3 minutes
-
Best for: Most research needs, comprehensive coverage
EXTENSIVE RESEARCH MODE:
-
User says "extensive research" → Launch 8 agents per researcher type
-
Timeout: 10 minutes
-
Best for: Deep-dive research, comprehensive reports
Available Research Agents
Check ${PAI_DIR}/agents/ for agents with "researcher" in their name:
- gemini-researcher
- Uses Gemini CLI as fallback when WebSearch fails (requires GOOGLE_API_KEY)
Speed Benefits
-
❌ Old approach: Sequential searches → 5-10 minutes
-
✅ Quick mode: 1 agent per type → 2 minute timeout
-
✅ Standard mode: 3 agents per type → 3 minute timeout
-
✅ Extensive mode: 8 agents per type → 10 minute timeout
Intelligent Content Retrieval
Three-Layer Escalation System
Layer 1: Built-in Tools (Try First - FREE)
-
WebFetch - Standard web content fetching
-
WebSearch - Search engine queries
-
When to use: Default for all content retrieval
Critical Rules:
-
Always try simplest approach first (Layer 1)
-
Escalate only when previous layer fails
-
Document which layers were used and why
File Organization
Working Directory (Scratchpad)
${PAI_DIR}/scratchpad/YYYY-MM-DD-HHMMSS_research-[topic]/ ├── raw-outputs/ ├── synthesis-notes.md └── draft-report.md
Permanent Storage (History)
${PAI_DIR}/history/research/YYYY-MM/YYYY-MM-DD_[topic]/ ├── README.md ├── research-report.md └── metadata.json
Key Principles
-
Parallel execution - Launch multiple agents simultaneously
-
Hard timeouts - Don't wait indefinitely, proceed with partial results
-
Simplest first - Always try free tools before paid services
-
Auto-routing - Skill analyzes intent and activates appropriate workflow
WebSearch Tool Usage
Built-in Web Search (FREE)
Claude Code includes a built-in WebSearch tool for real-time web queries.
When to Use:
-
Current events and recent information
-
Documentation and API references
-
Pricing, availability, status checks
-
Fact verification beyond training data
Best Practices:
// Include year for recent info WebSearch({ query: "Next.js 15 features 2024" })
// Be specific WebSearch({ query: "TypeScript 5.4 satisfies operator examples" })
// Use domain filtering for trusted sources WebSearch({ query: "React hooks best practices", allowed_domains: ["react.dev", "kentcdodds.com"] })
Query Optimization:
-
Include year: "React Server Components 2024"
-
Be specific: "Bun vs Node.js benchmark comparison"
-
Use domain filters: Focus on official docs or trusted sources
Source Citation: Always cite sources in research output:
Sources
WebSearch vs WebFetch
Need Tool
Search for information WebSearch
Get specific page content WebFetch
Multiple search results WebSearch
Full article extraction WebFetch
Integration with Research Workflows
WebSearch is the foundation of claude-researcher agent:
-
Query decomposition into sub-queries
-
Parallel WebSearch calls
-
Result synthesis
-
Source attribution
Workflow Files
Workflow File API Keys Needed
Multi-Source Research workflows/conduct.md
Varies by agent
Claude Research workflows/claude-research.ts
None (FREE)
Perplexity Research workflows/perplexity-research.ts
PERPLEXITY_API_KEY
Interview Prep workflows/interview-research.md
None
Content Retrieval workflows/retrieve.md
None
YouTube Extraction workflows/youtube-extraction.md
None
Web Scraping workflows/web-scraping.md
None
Content Enhancement workflows/enhance.md
None
Knowledge Extraction workflows/extract-knowledge.md
None