SKILL.md
Tavily Search
Headless web search and content extraction using Tavily. Built for LLM agents — returns clean, summarised results with optional raw article bodies. No browser required.
When to use
- You need up-to-date web information (news, docs, pricing, facts)
- You want cited sources with URLs for a research/writing task
- You need the full readable body of a URL as markdown
- Brave/Google search is not available or rate-limited
When NOT to use
- You already have the page in your context
- The answer is static and likely in the model's training data
- You need to interact with a page (login, click) — use a browser MCP instead
Setup
- Get a free API key: https://app.tavily.com (1000 free searches/month)
- Export it:
``bash export TAVILYAPIKEY="tvly-YOURKEYHERE" ``
Add to ~/.zshrc or ~/.bashrc for persistence. Never commit the key.
- First run will auto-install dependencies via
uv:
``bash command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh ``
Search
# Basic search — 5 results, summarised answer
uv run ~/.claude/skills/lich-skills/skills/tavily-search/scripts/search.py "your query"
# More results
uv run .../search.py "your query" --max-results 10
# Include full article bodies (slower, more tokens)
uv run .../search.py "your query" --raw-content
# Deeper search with higher recall
uv run .../search.py "your query" --depth advanced
# News-only, last 7 days
uv run .../search.py "your query" --topic news --days 7
# Output as JSON
uv run .../search.py "your query" --jsonFlags
| Flag | Default | Purpose |
|---|---|---|
--max-results N |
5 |
Number of results to return (1–20) |
--depth {basic,advanced} |
basic |
advanced = slower, higher quality |
--topic {general,news} |
general |
News mode adds recency filtering |
--days N |
— | With --topic news, restrict to last N days |
--raw-content |
off | Include full article body as markdown |
--include-domains a,b |
— | Restrict to comma-separated domains |
--exclude-domains a,b |
— | Exclude comma-separated domains |
--json |
off | Machine-readable JSON output |
Extract a single URL
uv run .../search.py --extract https://example.com/articleReturns clean markdown of the page body (no nav, ads, or boilerplate).
Output format (default, human-readable)
ANSWER: <Tavily's synthesised answer, 1–3 sentences>
RESULTS:
[1] <title>
<url>
<snippet — 1–2 sentences>
[2] ...With --raw-content each result gets an indented markdown body below the snippet.
Examples
Research a library:
uv run .../search.py "Gemini 3 Flash Image API pricing" --depth advancedGet the full article body of a blog post:
uv run .../search.py --extract https://blog.example.com/post --json > post.jsonNews sweep:
uv run .../search.py "OpenAI Codex release" --topic news --days 3 --max-results 10Environment
- Key lookup order:
--api-keyflag →$TAVILYAPIKEY→$TAVILY_KEY - Default model: Tavily's
searchandextractendpoints (v1) - Default timeout: 30s per request
Common failures
| Error | Fix |
|---|---|
Error: No TAVILYAPIKEY |
Export the key or pass --api-key |
401 Unauthorized |
Key is wrong, revoked, or over quota |
429 Rate limit |
Wait or upgrade plan |
No results |
Broaden query, try --depth advanced, drop domain filters |
Red flags
- Hardcoding the API key anywhere in this repo
- Passing the key on the command line in shared terminals (shell history leak)
- Using
--raw-contentwith--max-results 20on every query (burns tokens)
Verification
-
$TAVILYAPIKEYis set in env, not in files -
uv run .../search.py "hello world"returns results -
gitleaks detect --source .clean