SearXNG Search Skill
Search the web using a SearXNG instance via its API.
Configuration issues
This skill depends on a local SearXNG config file. Keep setup details out of this
file and load references/configuration.md only when needed.
If scripts/search.py reports configuration, auth, or instance setup errors,
read references/configuration.md before retrying. Common examples include:
ERROR: Config file not foundERROR: Invalid TOML ... / ERROR: Invalid JSON ...ERROR: base_url is requiredERROR: Environment variable ... is not setERROR: auth.token required for bearer authERROR: auth.user and auth.pass required for basic authERROR: Unknown auth.type ...ERROR: HTTP 401 / ERROR: HTTP 403
Usage
Run the search script:
python3 scripts/search.py [OPTIONS] <query>
Options
| Flag |
Description |
-c, --categories |
Comma-separated categories (general, news, images, videos, music, files, it, science, social media) |
-e, --engines |
Comma-separated engines (google, duckduckgo, bing, etc.) |
-l, --language |
Language code (en, zh-CN, ja, etc.) |
-p, --page |
Page number (default: 1) |
-t, --time-range |
Time range: day, month, year |
-n, --max-results |
Max results to show (overrides config default) |
-s, --safesearch |
Safe search: 0 (off), 1 (moderate), 2 (strict) |
Examples
# Basic search
python3 scripts/search.py "SearXNG documentation"
# Search news from the last day
python3 scripts/search.py -c news -t day "latest tech news"
# Search with specific engines, page 2
python3 scripts/search.py -e google,duckduckgo -p 2 "rust programming"
# Search in Chinese with more results
python3 scripts/search.py -l zh-CN -n 10 "开源搜索引擎"
Best Practices
- Technical topics (programming, software, science, IT, etc.): Always use English as both the query language and search language (
-l en), regardless of the user's input language. Translate the query to English if needed. English results are more comprehensive and up-to-date for technical content.
- Chinese lifestyle topics (food, travel, shopping, local services, social trends, etc.): In addition to the default search, run a second search with
-e baidu,sogou -l zh-CN using a Chinese query to capture China-specific results. Merge and deduplicate results before presenting to the user.
Workflow
- User asks to search for something
- Determine the topic type:
- Technical: translate query to English if needed, search with
-l en
- Chinese lifestyle: run the default search first, then an additional search with
-e baidu,sogou -l zh-CN
- Run
scripts/search.py with the query and any relevant filters
- Present results to the user in a readable format
- If user wants more results, use
-p for pagination or -n for more per page
1---2name: searxng-search3description: Search the web using a self-hosted SearXNG instance. Use when users ask to search with SearXNG, or when web search is needed and a SearXNG instance is configured. Supports categories, engines, time range, and language filters.4---56# SearXNG Search Skill78Search the web using a SearXNG instance via its API.910## Configuration issues1112This skill depends on a local SearXNG config file. Keep setup details out of this13file and load [references/configuration.md](references/configuration.md) only when needed.1415If `scripts/search.py` reports configuration, auth, or instance setup errors,16read [references/configuration.md](references/configuration.md) before retrying. Common examples include:1718- `ERROR: Config file not found`19- `ERROR: Invalid TOML ...` / `ERROR: Invalid JSON ...`20- `ERROR: base_url is required`21- `ERROR: Environment variable ... is not set`22- `ERROR: auth.token required for bearer auth`23- `ERROR: auth.user and auth.pass required for basic auth`24- `ERROR: Unknown auth.type ...`25- `ERROR: HTTP 401` / `ERROR: HTTP 403`2627## Usage2829Run the search script:3031```bash32python3 scripts/search.py [OPTIONS] <query>33```3435### Options3637| Flag | Description |38|---|---|39| `-c, --categories` | Comma-separated categories (`general`, `news`, `images`, `videos`, `music`, `files`, `it`, `science`, `social media`) |40| `-e, --engines` | Comma-separated engines (`google`, `duckduckgo`, `bing`, etc.) |41| `-l, --language` | Language code (`en`, `zh-CN`, `ja`, etc.) |42| `-p, --page` | Page number (default: 1) |43| `-t, --time-range` | Time range: `day`, `month`, `year` |44| `-n, --max-results` | Max results to show (overrides config default) |45| `-s, --safesearch` | Safe search: `0` (off), `1` (moderate), `2` (strict) |4647### Examples4849```bash50# Basic search51python3 scripts/search.py "SearXNG documentation"5253# Search news from the last day54python3 scripts/search.py -c news -t day "latest tech news"5556# Search with specific engines, page 257python3 scripts/search.py -e google,duckduckgo -p 2 "rust programming"5859# Search in Chinese with more results60python3 scripts/search.py -l zh-CN -n 10 "开源搜索引擎"61```6263## Best Practices6465- **Technical topics** (programming, software, science, IT, etc.): Always use **English** as both the query language and search language (`-l en`), regardless of the user's input language. Translate the query to English if needed. English results are more comprehensive and up-to-date for technical content.66- **Chinese lifestyle topics** (food, travel, shopping, local services, social trends, etc.): In addition to the default search, run a **second search** with `-e baidu,sogou -l zh-CN` using a Chinese query to capture China-specific results. Merge and deduplicate results before presenting to the user.6768## Workflow69701. User asks to search for something712. Determine the topic type:72 - **Technical**: translate query to English if needed, search with `-l en`73 - **Chinese lifestyle**: run the default search first, then an additional search with `-e baidu,sogou -l zh-CN`743. Run `scripts/search.py` with the query and any relevant filters754. Present results to the user in a readable format765. If user wants more results, use `-p` for pagination or `-n` for more per page
xyenon