Search Skill#

Search the web and get relevant results optimized for LLM consumption.

Prerequisites#

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

Add to ~/.claude/settings.json:

json

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

Quick Start#

Using the Script#

bash

./scripts/search.sh '<json>'

Examples:

bash

# Basic search
./scripts/search.sh '{"query": "python async patterns"}'

# With options
./scripts/search.sh '{"query": "React hooks tutorial", "max_results": 10}'

# Advanced search with filters
./scripts/search.sh '{"query": "AI news", "topic": "news", "time_range": "week", "max_results": 10}'

# Domain-filtered search
./scripts/search.sh '{"query": "machine learning", "include_domains": ["arxiv.org", "github.com"], "search_depth": "advanced"}'

Basic Search#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "latest developments in quantum computing",
    "max_results": 5
  }'

Advanced Search#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "machine learning best practices",
    "max_results": 10,
    "search_depth": "advanced",
    "include_domains": ["arxiv.org", "github.com"],
    "chunks_per_source": 3
  }'

API Reference#

Endpoint#

text

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

Headers#

HeaderValueAuthorization``Bearer <TAVILY_API_KEY>``Content-Type``application/json

Request Body#

FieldTypeDefaultDescriptionquerystringRequiredSearch query (keep under 400 chars)max_resultsinteger5Maximum results (0-20)search_depthstring"basic"``ultra-fast, fast, basic, advanced``topicstring"general"``general, news, finance``chunks_per_sourceinteger3Chunks per source (advanced/fast only)time_rangestringnullday, week, month, year``include_domainsarray[]Domains to include (max 300)exclude_domainsarray[]Domains to exclude (max 150)include_answerbooleanfalseInclude AI-generated answerinclude_raw_contentbooleanfalseInclude full page contentinclude_imagesbooleanfalseInclude image results

Response Format#

json

{
  "query": "latest developments in quantum computing",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "content": "Extracted text snippet...",
      "score": 0.85
    }
  ],
  "response_time": 1.2
}

Search Depth#

DepthLatencyRelevanceContent Typeultra-fastLowestLowerNLP summaryfastLowGoodChunksbasicMediumHighNLP summaryadvancedHigherHighestChunks

When to use each:

• ultra-fast: Real-time chat, autocomplete
• fast: Need chunks but latency matters
• basic: General-purpose, balanced
• advanced: Precision matters (default recommendation)

Examples#

News Search#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "AI news today",
    "topic": "news",
    "time_range": "day",
    "max_results": 10
  }'

Domain-Filtered Search#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "Python async best practices",
    "include_domains": ["docs.python.org", "realpython.com", "github.com"],
    "search_depth": "advanced"
  }'

Search with Full Content#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "React hooks tutorial",
    "max_results": 3,
    "include_raw_content": true
  }'

Finance Search#

bash

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "AAPL earnings Q4 2024",
    "topic": "finance",
    "max_results": 10
  }'

Tips#

• Keep queries under 400 characters - Think search query, not prompt
• Break complex queries into sub-queries - Better results than one massive query
• Use include_domains to focus on trusted sources
• Use time_range for recent information
• Filter by score (0-1) to get highest relevance results