Research Skill

Conduct comprehensive research on any topic with automatic source gathering, analysis, and response generation with citations.

When to Use

• Researching any topic requiring web-sourced information
• Generating structured research reports with custom schemas
• Building pipelines that need AI-synthesized insights with citations

Prerequisites

Tavily API Key Required - Get your key at https://tavily.com

Add to ~/.claude/settings.json:

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

Quick Start

Tip: Research can take several minutes, especially with --model pro. Press Ctrl+B to run in the background and continue working while it completes.

Basic Research (Polling Mode)

python scripts/research.py "Latest developments in quantum computing"

With Custom Schema

python scripts/research.py "Electric vehicle market analysis" \
  --schema ./schemas/market_analysis.json \
  --model pro

Streaming Mode

python scripts/research.py "AI agent frameworks comparison" --stream

Save to File

python scripts/research.py "Rust async ecosystem" \
  --output ./reports/rust_async.json \
  --model pro

CLI Reference

Option	Short	Default	Description
topic	-	Required	Research topic or question
--schema	-s	None	Path to JSON schema file or inline JSON
--stream	-	False	Enable streaming mode
--model	-m	mini	Model: mini, pro, auto
--citation	-c	numbered	Citation format: numbered, mla, apa, chicago
--output	-o	stdout	Output file path
--poll-interval	-p	5	Seconds between polls (polling mode)
--quiet	-q	False	Suppress progress output

Output Format

{
  "meta": {
    "topic": "Your research topic",
    "model": "pro",
    "completed_at": "2025-01-08T14:30:00Z",
    "response_time_seconds": 45.2
  },
  "content": "...",
  "sources": [
    {"url": "https://...", "title": "Source Title", "citation": "[1]"}
  ]
}

• content: Markdown string (default) or structured JSON (when schema provided)
• sources: Array of citations used in the research

Schema Usage

Schemas make output structured and predictable. Provide via file path or inline JSON.

File Path

python scripts/research.py "topic" --schema ./my_schema.json

Inline JSON

python scripts/research.py "topic" --schema '{"properties": {"summary": {"type": "string", "description": "Executive summary"}}}'

Schema Requirements

Every property MUST include both type and description:

{
  "properties": {
    "summary": {
      "type": "string",
      "description": "2-3 sentence executive summary"
    },
    "key_points": {
      "type": "array",
      "description": "Main takeaways",
      "items": {"type": "string"}
    }
  },
  "required": ["summary", "key_points"]
}

See references/schema.json for complete schema rules and examples.

Model Selection

Rule of thumb: "what does X do?" → mini. "X vs Y vs Z" or "best way to..." → pro.

Model	Use Case	Speed
mini	Single topic, targeted research	Fast
pro	Comprehensive multi-angle analysis, open ended	Slower
auto	API chooses based on topic complexity	Varies

Examples

Market Research

python scripts/research.py "Fintech startup landscape 2025" \
  --schema ./schemas/market_research.json \
  --model pro \
  --output ./reports/fintech_2025.json

Technical Comparison

python scripts/research.py "LangGraph vs CrewAI for multi-agent systems" \
  --model pro \
  --citation mla

Quick Overview

python scripts/research.py "What is retrieval augmented generation?" --quiet