grok-search

name	grok-search
description	On-demand real-time web and X (Twitter) search via xAI's Grok. Reach for this when the user explicitly wants Grok to search, or asks for real-time / breaking / X-Twitter-native results that a general web search misses. Not the default web search — a named tool you invoke deliberately.
version	0.1.0
license	MIT
metadata	{"hermes":{"tags":["grok","xai","real-time","twitter","x"],"related_skills":["xurl"]}}

Grok Search

Real-time web + X (Twitter) search powered by xAI's Grok agentic search tools. Grok does the searching server-side and returns ranked results with citations.

This is a deliberate, on-demand capability — it does not change your default web search backend. Use it when Grok's real-time reach or native access to X/Twitter is what the moment calls for; keep using the normal web_search tool for everything else.

When to load

Load this skill when:

• The user says "use Grok to search", "ask Grok", "search X / Twitter", or names Grok/X explicitly for a lookup.
• The request is real-time / breaking ("what's happening with X right now", "latest reactions to Y") where a general index lags.
• The request is X/Twitter-native ("what are people posting about Z", "what's the sentiment on X about W", "find the thread where…").

Do not reach for this for ordinary web research — the default web_search provider is better for general-purpose, index-backed queries and does not carry Grok's per-call cost.

Prerequisites

• XAI_API_KEY set in the profile's ~/.hermes/.env (an xAI developer key from the xAI console). The script also accepts --api-key, but prefer the env var — a key on the command line lands in shell history and process listings.
• Python 3 (stdlib only — no packages to install).

If the key is missing, the script exits with a clear JSON error; tell the user a key is needed and stop, don't fall back silently.

Usage

The helper is scripts/grok_search.py with two subcommands. It prints a JSON object to stdout: {query, mode, results: [{title, url, description, source}], citations: [...]}.

Always shell-quote the query — wrap it in single quotes so punctuation, double quotes, and shell metacharacters in the user's phrasing can't break the command or be interpreted by the shell. If the query itself contains a single quote, escape it ('\'').

Web (real-time web search)

python3 scripts/grok_search.py web '<query>' --limit 5

Optional:

• --recency-days D — restrict to roughly the last D days (translated to a from_date of today − D, which is xAI's supported recency mechanism)
• --allowed-domains a.com,b.com — only these (max 5)
• --excluded-domains a.com,b.com — never these (max 5; mutually exclusive with allowed)
• --model M — override the Grok model (default is a reasoning model required for agentic tools)

X / Twitter search

python3 scripts/grok_search.py x '<query>' --limit 5

Optional:

• --handles elonmusk,xai — only posts from these handles (max 20)
• --from-date YYYY-MM-DD / --to-date YYYY-MM-DD — date window

How to present results

• Summarize the top results in your own words; cite the URLs. For X results the URLs are x.com/<handle>/status/... — attribute to the handle when useful.
• If results is empty but citations has URLs, output the citations as a simple bulleted list and tell the user Grok found sources but didn't return structured summaries — don't invent descriptions for them.
• If the script errors (non-zero exit, JSON error on stderr), report the error plainly. Do not invent results.

Trust & safety

Grok is an LLM, not a search index — it generates the result URLs it returns. That means:

• A query built from untrusted input can in principle steer Grok toward attacker-chosen URLs. Validate any URL before fetching it downstream, exactly as you would treat any model-generated link.
• Treat the descriptions as Grok's summaries, not verbatim source text. When accuracy matters, fetch the cited URL and confirm.

Cost

xAI bills Grok's built-in search tools per call (a flat per-1k-calls fee on top of token usage). This is why the skill is on-demand, not the default backend — reach for it when its real-time / X reach earns the call, not for routine lookups.

Pitfalls

• Reasoning model required. The agentic web_search / x_search tools need a reasoning-capable Grok model. The default (grok-4.3, the stable flagship) supports them. If a non-reasoning model is passed via --model, the call may return no tool results. Stick with the default unless you know the target model supports agentic tools.
• Not an extractor. This returns search results (title/url/description), not full page content. To read a normal web page, pass the URL to the built-in web_extract tool. Exception: x.com URLs — web_extract almost always fails on them (auth-walls, JS rendering), so rely on Grok's own descriptions for X posts rather than trying to extract them.
• Don't wire it as web.backend. If you want Grok as a profile's default search, that's the built-in xai backend instead — a different, deliberate choice with the same trust caveats. This skill deliberately leaves the default untouched.