SearXNG Search Skill

Search the web using a SearXNG instance via its API.

Network destinations

Two levels — both matter:

• Direct (this script): the script makes a single request to your configured base_url. HTTPS by default; plain HTTP is allowed only for loopback hosts (127.0.0.1, ::1, localhost) or for non-loopback hosts if the config contains allow_insecure_http = true (with a warning). If auth.type is set, the Authorization header travels to that single host and nowhere else. Redirects are never followed: a 30x response is an error, because following a redirect could forward the Authorization header to a host you did not configure. Point base_url directly at the final endpoint (or front the instance with a same-origin reverse proxy).
• Downstream (your SearXNG instance): the instance then forwards the query, language, and categories to the engines it itself has been configured with (Google, Bing, DuckDuckGo, Brave, Baidu, etc., as enabled by the instance operator). This skill does not control that hop — it is a property of any SearXNG client. If query contents reaching the upstream engines is a concern, configure your instance to use engines you trust, or self-host engines locally.

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 found
• ERROR: Invalid TOML ... / ERROR: Invalid JSON ...
• ERROR: base_url is required
• ERROR: Environment variable ... is not set
• ERROR: auth.token required for bearer auth
• ERROR: auth.user and auth.pass required for basic auth
• ERROR: Unknown auth.type ...
• ERROR: HTTP 401 / ERROR: HTTP 403

Usage

Run the search script:

python3 scripts/search.py [OPTIONS] <query>

Options

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

1. User asks to search for something
2. 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
3. Run scripts/search.py with the query and any relevant filters
4. Present results to the user in a readable format
5. If user wants more results, use -p for pagination or -n for more per page