SkillAgentSearch skills...

agent-web-search-setup

Fixes web search on an agent whose model backend can't run it: a relay/reseller proxying Claude or Codex returns empty instead of failing

Install / Use

npx skills add daymade/claude-code-skills --skill agent-web-search-setup

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Supported Platforms

Claude Code
OpenAI Codex

Tags

Our assessment of agent-web-search-setup

agent-web-search-setup scores 93/100 on our quality scale, 716th of 4,700 Development & Engineering skills we index (top 16%).

Its SKILL.md is 37 KB long, well organised into 9 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.

With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so agent-web-search-setup is actively maintained.
  • Our last check on 2026-10-26 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

Review

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa.

AI review: risky

  • The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa
  • It directs the agent to disable built-in web search safeguards (permissions.deny for WebSearch/WebFetch and web_search = "disabled" in Codex config) and replace them with a third-party MCP server, a significant configuration change under ag
  • It has the agent read API credentials from client config files and pass them to a local diagnostic script, and to run verification commands that modify user config files; while not exfiltratory, it involves credential handling and config ed

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

agent-web-search-setup compared with similar skills

All 4 of these similar skills score higher than agent-web-search-setup; compare them before choosing.

SkillScoreStarsUpdatedFormat
agent-web-search-setup (this skill)by daymade931.4k53d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install agent-web-search-setup?
Run npx skills add daymade/claude-code-skills --skill agent-web-search-setup. The install tabs above show the steps for each supported agent.
Which AI agents does agent-web-search-setup work with?
It is written for Claude Code and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
Is agent-web-search-setup safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is agent-web-search-setup still maintained?
The repository was last updated about 2 months ago, so agent-web-search-setup is actively maintained.

name: agent-web-search-setup description: >- Fixes web search on an agent whose model backend can't run it: a relay/reseller proxying Claude or Codex returns empty instead of failing. Use when web search returns nothing, a model insists a shipped product doesn't exist, someone wants to give an agent internet access, or the user is on a third-party base URL, relay, or 中转站. Diagnoses which built-in tools are dead, removes them, and installs a working replacement.

Agent Web Search Setup

A model backend that cannot search is not the same as a model that searched and found nothing, but from inside the conversation the two look identical. This skill turns the first into the second, on whichever agent is in front of you. It configures the agent's tools; it is not itself a search engine, so nothing here answers a query directly — the proof of done is the agent's own session calling a real tool.

What actually breaks

Anthropic's web_search and web_fetch are server tools: the API runs them during the request and splices results into the same response. OpenAI's Responses API web_search works the same way. The client only ever declares the tool.

A reseller that proxies to another cloud cannot execute those. Anthropic's own documentation states that web fetch is unavailable on Amazon Bedrock and Google Cloud; search was measured failing the same way on both. What comes back is not an error. It is an empty shell, so the model concludes the topic does not exist and says so with total confidence. That is the whole bug, and it is why users report their agent has "gotten stupid" rather than reporting a broken tool.

Three things follow, each of which cost real time to establish:

  • Switching models does not help. One reseller was measured routing four model names to three different backends; none produced a working search.
  • web_fetch breaks with it. Fixing only search moves the failure from "I found nothing" to "I found links but cannot open them."
  • Installing an alternative is not enough on its own. With the dead tool still on the menu, a model made 21 web-search calls and 0 calls to an installed alternative whose description said the built-in was broken. Built-in tools win head-to-head. The dead tool has to be removed, or nothing else you do matters.

1. Prove it, on this machine

Do not take the user's word for which tool is broken, and do not take yours.

<skill> below is the directory holding this SKILL.md — substitute the real path. If it is somehow not known, find ~ -type d -name agent-web-search-setup locates it.

python3 <skill>/scripts/diagnose.py

It reads ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL, or the OPENAI_ equivalents under --api openai, or takes --url --key --model. Exit codes: 0 nothing to fix, 1 at least one tool is dead, 2 undetermined. --json for parsing.

Those values are usually not in the shell — go and read them out of the client. A person on a relay set it up through a provider switcher or a settings screen, not by exporting variables, so a plain shell sees nothing and the probe stops before it starts. For Claude Code they live in the env block of ~/.claude/settings.json; for Codex, the base URL is under [model_providers.*] in ~/.codex/config.toml and the key is in ~/.codex/auth.json. Read them from there and pass them with --url and --key. Never print the key.

This step needs a working python3, and on a fresh Mac that is one dialog. /usr/bin/python3 ships as a stub that opens the Command Line Tools installer the first time it is called. Expect it, and say so before it appears rather than after. The script itself is standard library only and runs on the 3.9 that macOS ships, so nothing else has to be installed — which is exactly the difference between this one dialog and an MCP server that wants Node plus an SDK.

It reports a verdict per tool and names the real backend from the tool-call id prefix (toolu_vrtx_ Vertex AI, toolu_bdrk_ Bedrock, ws_ an OpenAI hosted tool). A model that simply declined to call the tool is reported as inconclusive, not as broken; re-run or try another model rather than treating silence as evidence.

Slow is not dead, and the difference is easy to get wrong. One gateway was measured answering in about 15 seconds on two model ids and about 146 on a third. A timeout set between those two numbers reports a perfectly healthy endpoint as broken, which is the same misdiagnosis this skill exists to correct. The default allows for the slow case; if you shorten it, a timeout still reports inconclusive rather than a verdict.

Codex reaches its backend through a different API, so probe that one. Its hosted search lives in the OpenAI Responses API, where a working endpoint returns a web_search_call item. --api openai asks there. Asking only the Anthropic shape leaves a Codex user with no verdict at all.

The commonest way that probe fails is not a refusal — it is a missing route, and that is more decisive than it looks. A relay measured here answers the older /v1/chat/completions with HTTP 200 and returns HTTP 404 for /v1/responses. Both facts matter together: the endpoint really is OpenAI-compatible, and it simply does not implement the surface hosted tools are served through. So hosted search cannot run there at all, and for Codex that settles the whole question, because that route is the one its hosted tools use. The probe makes this second request itself and reports unavailable; a 404 with no working Chat Completions route stays inconclusive, because then the key or the base URL is the likelier fault.

The two APIs do not share a model namespace, so --api both also needs --openai-model (or OPENAI_MODEL). Without one the OpenAI probe is skipped and says so, rather than sending a Claude model id to /v1/responses and collecting a 400 about the model that reads exactly like a verdict about the tool.

On the Codex side the setting is web_search. The values seen were disabled, cached, indexed and live, but treat that list as a snapshot: an invalid value makes Codex print the full set itself, which is both the fastest way to confirm the current syntax and the only one that cannot go stale.

If every probe comes back working, stop and look elsewhere before configuring anything. The tools are fine on that endpoint, so installing a replacement adds a second way to search without fixing the first. Two causes have been seen on real machines: another installed component answers search-shaped requests before any tool is considered, and a client whose own setting turns search off. Both look exactly like a dead backend from inside the conversation.

2. Remove the dead tools

Only the tools diagnose.py actually reported dead. Removing a working tool is a regression, not a safety margin.

| Agent | Where | What | |---|---|---| | Claude Code, terminal or the Code surface of the desktop app | ~/.claude/settings.json | add the dead tool names to permissions.deny | | Codex | ~/.codex/config.toml | web_search = "disabled" | | Claude Desktop, the chat surface | not a supported target | see below |

The client spells these differently from the API, and the wrong spelling fails silently. diagnose.py reports web_search and web_fetch, because that is what the API calls them. A deny list takes WebSearch and WebFetch. Writing the API spelling into permissions.deny matches no tool at all, so the file changes, the run reports success, and the tool is still on the model's menu — the same dead end as not editing anything. The diagnostic prints the client spelling next to its conclusion for this reason; use that one.

A bare tool name in permissions.deny removes the tool from the model's context entirely, which is what you want. Verified by reading the session's init event: the tool is absent from the list the model receives, rather than present with advice against using it.

That event is referred to several times below, so here is how to actually get it. Do not reach for the first line — on a machine with SessionStart hooks configured it was measured arriving as line 24 of 24, behind the hooks' own output. Filter by type instead, which is what this does:

claude -p "reply ok" --output-format stream-json --verbose < /dev/null > /tmp/init.jsonl
python3 -c "
import json
for line in open('/tmp/init.jsonl'):
    d = json.loads(line)
    if d.get('type') == 'system' and d.get('subtype') == 'init':
        print('WebSearch:', 'WebSearch' in d['tools'], ' WebFetch:', 'WebFetch' in d['tools'])
        break"

Two False values mean the tools are gone from what the model receives. The same event carries permissionMode, which is worth reading at the same time for the reason given in step 4.

A deny travels further than a grant does, and that asymmetry matters in step 4. permissions.deny is honoured out of a project's own .claude/settings.json even in a directory nobody has ever trusted — measured there by reading the init event, which listed 24 tools with WebSearch and WebFetch absent and printed no warning. The grant in step 4 does not behave this way. A restriction arriving from an untrusted file is safe to obey; a privilege is not, and the client is right to treat the two differently.

A second asymmetry, this one about synchronisation, decides where the deny goes on a multi-profile machine. Step 4 sends the grant to the profile the others sync from, because a synchroniser that converges settings.json drops it anywhere else. The deny cannot follow it there: the source profile is the one every other profile copies from, so a deny placed in it lands on profiles whose built-in search works, and removing a working tool is the regression the top of this step warns against. The layer that is both per-profile and out of the synchroniser's reach is the settings file the profile launcher passes with --settings; claude-switch-models-setup in this same marketplace documents that file and the measurement showing a deny taking effect from it. Getting this wrong has a symptom worth recognising on sight: the fix works in the session that made it and stops working after the restart you asked the user to do, which reads as the restart not taking rather than as something rewriting the file.

Both edits are small enough to show literally, which beats describing a shape the reader then has to build:

{ "permissions": { "deny": ["WebSearch", "WebFetch"] } }
web_search = "disabled"

That TOML line has to go above the first [table] header in the file, and appending it to the end is the way to get this wrong. It is a bare key, so TOML binds it to whatever table precedes it — drop it after a [model_providers.…] block, which step 1 has just sent you into that same file to read, and it becomes model_providers.<name>.web_search, a setting nothing reads. The file changes, the command succeeds, and hosted search is still on. Put it on its own line at the top of the file and read the file back.

Merge, never replace. These files hold the user's own configuration. Add the one key and leave the rest byte-identical. Show them the before and after.

Prefer pointing at a key over copying one in. Where the client supports reading a credential from the environment, register that reference rather than writing the secret into a config file. These files get screenshotted into help requests and shared wholesale; a key pasted into one travels with it.

The desktop app is two clients, not one. Its Code surface runs a real claude binary the app downloads and carries the Claude Code settings engine, so the row above covers it. The app's own bundle settles where that engine looks: the config root is the value held in the app's settings store if one is set, otherwise `process.env.CLAUDE_CONFIG_DI

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.4k
CategoryDevelopment
Updated1mo ago
Forks219

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions