stevessr/research

Research Skill

Conduct comprehensive research on any topic with automatic source gathering, analysis, and response generation 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 30-120 seconds. Press Ctrl+B to run in the background.

Using the Script

./scripts/research.sh '<json>' [output_file]

Examples:

# Basic research
./scripts/research.sh '{"input": "quantum computing trends"}'

# With pro model for comprehensive analysis
./scripts/research.sh '{"input": "AI agents comparison", "model": "pro"}'

# Save to file
./scripts/research.sh '{"input": "market analysis for EVs", "model": "pro"}' ./ev-report.md

# With custom citation format
./scripts/research.sh '{"input": "climate change impacts", "model": "mini", "citation_format": "apa"}'

# With structured output schema
./scripts/research.sh '{"input": "fintech startups 2025", "model": "pro", "output_schema": {"properties": {"summary": {"type": "string"}, "companies": {"type": "array", "items": {"type": "string"}}}, "required": ["summary"]}}'

Basic Research

curl --request POST \
  --url https://api.tavily.com/research \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "Latest developments in quantum computing",
    "model": "mini",
    "stream": false,
    "citation_format": "numbered"
  }'

Note: Streaming is disabled for token management. The call waits until research completes and returns clean JSON.

With Custom Schema

curl --request POST \
  --url https://api.tavily.com/research \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "Electric vehicle market analysis",
    "model": "pro",
    "stream": false,
    "citation_format": "numbered",
    "output_schema": {
      "properties": {
        "market_overview": {
          "type": "string",
          "description": "2-3 sentence overview of the market"
        },
        "key_players": {
          "type": "array",
          "description": "Major companies in this market",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string", "description": "Company name"},
              "market_share": {"type": "string", "description": "Approximate market share"}
            },
            "required": ["name"]
          }
        }
      },
      "required": ["market_overview", "key_players"]
    }
  }'

API Reference

Endpoint

POST https://api.tavily.com/research

Headers

| Header | Value | |--------|-------| | Authorization | Bearer <TAVILY_API_KEY> | | Content-Type | application/json |

Request Body

| Field | Type | Default | Description | |-------|------|---------|-------------| | input | string | Required | Research topic or question | | model | string | "mini" | Model: mini, pro, auto | | stream | boolean | false | Streaming disabled for token management | | output_schema | object | null | JSON schema for structured output | | citation_format | string | "numbered" | Citation format: numbered, mla, apa, chicago |

Response Format (JSON)

With stream: false, the response is clean JSON:

{
  "content": "# Research Results\n\n...",
  "sources": [{"url": "https://...", "title": "Source Title"}],
  "response_time": 45.2
}

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 | ~30s | | pro | Comprehensive multi-angle analysis | ~60-120s | | auto | API chooses based on complexity | Varies |

Schema Usage

Schemas make output structured and predictable. 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"]
}

Examples

Market Research

curl --request POST \
  --url https://api.tavily.com/research \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "Fintech startup landscape 2025",
    "model": "pro",
    "stream": false,
    "citation_format": "numbered",
    "output_schema": {
      "properties": {
        "market_overview": {"type": "string", "description": "Executive summary of fintech market"},
        "top_startups": {
          "type": "array",
          "description": "Notable fintech startups",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string", "description": "Startup name"},
              "focus": {"type": "string", "description": "Primary business focus"},
              "funding": {"type": "string", "description": "Total funding raised"}
            },
            "required": ["name", "focus"]
          }
        },
        "trends": {"type": "array", "description": "Key market trends", "items": {"type": "string"}}
      },
      "required": ["market_overview", "top_startups"]
    }
  }'

Technical Comparison

curl --request POST \
  --url https://api.tavily.com/research \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "LangGraph vs CrewAI for multi-agent systems",
    "model": "pro",
    "stream": false,
    "citation_format": "mla"
  }'

Quick Overview

curl --request POST \
  --url https://api.tavily.com/research \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "What is retrieval augmented generation?",
    "model": "mini",
    "stream": false
  }'