| name | web-search |
| description | Search the live web for a query and return ranked results (title, URL, snippet) as JSON. Works with no API key (DuckDuckGo HTML fallback) and uses the Brave Search API or SerpAPI automatically when BRAVE_API_KEY / SERPAPI_KEY is set. Any agent can call it for research, competitor analysis, market/trend lookups, fact-checking, finding sources to cite, or grounding a non-software goal (marketing, growth, commerce) in real-world information. |
| category | research |
| assignableRoles | ["*"] |
| version | 1.0.0 |
| tags | ["search","web","research","competitor-analysis","market-research","sources","brave","serpapi","duckduckgo"] |
Web Search
Search the live web and get back ranked results as JSON. This is the agent's
window onto the real world — use it for research, competitor/market analysis,
trend lookups, fact-checking, and finding sources to cite. It is the
load-bearing tool for non-software goals (marketing, growth, commerce) that
need real information, not just the model's training data.
Usage
bash {{AGENT_SKILLS_PATH}}/web-search/execute.sh "best protein powder for runners 2026"
bash {{AGENT_SKILLS_PATH}}/web-search/execute.sh --query "competitors of Notion" --limit 5
bash {{AGENT_SKILLS_PATH}}/web-search/execute.sh '{"query":"shopify conversion rate benchmarks","limit":8}'
--query / positional / JSON {"query":...} — the search query (required).--limit N / JSON limit — max results (default 8, capped at 20).
Output
Newline-free JSON on stdout:
{
"query": "competitors of Notion",
"provider": "brave",
"results": [
{ "title": "...", "url": "https://...", "snippet": "..." }
]
}
On failure it still returns valid JSON with an empty results array and an
error field, so callers can branch without parsing stderr.
Providers (auto-selected, best → fallback)
- Brave Search API — when
BRAVE_API_KEY is set. Clean JSON, best quality.
- SerpAPI (Google) — when
SERPAPI_KEY is set.
- DuckDuckGo HTML — no key required. Best-effort scrape of titles + URLs;
snippets may be sparse. Always available so the skill works out of the box.
Set a key in your .env (BRAVE_API_KEY=... — free tier at
https://brave.com/search/api/) for higher-quality, rate-limit-friendly results.
Notes
- Read-only: this skill only fetches search results; it never posts, buys, or
changes anything.
- Respects a 15s network timeout and returns whatever it has.
