smart-search
Intelligent web search routing across Gemini and Brave APIs with quota management, circuit breaker, and web_fetch fallback. Routes finance queries to Gemini, space/astronomy to Brave, with per-agent daily allocations and shared pool.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/airaalfredsf/aira-smart-searchsmart-search
1. WHAT THIS SKILL DOES
This skill routes search queries to the best available provider, manages daily API quota per agent, logs all searches, and degrades gracefully through web scraping when APIs are unavailable. It supports two execution strategies: scheduled agents that prioritise API calls for reliable results, and a general agent that preserves API quota by trying web scraping first. All quota state is persisted to a shared JSON file so multiple agents can coordinate without overrunning daily limits.
2. WHEN TO INVOKE THIS SKILL
Use this skill whenever an agent needs to search the web for information — news, research, stock data, general queries, or any topic requiring up-to-date results.
This skill exposes three tools:
| Tool | Purpose |
|---|---|
smart_search | Execute a web search and return results |
search_quota_status | Check remaining quota for an agent or the full system |
search_mark_agent_complete | Release unused quota to the shared pool when an agent finishes |
3. TOOL REFERENCE
smart_search
Executes a search query using the best available provider for the given agent.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The search query. Max 1000 characters. No control characters. |
agent_id | string | Yes | Lowercase letters, numbers, and hyphens only (e.g. stock-analysis). Use general for manual/chat searches. |
force_provider | string | No | Override routing. Accepts "gemini" or "brave" only. |
Return shape:
{
"results": "<string or array>",
"provider_used": "gemini | brave | web_fetch",
"queries_remaining": 12,
"quota_source": "agent_allocation | shared_pool | provider_direct | none",
"fallback_used": false,
"warning": null,
"web_fetch_engine": null,
"error": null
}
On failure results is null and error contains the reason.
search_quota_status
Returns quota information for a specific agent or the full quota file.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | No | If omitted, returns the full quota object. |
Return shape (single agent):
{
"agent_id": "stock-analysis",
"gemini": { "allocated": 15, "used": 3, "remaining": 12 },
"brave": { "allocated": 0, "used": 0, "remaining": 0 },
"completed": false
}
search_mark_agent_complete
Marks an agent as done for the day and releases any unused allocation to the shared pool for other agents to use.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent to mark complete. |
Return shape:
{
"agent_id": "tech-news",
"released": { "gemini": 7, "brave": 0 },
"message": "Agent marked complete. 7 Gemini calls released to shared pool."
}
4. TWO EXECUTION STRATEGIES
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-airaalfredsf-aira-smart-search": {
"enabled": true,
"auto_update": true
}
}
}