Tavily Web Skill

Trigger Conditions & Endpoint Selection

Choose Tavily endpoint based on user intent:

search: Need to "search web / latest info / find sources / find links"
extract: Given URL(s), need to extract/summarize content
crawl: Need to traverse site following instructions and scrape page content
map: Need to discover site page list/structure (without full content or metadata only)
research: Need structured research output following given
```
output_schema
```

Recommended Architecture (Main Skill + Sub-skill)

This skill uses a two-phase architecture:

Main skill (current context): Understand user question → Choose endpoint → Assemble JSON payload
Sub-skill (fork context): Only responsible for HTTP call execution, avoiding conversation history token waste

Skill Path Resolution

Resolve

TAVILY_WEB_SKILL_DIR

before running commands:

bash

if [ -z "${TAVILY_WEB_SKILL_DIR:-}" ]; then
  if [ -f "$HOME/.agent/skills/tavily-web/tavily-api.cjs" ]; then
    export TAVILY_WEB_SKILL_DIR="$HOME/.agent/skills/tavily-web"
  elif [ -f "$HOME/.claude/skills/tavily-web/tavily-api.cjs" ]; then
    export TAVILY_WEB_SKILL_DIR="$HOME/.claude/skills/tavily-web"
  elif [ -f "$HOME/.codex/skills/tavily-web/tavily-api.cjs" ]; then
    export TAVILY_WEB_SKILL_DIR="$HOME/.codex/skills/tavily-web"
  else
    echo "Set TAVILY_WEB_SKILL_DIR to your installed skill path." >&2
    exit 1
  fi
fi

Execution Method

Use Task tool to invoke

tavily-fetcher

sub-skill, passing command and JSON (stdin):

Task parameters:
- subagent_type: Bash
- description: "Call Tavily API"
- prompt: cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" <search|extract|crawl|map|research>
  { ...payload... }
  JSON

Payload Examples (Based on Provided curl)

1) Search the web

bash

cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" search
{
  "query": "who is Leo Messi?",
  "auto_parameters": false,
  "topic": "general",
  "search_depth": "basic",
  "chunks_per_source": 3,
  "max_results": 1,
  "time_range": null,
  "start_date": "2025-02-09",
  "end_date": "2025-12-29",
  "include_answer": false,
  "include_raw_content": false,
  "include_images": false,
  "include_image_descriptions": false,
  "include_favicon": false,
  "include_domains": [],
  "exclude_domains": [],
  "country": null,
  "include_usage": false
}
JSON

2) Extract webpages

bash

cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" extract
{
  "urls": "https://en.wikipedia.org/wiki/Artificial_intelligence",
  "query": "<string>",
  "chunks_per_source": 3,
  "extract_depth": "basic",
  "include_images": false,
  "include_favicon": false,
  "format": "markdown",
  "timeout": "None",
  "include_usage": false
}
JSON

3) Crawl webpages

bash

cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" crawl
{
  "url": "docs.tavily.com",
  "instructions": "Find all pages about the Python SDK",
  "chunks_per_source": 3,
  "max_depth": 1,
  "max_breadth": 20,
  "limit": 50,
  "select_paths": null,
  "select_domains": null,
  "exclude_paths": null,
  "exclude_domains": null,
  "allow_external": true,
  "include_images": false,
  "extract_depth": "basic",
  "format": "markdown",
  "include_favicon": false,
  "timeout": 150,
  "include_usage": false
}
JSON

4) Map webpages

bash

cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" map
{
  "url": "docs.tavily.com",
  "instructions": "Find all pages about the Python SDK",
  "max_depth": 1,
  "max_breadth": 20,
  "limit": 50,
  "select_paths": null,
  "select_domains": null,
  "exclude_paths": null,
  "exclude_domains": null,
  "allow_external": true,
  "timeout": 150,
  "include_usage": false
}
JSON

5) Create Research Task

bash

cat <<'JSON' | node "$TAVILY_WEB_SKILL_DIR/tavily-api.cjs" research
{
  "input": "What are the latest developments in AI?",
  "model": "auto",
  "stream": false,
  "output_schema": {
    "properties": {
      "company": {
        "type": "string",
        "description": "The name of the company"
      },
      "key_metrics": {
        "type": "array",
        "description": "List of key performance metrics",
        "items": {
          "type": "string"
        }
      },
      "financial_details": {
        "type": "object",
        "description": "Detailed financial breakdown",
        "properties": {
          "operating_income": {
            "type": "number",
            "description": "Operating income for the period"
          }
        }
      }
    },
    "required": [
      "company"
    ]
  },
  "citation_format": "numbered"
}
JSON

Environment Variables & API Key

Configuration priority: process environment >

.env

Multi-key (recommended):
```
TAVILY_API_KEYS=key1,key2,key3
```
Single-key fallback:
```
TAVILY_API_KEY=key1
```

.env

file path:

$TAVILY_WEB_SKILL_DIR/.env

(can copy from

.env.example

)

Optional:

```
TAVILY_MAX_RETRIES
```
for network/server retries
```
TAVILY_KEY_STATE_PATH
```
to override key-state file path

tavily-web

NPX Install

SKILL.md Content

Tavily Web Skill

Trigger Conditions & Endpoint Selection

Recommended Architecture (Main Skill + Sub-skill)

Skill Path Resolution

Execution Method

Payload Examples (Based on Provided curl)

1) Search the web

2) Extract webpages

3) Crawl webpages

4) Map webpages

5) Create Research Task

Environment Variables & API Key