grok-x-search
Skill3 starsChanged 5 months agoMITView on GitHub
Search, filter, and summarize real-time X posts through Grok. Defaults to web_search constrained to X post pages with direct x.com status links; supports native x_search when explicitly selected, filters, retries, and traceable citations.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- leaf76/agent-skillstheir own version, first seen Aug 17, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- leaf76/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use scripts/search_x.py for X, web, or mixed research.
- Very specific: line 26
search source, with --search-type x|web|hybrid (default web)
- Distinctive: line 28
Run the script and parse its JSON output.
- Distinctive: line 96
Create or update it without putting the key in shell history:
- Very specific: line 112
Use --dry-run to inspect the resolved endpoint, model, filters, and prompt without making a network request or requiring a key.
- Very specific: line 151
Do not combine --allow-handle and --exclude-handle.
- Distinctive: line 159
Keep citations when reporting results.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Grok X Search
Use scripts/search_x.py for X, web, or mixed research. It calls a
Responses-compatible endpoint and enables x_search, web_search, or both. The default is
web with strict scope: public web search is constrained to individual X post pages and
requires direct x.com/<handle>/status/<id> links. Use --search-scope loose when X should
remain the priority but relevant non-X context is also acceptable. Use x only when an
official xAI key and native x_search access are available; use hybrid only when both
sources are needed.
Operating procedure
- Translate the user's request into one focused search query.
- Preserve explicit constraints:
- result count, with
--limit(default20) - inclusive dates, with
--from-dateand--to-date - account allowlist or blocklist, with repeated
--allow-handleor--exclude-handle - media analysis, with
--imagesor--videos - ordering, with
--sort relevanceor--sort recent - preferred language, with
--language Chineseor another language name - search source, with
--search-type x|web|hybrid(defaultweb) - web strictness, with
--search-scope strict|loose(defaultstrict)
- result count, with
- Run the script and parse its JSON output.
- Present the model's summaries together with direct
x.comURLs and the returnedcitationslist. The script also extracts and deduplicatesx.comandtwitter.comstatus URLs when a gateway flattens tool results into final text. Do not invent authors, dates, metrics, quotes, or URLs. - State the actual number of usable posts when it is lower than requested.
Requests stream by default (stream: true, SSE): text deltas are echoed to stderr as they
arrive and the final response is reassembled from response.completed or
response.incomplete, so long searches survive proxies like Cloudflare that kill idle
origins. Disable with --no-stream or config key "stream": false. A provider error or
response.failed event exits non-zero. A stream that closes with no response object and no
text also exits non-zero. Text deltas without a completed event are still returned, with
status incomplete_stream.
For more than 20 results, pass the full count in one call. The prompt asks Grok to make additional searches and deduplicate canonical post URLs. A requested count is a target, not a guarantee.
Models and search modes
There is one Responses API request model. x_search is a tool attached to that request,
not a second endpoint or credential. This skill exposes two names so deployments can
choose deliberately:
default_model, the general fallback modelsearch_model, the model used by this X Search commandsearch_type, the default source mode,x,web, orhybridsearch_scope, the web mode scope,strictorloose
Both default to grok-4.6. Keep them equal unless the configured
gateway documents separate model names. Override per call with --search-model; --model
is retained as a general compatibility override.
web is the default because it does not require the official xAI x_search credential.
In strict scope it applies the provider's allowed_domains filter for x.com and
twitter.com, adds site:x.com/site:twitter.com to the prompt, and permits only
individual post pages. In loose scope it removes the hard domain filter, while the prompt
still constrains the search toward X, asks Grok to use site qualifiers, and allows useful
non-X context when necessary.
Configuration
Configuration is intentionally isolated from Codex and from the user's home config.
The default file is config.json beside this SKILL.md. It is ignored by the skill's
local .gitignore.
Precedence, highest first:
- CLI flags,
--base-url,--api-key,--search-model,--model - Environment,
GROK_BASE_URL/XAI_BASE_URL,GROK_API_KEY/XAI_API_KEY,GROK_SEARCH_MODEL, thenGROK_MODEL - Local
config.json - Defaults, base URL
https://api.x.ai/v1, modelgrok-4.6
The local schema is:
{
"base_url": "https://api.x.ai/v1",
"default_model": "grok-4.6",
"search_model": "grok-4.6",
"search_type": "web",
"search_scope": "strict",
"api_key": "..."
}Create or update it without putting the key in shell history:
python3 scripts/configure.pyThe configurator writes atomically and sets file permissions to 600. Never print or
summarize the API key. GROK_X_SEARCH_CONFIG may point to an explicitly chosen alternate
file; no Codex config.toml, auth.json, or OPENAI_API_KEY is read.
Reliability and diagnostics
Transient HTTP failures, rate limits, 5xx responses, network errors, and timeouts are
retried with exponential backoff. Tune with --retries and --timeout; use
--retries 0 to disable retries. Error bodies are truncated before printing.
Use --dry-run to inspect the resolved endpoint, model, filters, and prompt without making
a network request or requiring a key. Use --raw only when the complete provider response
is needed for debugging. Normal JSON output includes posts, actual_extracted_count, and
search_execution. The value is native_tool when the provider exposes a search-call
object and text_fallback when valid X status URLs were recovered from final text.
Examples
# Default, 20 relevant posts
python3 scripts/search_x.py "Grok 4.5 user reactions"
# Newest Chinese posts, with images analyzed
python3 scripts/search_x.py "国内 AI 产品发布" \
--limit 30 --sort recent --language Chinese --images
# Restrict to selected accounts and a date window
python3 scripts/search_x.py "model release announcements" \
--limit 30 \
--allow-handle xai \
--allow-handle elonmusk \
--from-date 2026-07-01 \
--to-date 2026-07-23
# Inspect configuration and request construction
python3 scripts/search_x.py "test query" --dry-run
# Explicitly use web_search constrained to X post pages (also the default)
python3 scripts/search_x.py "GPT 新模型新闻" --search-type web --limit 20
# Prefer X, but allow useful context from other web pages
python3 scripts/search_x.py "GPT 新模型新闻" --search-type web --search-scope loose
# Combine web coverage and X discussion
python3 scripts/search_x.py "GPT 新模型" --search-type hybrid --limit 20Constraints
- Do not combine
--allow-handleand--exclude-handle. - Each account filter accepts at most 20 handles.
- Dates must use
YYYY-MM-DDand are inclusive on both ends for the caller. web_searchhas no date parameter. Web mode, including the default strict scope, puts that inclusive window in the prompt.- Native
x_searchtreatsto_dateas exclusive. The script sends the next calendar day, so the requested end date is included.--to-date 9999-12-31is rejected because that conversion overflows. - Keep citations when reporting results; they are the traceability layer.
- Accept
text_fallbackas a valid gateway response shape, but distinguish extracted URLs from provider citations when describing confidence.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

