Serper
Google search via Serper API. Fetches results AND reads the actual web pages to extract clean full-text content via trafilatura. Not just snippets — full article text.
Constraint
This skill already fetches and extracts full page content. Do NOT use WebFetch, web_fetch, WebSearch, browser tools, or any other URL-fetching/browsing tool on the URLs returned by this skill. The content is already included in the output. Never follow up with a separate fetch — everything you need is in the results.
Query Discipline
Craft ONE good search query. That is almost always enough.
Each call returns multiple results with full page text — you get broad coverage from a single query. Do not run multiple searches to "explore" a topic. One well-chosen query with the right mode covers it.
At most two calls if the user's request genuinely spans two distinct topics (e.g. "compare X vs Y" where X and Y need separate searches, or one default + one current call for different aspects). Never more than two.
Do NOT:
- Run the same query with different wording to "get more results"
- Run sequential searches to "dig deeper" — the full page content is already deep
- Run one search to find something, then another to follow up — read the content you already have
Two Search Modes
There are exactly two modes. Pick the right one based on the query:
default — General search (all-time)
- All-time Google web search, 5 results, each enriched with full page content
- Use for: general questions, research, how-to, evergreen topics, product info, technical docs, comparisons, tutorials, anything NOT time-sensitive
current — News and recent info
- Past-week Google web search (3 results) + Google News (3 results), each enriched with full page content
- Use for: news, current events, recent developments, breaking news, announcements, anything time-sensitive
Mode Selection Guide
| Query signals |
Mode |
| "how does X work", "what is X", "explain X" |
default |
| Product research, comparisons, tutorials |
default |
| Technical documentation, guides |
default |
| Historical topics, evergreen content |
default |
| "news", "latest", "today", "this week", "recent" |
current |
| "what happened", "breaking", "announced", "released" |
current |
| Current events, politics, sports scores, stock prices |
current |
Locale
Default is global — no country filter, English results. This ONLY works for English queries.
You MUST ALWAYS set --gl and --hl when ANY of these are true:
- The user's message is in a non-English language
- The search query you construct is in a non-English language
- The user mentions a specific country, city, or region
- The user asks for local results (prices, news, stores, etc.) in a non-English context
If the user writes in German, you MUST pass --gl de --hl de. No exceptions.
| Scenario |
Flags |
| English query, no country target |
(omit --gl and --hl) |
| German query OR user writes in German OR targeting DE/AT/CH |
--gl de --hl de |
| French query OR user writes in French OR targeting France |
--gl fr --hl fr |
| Any other non-English language/country |
--gl XX --hl XX (ISO codes) |
Rule of thumb: If the query string contains non-English words, set --gl and --hl to match that language.
How to Invoke
python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG]
Examples
# English, general research
python3 scripts/search.py -q "how does HTTPS work"
# English, time-sensitive
python3 scripts/search.py -q "OpenAI latest announcements" --mode current
# German query — set locale + current mode for news/prices
python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de
# German news
python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de
# French product research
python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr
Output Format
The script streams a JSON array. The first element is metadata, the rest are results with full extracted content:
[{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}]}
,{"title": "Page Title", "url": "https://example.com", "source": "web", "content": "Full extracted page text..."}
,{"title": "News Article", "url": "https://news.com", "source": "news", "date": "2 hours ago", "content": "Full article text..."}
]
| Field |
Description |
title |
Page title |
url |
Source URL |
source |
"web", "news", or "knowledge_graph" |
content |
Full extracted page text (falls back to search snippet if extraction fails) |
date |
Present when available (news results always, web results sometimes) |
CLI Reference
| Flag |
Description |
-q, --query |
Search query (required) |
-m, --mode |
default (all-time, 5 results) or current (past week + news, 3 each) |
--gl |
Country code (e.g. de, us, fr, at, ch). Default: world |
--hl |
Language code (e.g. en, de, fr). Default: en |
Edge Cases
- If trafilatura cannot extract content from a page, the result falls back to the search snippet.
- Some sites block scraping entirely — the snippet is all you get.
- If zero results are returned, the script exits with
{"error": "No results found", "query": "..."}.
- The Serper API key is loaded from
.env in the skill directory. If missing, the script exits with setup instructions.
1---2name: openclaw-serper3description: Searches Google and extracts full page content from every result via trafilatura. Returns clean readable text, not just snippets. Use when the user needs web search, research, current events, news, factual lookups, product comparisons, technical documentation, or any question requiring up-to-date information from the internet.4license: MIT5---6
7# Serper
8
9Google search via Serper API. Fetches results AND reads the actual web pages to extract clean full-text content via trafilatura. Not just snippets — full article text.
10
11## Constraint
12
13This skill already fetches and extracts full page content. Do NOT use WebFetch, web_fetch, WebSearch, browser tools, or any other URL-fetching/browsing tool on the URLs returned by this skill. The content is already included in the output. Never follow up with a separate fetch — everything you need is in the results.
14
15## Query Discipline
16
17Craft ONE good search query. That is almost always enough.
18
19Each call returns multiple results with full page text — you get broad coverage from a single query. Do not run multiple searches to "explore" a topic. One well-chosen query with the right mode covers it.
20
21**At most two calls** if the user's request genuinely spans two distinct topics (e.g. "compare X vs Y" where X and Y need separate searches, or one `default` + one `current` call for different aspects). Never more than two.
22
23**Do NOT:**
24- Run the same query with different wording to "get more results"
25- Run sequential searches to "dig deeper" — the full page content is already deep
26- Run one search to find something, then another to follow up — read the content you already have
27
28## Two Search Modes
29
30There are exactly two modes. Pick the right one based on the query:
31
32### `default` — General search (all-time)
33
34- All-time Google web search, **5 results**, each enriched with full page content
35- Use for: general questions, research, how-to, evergreen topics, product info, technical docs, comparisons, tutorials, anything NOT time-sensitive
36
37### `current` — News and recent info
38
39- Past-week Google web search (3 results) + Google News (3 results), each enriched with full page content
40- Use for: news, current events, recent developments, breaking news, announcements, anything time-sensitive
41
42### Mode Selection Guide
43
44| Query signals | Mode |
45|---------------|------|
46| "how does X work", "what is X", "explain X" | `default` |
47| Product research, comparisons, tutorials | `default` |
48| Technical documentation, guides | `default` |
49| Historical topics, evergreen content | `default` |
50| "news", "latest", "today", "this week", "recent" | `current` |
51| "what happened", "breaking", "announced", "released" | `current` |
52| Current events, politics, sports scores, stock prices | `current` |
53
54## Locale
55
56**Default is global** — no country filter, English results. This ONLY works for English queries.
57
58**You MUST ALWAYS set `--gl` and `--hl` when ANY of these are true:**
59- The user's message is in a non-English language
60- The search query you construct is in a non-English language
61- The user mentions a specific country, city, or region
62- The user asks for local results (prices, news, stores, etc.) in a non-English context
63
64**If the user writes in German, you MUST pass `--gl de --hl de`. No exceptions.**
65
66| Scenario | Flags |
67|----------|-------|
68| English query, no country target | *(omit --gl and --hl)* |
69| German query OR user writes in German OR targeting DE/AT/CH | `--gl de --hl de` |
70| French query OR user writes in French OR targeting France | `--gl fr --hl fr` |
71| Any other non-English language/country | `--gl XX --hl XX` (ISO codes) |
72
73**Rule of thumb:** If the query string contains non-English words, set `--gl` and `--hl` to match that language.
74
75## How to Invoke
76
77```bash
78python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG]
79```
80
81### Examples
82
83```bash
84# English, general research
85python3 scripts/search.py -q "how does HTTPS work"
86
87# English, time-sensitive
88python3 scripts/search.py -q "OpenAI latest announcements" --mode current
89
90# German query — set locale + current mode for news/prices
91python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de
92
93# German news
94python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de
95
96# French product research
97python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr
98```
99
100## Output Format
101
102The script streams a JSON array. The first element is metadata, the rest are results with full extracted content:
103
104```json
105[{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}]}
106,{"title": "Page Title", "url": "https://example.com", "source": "web", "content": "Full extracted page text..."}
107,{"title": "News Article", "url": "https://news.com", "source": "news", "date": "2 hours ago", "content": "Full article text..."}
108]
109```
110
111| Field | Description |
112|-------|-------------|
113| `title` | Page title |
114| `url` | Source URL |
115| `source` | `"web"`, `"news"`, or `"knowledge_graph"` |
116| `content` | Full extracted page text (falls back to search snippet if extraction fails) |
117| `date` | Present when available (news results always, web results sometimes) |
118
119## CLI Reference
120
121| Flag | Description |
122|------|-------------|
123| `-q, --query` | Search query (required) |
124| `-m, --mode` | `default` (all-time, 5 results) or `current` (past week + news, 3 each) |
125| `--gl` | Country code (e.g. `de`, `us`, `fr`, `at`, `ch`). Default: `world` |
126| `--hl` | Language code (e.g. `en`, `de`, `fr`). Default: `en` |
127
128## Edge Cases
129
130- If trafilatura cannot extract content from a page, the result falls back to the search snippet.
131- Some sites block scraping entirely — the snippet is all you get.
132- If zero results are returned, the script exits with `{"error": "No results found", "query": "..."}`.
133- The Serper API key is loaded from `.env` in the skill directory. If missing, the script exits with setup instructions.
modbender