| name | web-search |
| description | Default for web lookup/research/latest/current/URL/package/docs questions. Uses kagi→codex→claude-code→openai-cli→perplexity, escalating only if needed. Prefer this over provider skills unless user explicitly names kagi, perplexity, codex/claude-code/openai-cli, or ai-search. |
| allowed-tools | ["Bash","Read"] |
Web Search (tiered)
Single entry point for web research. Runs providers in a strict cost/speed order
and lets you escalate when the previous tier's answer is not good enough.
Tier order (always follow)
| Tier | Provider | Why first / when |
|---|
| 1 | kagi quick | Fastest grounded answer, source confidence %, free w/ subscription |
| 2 | codex | Deeper synthesis, clean canonical URLs, code-aware; uses gpt-5.5 with low reasoning |
| 3 | claude-code | Second analytical opinion when codex hedges or gets it wrong; uses Haiku 4.5 with low thinking |
| 4 | openai-cli | OpenAI API web-search fallback; uses gpt-5.3-chat-latest |
| 5 | perplexity | Most citations, last resort for hard or very recent topics |
Always start at tier 1. Only escalate to the next tier if the current
answer is insufficient (vague, hedged, missing key facts, contradicts known
truth, no real URLs, or explicitly says it could not find X).
Do not call multiple tiers in parallel — the whole point is to save tokens
and time when tier 1 already answers the question.
Usage
Single script, one provider per call:
~/.agents/skills/web-search/search.sh --provider <kagi|codex|claude-code|openai-cli|perplexity> "<query>" [--purpose "<why>"]
Examples:
~/.agents/skills/web-search/search.sh --provider kagi \
"latest stable Firefox version macOS user agent" \
--purpose "update hardcoded UA in nvim plugin"
~/.agents/skills/web-search/search.sh --provider codex \
"latest stable Firefox version macOS user agent" \
--purpose "update hardcoded UA in nvim plugin"
~/.agents/skills/web-search/search.sh --provider claude-code "..."
~/.agents/skills/web-search/search.sh --provider openai-cli "..."
~/.agents/skills/web-search/search.sh --provider perplexity "..."
Escalation rubric
After each tier's output, ask yourself:
- Did it answer the actual question? A hedge ("not directly available")
counts as no — escalate.
- Are there real canonical URLs (not just titles, not redirect wrappers)?
If no, escalate.
- Does the data look current? If purpose mentions "latest" and the answer
cites an old version, escalate.
- Did sources disagree without resolution? Escalate to corroborate.
If tier-1 answer satisfies all four → stop. Don't run tier 2+.
Provider notes
- kagi: requires
KAGI_API_KEY env (already set) and ~/.kagi.toml with
session token. Wrapper does cd $HOME automatically. Output includes
source confidence percentages and follow-up questions.
- codex / claude-code / openai-cli: thin wrappers over the
ai-search skill's search.mjs, using its current model defaults and
reasoning settings.
- openai-cli: additionally requires the
openai binary on PATH and
OPENAI_API_KEY in the environment.
- perplexity: requires
PERPLEXITY_API_KEY env. Wraps perplexity-search
skill's --ask mode (sonar model).
When NOT to use this skill
- For raw search results with no synthesis → use
kagi search or
perplexity --search directly.
- For deep research reports → use
perplexity --deep directly.
- For reading a known URL → use
defuddle or summarize skill, not search.
Related skills (kept for specialized use)
kagi — full kagi-cli toolbox (translate, summarize, news, batch, etc.)perplexity-search — search/research/reason/deep modesai-search — direct provider control for codex/claude-code/openai-cli
