Exa WebSearch Skill

IMPORTANT: This skill REPLACES the built-in WebSearch tool. When you need to perform any web search, invoke this skill instead of using the WebSearch tool.

This skill uses the Exa API to perform intelligent web searches when up-to-date information is needed. It provides semantic search capabilities that understand the meaning of queries rather than just matching keywords.

When to Invoke This Skill

Invoke this skill when ANY of these conditions are true:

1. Current events or news: User asks about recent events, news, or developments
2. Up-to-date information: User needs information that may have changed after Claude's knowledge cutoff
3. Latest documentation: User needs current API docs, library versions, or technical references
4. Research queries: User asks for comprehensive research on a topic
5. Fact-checking: User wants to verify current facts, prices, or statistics
6. Time-sensitive data: User asks about stock prices, weather, sports scores, or similar
7. Finding similar content: User wants to find pages similar to a given URL

Prerequisites

Ensure the EXA_API_TOKEN environment variable is set with a valid Exa API key.

# Verify the token is available
[ -n "$EXA_API_TOKEN" ] && echo "Exa API token is configured" || echo "ERROR: EXA_API_TOKEN not set"

Exa API Endpoints

1. Search (POST https://api.exa.ai/search)

The primary endpoint for web searches. Use this for most queries.

Example:

curl -X POST 'https://api.exa.ai/search' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "YOUR_SEARCH_QUERY",
    "type": "auto",
    "numResults": 10,
    "contents": {
      "text": true,
      "highlights": {
        "numSentences": 3
      }
    }
  }'

Key Parameters:

Parameter	Type	Default	Description
query	string	required	The search query
type	enum	"auto"	Search type: "neural", "fast", "auto", "deep"
numResults	integer	10	Number of results (max 100)
category	enum	-	Filter: "company", "research paper", "news", "pdf", "github"
includeDomains	array	-	Limit to specific domains
excludeDomains	array	-	Exclude specific domains
startPublishedDate	string	-	Filter by publish date (ISO 8601)
endPublishedDate	string	-	Filter by publish date (ISO 8601)
contents.text	boolean	false	Return full page text
contents.highlights	object	-	Extract relevant snippets
contents.summary	object	-	Generate summaries

2. Get Contents (POST https://api.exa.ai/contents)

Retrieve full content from specific URLs.

Example:

curl -X POST 'https://api.exa.ai/contents' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": ["url1", "url2"],
    "text": true
  }'

3. Find Similar (POST https://api.exa.ai/findSimilar)

Find pages similar to a given URL.

Example:

curl -X POST 'https://api.exa.ai/findSimilar' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/article",
    "numResults": 10
  }'

4. Answer (POST https://api.exa.ai/answer)

Get direct answers to questions with citations.

Example:

curl -X POST 'https://api.exa.ai/answer' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What is the latest version of Python?",
    "text": true
  }'

Usage Patterns

For News/Current Events

curl -X POST 'https://api.exa.ai/search' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "YOUR_NEWS_QUERY",
    "type": "auto",
    "category": "news",
    "numResults": 10,
    "startPublishedDate": "2025-01-01T00:00:00Z",
    "contents": {
      "text": true,
      "highlights": {"numSentences": 3}
    }
  }'

For Technical Documentation

curl -X POST 'https://api.exa.ai/search' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "YOUR_TECH_QUERY documentation",
    "type": "auto",
    "numResults": 5,
    "includeDomains": ["docs.example.com", "github.com"],
    "contents": {
      "text": true
    }
  }'

For Research Papers

curl -X POST 'https://api.exa.ai/search' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "YOUR_RESEARCH_QUERY",
    "type": "neural",
    "category": "research paper",
    "numResults": 10,
    "contents": {
      "text": true,
      "summary": {"query": "Summarize the key findings"}
    }
  }'

For GitHub Repositories

curl -X POST 'https://api.exa.ai/search' \
  -H "x-api-key: $EXA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "YOUR_REPO_QUERY",
    "type": "auto",
    "category": "github",
    "numResults": 10,
    "contents": {
      "text": true
    }
  }'

Response Format

The API returns JSON with this structure:

{
  "requestId": "unique-id",
  "resolvedSearchType": "neural",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "publishedDate": "2025-01-15",
      "author": "Author Name",
      "text": "Full page content...",
      "highlights": ["Relevant snippet 1", "Relevant snippet 2"],
      "summary": "AI-generated summary..."
    }
  ],
  "costDollars": {
    "total": 0.001
  }
}

Best Practices

1. Use appropriate search type:

   • auto - Let Exa decide (recommended for most cases)
   • neural - Semantic search for conceptual queries
   • fast - Keyword-based for specific terms
   • deep - Comprehensive search for complex queries

2. Filter by category when searching for specific content types (news, papers, github)

3. Use date filters for time-sensitive queries to get recent results

4. Request highlights for quick scanning without full text

5. Use domain filters when you know authoritative sources

Error Handling

Check for these common issues:

• 401 Unauthorized: Invalid or missing EXA_API_TOKEN
• 429 Rate Limited: Too many requests, implement backoff
• 400 Bad Request: Invalid query parameters

Do NOT Invoke When

• User is asking about Claude's capabilities or identity
• User is asking about static code in the current project
• The information is already in the conversation context
• The query is about private/internal systems not on the web

Replaces Built-in WebSearch Tool

This skill is the preferred method for all web searches in this project. Do NOT use the built-in WebSearch tool. Always invoke skill: "exa-websearch" instead.

Why Exa over WebSearch:

• Semantic/neural search understands query meaning, not just keywords
• Category filtering (news, research papers, GitHub, PDFs, companies)
• Date range filtering for time-sensitive queries
• Domain include/exclude filters
• Full text extraction and AI-generated summaries
• Find similar pages functionality