// Web search and content extraction via the Tavily API. Use when you need real-time web results, citations, or raw article content without a browser. Requires TAVILY_API_KEY.
Use BEFORE any spec, plan, or code exists — the Stage 0 gate that decides whether a project should start at all. NO-GO is the default. GO requires passing five framework checks (Differentiation · Audience–Market Fit · Acquisition Channel · Capacity · 7-Factor Wedge), a memory check against your own prior attempts, and a 24-hour pattern-interrupt if enthusiasm-high is detected. Output is a public commitment artifact with pre-mortemed kill criteria (D14/D30/D60/D90 review gates). Triggered by "/go-no-go [project]", any "I want to build / start / take on X" intent, or before opening any new repo or signing any new contract. Pairs with spec-driven-dev (this is Stage 0, that is Stage 1).
Use BEFORE invoking the Task or Agent tool to spawn a subagent. Anthropic does NOT share prefix cache across subagents — every subagent cold-starts and re-tokenizes its full prompt (system prompt + tool definitions + the context you handed it). Spawning N subagents with full context = N× token cost; a single fan-out can burn an entire Max-plan day. This skill enforces a pre-flight discipline: compress every subagent prompt into a ≤200-word brief before spawning. Triggers when the agent is about to call Task / Agent tool, especially with long files, full repo dumps, or N parallel subagents on similar work.
Use when an agent will work for hours or days across many files and multiple vertical slices. Drives a three-level Project → Sprint → Task hierarchy with isolated per-task execution, a review round-loop, context packs for subagent reviewers, governance-as-code, and orchestrator-readable state. Designed for long-running drivers like /loop, autoresearch:ship, and goal-driven.
Use when you have N≥3 raw research artifacts (notes, podcast summaries, deep-research dumps, daily intel, paper analyses) on one topic and want to lift them into a single structured pack with cross-source claims and provenance — instead of one-shot summarization that loses 90% of intermediate evidence. Treats the N sources as an environment a lite aggregator agent navigates with `inspect` / `search` / `synthesize` tools, rather than concatenating into one prompt.
Use when debugging any non-trivial bug — wrong output, crash, flaky test, performance regression, or "it works locally but not in CI." Forces a scientific-method loop (Observe → Hypothesize → Experiment → Conclude) so the agent stops guessing and starts reasoning. Prevents the
Generate or edit images with Google's Nano Banana 2 (`gemini-3.1-flash-image-preview`). Use when the user asks to generate an image, edit an image, or create a picture. Supports 512 / 1K / 2K / 4K resolutions.
| name | tavily-search |
| description | Web search and content extraction via the Tavily API. Use when you need real-time web results, citations, or raw article content without a browser. Requires TAVILY_API_KEY. |
Headless web search and content extraction using Tavily. Built for LLM agents — returns clean, summarised results with optional raw article bodies. No browser required.
Get a free API key: https://app.tavily.com (1000 free searches/month)
Export it:
export TAVILY_API_KEY="tvly-YOUR_KEY_HERE"
Add to ~/.zshrc or ~/.bashrc for persistence. Never commit the key.
First run will auto-install dependencies via uv:
command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
# 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" --json
| 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 |
uv run .../search.py --extract https://example.com/article
Returns clean markdown of the page body (no nav, ads, or boilerplate).
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.
Research a library:
uv run .../search.py "Gemini 3 Flash Image API pricing" --depth advanced
Get the full article body of a blog post:
uv run .../search.py --extract https://blog.example.com/post --json > post.json
News sweep:
uv run .../search.py "OpenAI Codex release" --topic news --days 3 --max-results 10
--api-key flag → $TAVILY_API_KEY → $TAVILY_KEYsearch and extract endpoints (v1)| Error | Fix |
|---|---|
Error: No TAVILY_API_KEY | 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 |
--raw-content with --max-results 20 on every query (burns tokens)$TAVILY_API_KEY is set in env, not in filesuv run .../search.py "hello world" returns resultsgitleaks detect --source . clean