Skip to content
Get packs

Guide · Agent skill

How to use the Tavily Web Search Best Practices agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The tavily-best-practices skill is a reference guide that teaches an AI agent how to use Tavily's Python and JavaScript libraries for live web search, page extraction, site crawling and research. It is written for developers building RAG pipelines or autonomous agents. After this guide you will know how to install the skill, ask for web-search features in a way that triggers it, and what you need before the code will run.

Tavily Web Search Best Practicesandrewyng/context-hub · MIT

Quick start

  1. 1Download the ZIP. Download the tavily-best-practices ZIP from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder.
  3. 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill there instead.
  4. 4Install the Tavily SDK. Run pip install tavily-python for Python or npm install @tavily/core for JavaScript.
  5. 5Set your API key. Create a Tavily account, get an API key and store it in the TAVILY_API_KEY environment variable.
  6. 6Ask for a Tavily feature. Describe the search, extraction, crawl or research feature you want and mention Tavily or live web data.

What the skill makes the agent do

Tavily is a search API designed for LLMs, giving AI applications access to real-time web data. Without guidance, an agent may guess at the API. With this skill loaded, it follows the patterns in the skill's reference files when you ask for a web-search or RAG feature.

The skill covers five methods: search() for web results, extract() for content from specific URLs, crawl() for content from an entire site, map() for URL discovery, and research() for end-to-end research with AI synthesis. It also covers client setup and key options for each method.

Install the skill

Download the ZIP from this page. Then choose one of two routes.

For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Install the Tavily libraries and set your API key

The skill needs the Tavily SDK for the language you use. Install tavily-python for Python or @tavily/core for JavaScript. The client reads your key from the TAVILY_API_KEY environment variable, which the skill recommends over passing the key in code.

  • Python and/or Node.js must be installed
  • A Tavily account and API key are required; code examples will not run without one
  • Optional: LangChain, LlamaIndex, CrewAI or Vercel AI SDK if you use those integrations
pip install tavily-python npm install @tavily/core

Trigger the skill with natural requests

You do not need a special command. Describe the web-search or extraction feature you want in plain language, and mention Tavily or live web data so the agent knows which API to follow. The skill's description covers web search, content extraction, crawling and research in agentic workflows, RAG systems and autonomous agents.

Good requests name the goal and the data source, for example: asking for a function that searches the web for recent results and feeds them into a RAG prompt, or asking for a crawler that collects documentation pages from one site. Asking the agent to pick between search, extract, crawl and map is also a valid request.

  • Ask for a search feature: "Add Tavily search to my agent so it can answer questions about recent quantum computing news."
  • Ask for extraction: "Use Tavily to pull the main text from these three documentation URLs."
  • Ask for a site crawl: "Crawl the docs site and collect the API reference pages for my RAG index."
  • Ask for a method choice: "Should I use Tavily crawl or map to list the pages on this site?"

Understand the methods and their key options

Choose the method by the job. Use search() when you need web results. Use extract() when you already have URLs. Use crawl() when you need full content across a site, and map() when you only need URLs. Use research() for a multi-topic report with AI synthesis.

The skill names the main parameters for each method. For search these include query (keep under 400 characters), max_results, search_depth (ultra-fast, fast, basic or advanced), include_domains, exclude_domains and time_range. For extract, urls (max 20), extract_depth, query and chunks_per_source (1-5) matter most. Crawl's key parameters include url, max_depth, max_breadth, limit, instructions, select_paths and exclude_paths.

  • Crawl returns full content and is slower; map returns URLs only and is faster.
  • research() takes a model of "mini", "pro" or "auto" and is polled with get_research() until it completes or fails.
from tavily import TavilyClient client = TavilyClient() response = client.search( query="quantum computing breakthroughs", max_results=10, search_depth="advanced" ) print(response)

Use the framework references when you need them

If you use LangChain, LlamaIndex, CrewAI or the Vercel AI SDK, the agent can read the integrations reference for setup patterns. For LangChain, the skill recommends the official langchain-tavily package, and warns that the older langchain_community tavily search tool is deprecated.

The skill also includes detailed reference files for search, extract, crawl, research and the SDK itself, so the agent can look up exact parameters before writing code.

  • langchain-tavily is the recommended LangChain package (install with pip install -U langchain-tavily)
  • Reference files: sdk.md, search.md, extract.md, crawl.md, research.md, integrations.md
pip install -U langchain-tavily

Safety notes: scripts and network use

This skill does not run scripts. It is a set of reference documents that guide code the agent writes for you. It does use the network: every query and every crawled page is sent to Tavily's API, so do not use it where data must stay out of third-party services.

Review the code the agent produces before running it, and keep your TAVILY_API_KEY in an environment variable rather than in source files.

  • Runs scripts: no
  • Uses network: yes, queries and crawled pages go to Tavily's API

What people use it for

  • Adding live web search to a customer-support agent so it can answer with current information
  • Building a RAG pipeline that searches the web, extracts page content and feeds it into a prompt
  • Crawling a documentation site to collect API reference pages for a knowledge base
  • Using map() to list a site's URLs before deciding which pages to extract
  • Wiring Tavily search into a LangChain or LlamaIndex agent

Frequently asked questions

Is the tavily-best-practices skill free?

The skill is published under the MIT licence. Tavily's API itself requires an account and API key, so check Tavily's own terms for usage and any costs; this guide does not state pricing.

What do I need before the code examples will run?

You need Python with tavily-python and/or Node.js with @tavily/core, plus a Tavily API key stored in the TAVILY_API_KEY environment variable. Optional integrations need LangChain, LlamaIndex, CrewAI or Vercel AI SDK.

How do I install the skill in Claude?

Download the ZIP and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Is this a search tool I can use myself?

No. It is a coding reference that helps an agent write Tavily integration code. If you only want to search the web yourself, use a search tool directly rather than this skill.

Does the skill run scripts or send my data anywhere?

It does not run scripts. It does use the network, because every query and crawled page is sent to Tavily's API, so avoid it for data that must stay with you.

Should I use crawl or map?

Use crawl when you need full content for RAG or deep analysis. Use map when you only need URLs for site structure discovery or planning before crawling, since map is faster and returns URLs only.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you are a developer adding live web search, extraction or crawling to an agent or RAG pipeline and you already have a Tavily account. Skip it if you only want to search the web yourself, if your data cannot leave your own systems, or if you do not want to write and review code.

Download the skill