Skip to content
Get packs

Guide · Agent skill

How to use the Add Tavily Search and Extract agent skill

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

The add-tavily-tool skill gives agents in a NanoClaw deployment two web tools from Tavily: a search tool and a tool that extracts content from a URL. It works without an API key at first, using Tavily's keyless shared allowance. This guide explains what the skill changes, how to install it, how to ask an agent to use it, and what to check before you run it on a shared host.

Add Tavily Search and Extractnanocoai/nanoclaw · MIT

Quick start

  1. 1Download and install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
  2. 2Check prerequisites. Confirm you have a NanoClaw checkout with ncl and pnpm, Docker, Node.js with vitest, and network access to mcp.tavily.com.
  3. 3Add the mcp-remote bridge. Add the mcp-remote entry to container/cli-tools.json if it is not already there, then build the image with container/build.sh.
  4. 4Register Tavily for chosen groups. Run ncl groups config add-mcp-server for each selected group, then wait for approval if the command is gated.
  5. 5Restart and verify. Restart each group with ncl groups restart, then confirm with ncl groups config get that the tavily entry and both headers are present.
  6. 6Ask for a search. Request a single Tavily search in a chat with the agent and confirm it uses mcp__tavily__tavily_search.

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that tells an AI agent how to carry out a specific task. This skill sets up the NanoClaw agent system so that selected agent groups can call Tavily, a web search and page extraction service, as tools.

Once installed, the registered server exposes two tools: mcp__tavily__tavily_search and mcp__tavily__tavily_extract. The skill limits the tools to these two. Tavily's Crawl, Map and Research tools are filtered out.

  • Installs a pinned mcp-remote bridge into the agent container image.
  • Registers Tavily's remote MCP server for the agent groups you choose.
  • Does not require an API key at first.
  • Adds instructions for when the shared free allowance runs out, so the agent can guide an operator to a paid key stored in the OneCLI vault.

Check whether this skill fits your setup

The skill is most useful for groups on non-Claude providers, which do not have built-in web tools. The skill notes that groups on the Claude provider already have built-in WebSearch and WebFetch tools, so the gain is smaller there, though Tavily's structured extraction is still available to them.

The keyless allowance is shared by every group on the host. On a shared or production host it can run out without warning, so only install it there if you are ready to manage a paid key and gateway configuration.

  • Good fit: operators of a NanoClaw deployment, teams on non-Claude providers, and developers who want to try Tavily without signing up first.
  • Poor fit: Claude-provider groups that do not need structured extraction, shared hosts you cannot afford to run out of allowance on, and anyone unfamiliar with NanoClaw's container, OneCLI and ncl tooling.

Install the skill in the Claude apps or Claude Code

Download the skill ZIP from this page. You can install it in two ways, depending on how you use Claude.

For Claude Code, unzip the download into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project

Set up the Tavily tools in a NanoClaw deployment

The setup steps edit NanoClaw configuration, rebuild the agent image and restart agent groups. Run them from a NanoClaw repository checkout, which needs the ncl CLI, pnpm, Docker and Node.js with vitest.

First, check whether the bridge is already in the manifest and list your groups. Then add the mcp-remote entry to container/cli-tools.json if it is not already present, build the image and run the dependency guard test.

Next, register the tavily server for each selected group with ncl groups config add-mcp-server. Restart each group afterwards. The config add-mcp-server and groups restart commands are approval-gated, so when run from inside a container they return approval-pending; wait for the admin's approval before continuing.

  • Requires: NanoClaw checkout with ncl and pnpm, Docker, Node.js with vitest, and network access to mcp.tavily.com.
  • Optional: a free Tavily API key and a running OneCLI gateway for the upgrade path.
ncl groups config add-mcp-server --id <group-id> --name tavily --command mcp-remote --args '["https://mcp.tavily.com/mcp/","--transport","http-only","--enable-proxy","--header","X-Tavily-Access-Mode:keyless","--header","X-Client-Name:nanoclaw","--ignore-tool","tavily_crawl","--ignore-tool","tavily_map","--ignore-tool","tavily_research"]' --env '{}'

Verify the Tavily tools work

Check the stored configuration to confirm the group has one tavily server with both headers. Then check the agent's test response: the call must use mcp__tavily__tavily_search, and Crawl, Map and Research must not appear in the Tavily namespace.

If the test fails, the troubleshooting list below covers the common causes.

  • Restore all three --ignore-tool pairs if Crawl, Map or Research appears.
  • If Tavily tools are absent, confirm the tavily MCP entry exists and restart the group.
ncl groups config get --id <group-id>

Ask the agent to use Tavily in plain language

After setup, you do not need special syntax. Ask the agent in ordinary words to search the web or to read a page, and it can use the Tavily search or extract tool. The skill's own description says it applies when you are installing Tavily web search or URL extraction without an API key.

If you want to confirm the tools are live, ask for a single short search. The setup restart message asks the agent to run one Tavily search with max_results set to 1 and report whether it succeeds.

  • Search: ask for current information on a topic and request a few results.
  • Extract: give the agent a specific URL and ask for its content.
  • Check: ask for one search with one result to test the connection.

What people use it for

  • Letting a non-Claude agent group search the web for current information.
  • Having an agent extract the content of a specific URL in a structured form.
  • Trying Tavily search on a development host before deciding whether to buy a paid key.
  • Giving a team's agent group web search while keeping Crawl, Map and Research disabled.

Frequently asked questions

Is the add-tavily-tool skill free?

The skill's source is published under the MIT licence. Tavily's keyless allowance is shared across all groups on a host, and the upgrade block says free Tavily accounts include 1,000 credits per month; check Tavily's own documentation for current terms.

Do I need a Tavily API key to use this skill?

No. The skill registers Tavily's remote server using the keyless header, so it works without a key at first. A key is only needed after the shared keyless allowance is used up.

What requirements does the add-tavily-tool skill have?

You need a NanoClaw repository checkout with the ncl CLI and pnpm, Docker, Node.js with vitest, and network access to mcp.tavily.com. A free Tavily key and a running OneCLI gateway are optional, for the upgrade path.

Why does Tavily return a 429 error or monthly_cap_reached_bonus_eligible?

Those responses mean the shared keyless allowance for the host is exhausted. The skill's upgrade path lets the agent guide an operator to create a free API key and store it in the OneCLI vault, then attach it to the group.

Does the skill let the agent see my API key?

According to the upgrade instructions, the key goes straight into the OneCLI credential vault through the dashboard, and the agent never sees it. The key is attached to the group on the host with the OneCLI CLI.

How is this different from Claude's built-in WebSearch and WebFetch?

Groups on the Claude provider already have WebSearch and WebFetch. The skill says it adds the most value for groups on other providers, and for Tavily's structured page extraction on any provider.

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

Use this skill if you run NanoClaw, want web search on non-Claude agent groups, and are comfortable editing configuration, rebuilding the image and restarting groups. Pick something else if you have a shared production host you cannot risk running out of the keyless allowance on, or if your groups already have the built-in web tools and you do not need Tavily's structured extraction.

Download the skill