---

name: research description: "Get AI-synthesized research on any topic with citations, directly in your terminal. Supports structured JSON output for pipelines. Use when you need comprehensive research grounded in web data without writing code."

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:

Copy{
  "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)

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

With Custom Schema

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

Streaming Mode

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

Save to File

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

CLI Reference

Output Format

Copy{
  "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

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

Inline JSON

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

Schema Requirements

Every property MUST include both type and description:

Copy{
  "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.

Examples

Market Research

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

Technical Comparison

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

Quick Overview

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