Tavily Search Skill

---
name: tavily-search-skill
description: Web search via Tavily API (alternative to Brave). Use when the user asks to search the web / look up sources / find links and Brave web_search is unavailable or undesired.
metadata:
  openclaw:
    homepage: https://github.com/JayeGT002/Tavily-Search-Skill
---

# Tavily Search Skill

OpenClaw Skill for performing high quality web searches using the Tavily API.

## Directory Structure

```
tavily-search-skill/
├── SKILL.md                    ← must stay at root
├── search.sh                   ← must stay at root (entry script)
├── apikey                      ← API Key file (user creates this)
├── _meta.json
└── blocklist/
    ├── blocklist.json         ← blacklist config
    └── filter_blocklist.py     ← filter script
```

## Agent Workflow

When instructed to install this skill, follow these steps in order:

### Step 1: Install the skill

```bash
git clone https://github.com/JayeGT002/Tavily-Search-Skill.git tavily-search-skill
cd tavily-search-skill
```

### Step 2: Request API Key from user

Ask the user: "请提供你的 Tavily API Key，用于配置搜索功能。获取地址：https://app.tavily.com/api-keys"

**Wait for the user's API Key reply before proceeding.**

### Step 3: Create apikey file

```bash
echo "USER_PROVIDED_API_KEY" > apikey
chmod 600 apikey
```

### Step 4: Verify installation

```bash
./search.sh "test"
```

A successful response contains search results and quota info.

---

## Blacklist Management

The blacklist filters out low quality or untrusted sources from search results.

### View current blacklist

```bash
cat blocklist/blocklist.json
```

### Add a domain to blacklist

When the user says "block [domain]", update `blocklist/blocklist.json`:

Root domains automatically match all subdomains. Example: adding `csdn.net` also blocks `blog.csdn.net`, `download.csdn.net`, etc.

### Filter feedback

When results are filtered, a message is written to stderr (not visible in normal output). Check stderr if you suspect filtering is silently removing results.

---

## Usage

### Basic Search

```bash
./search.sh "search query"
```

### Specify Result Count

```bash
./search.sh "query" 10
```

### Include Images

```bash
./search.sh "query" 5 true
```

## Dependencies

- `curl`
- `jq`

Install if missing:
- Ubuntu/Debian: `sudo apt-get install curl jq`
- macOS: `brew install curl jq`
- Alpine: `apk add curl jq`