grok-search
Search the web or X/Twitter using xAI Grok server-side tools (web_search, x_search) via the xAI Responses API. Use when you need tweets/threads/users from X, want Grok as an alternative to Brave, or you need structured JSON + citations.
Best use case
grok-search is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Search the web or X/Twitter using xAI Grok server-side tools (web_search, x_search) via the xAI Responses API. Use when you need tweets/threads/users from X, want Grok as an alternative to Brave, or you need structured JSON + citations.
Teams using grok-search should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/grok-search/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How grok-search Compares
| Feature / Agent | grok-search | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Search the web or X/Twitter using xAI Grok server-side tools (web_search, x_search) via the xAI Responses API. Use when you need tweets/threads/users from X, want Grok as an alternative to Brave, or you need structured JSON + citations.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
Run xAI Grok locally via bundled scripts (search + chat + model listing). Default output for search is *pretty JSON* (agent-friendly) with citations.
## API key
The script looks for an xAI API key in this order:
- `XAI_API_KEY` env var
- `~/.hermes/.env` → `XAI_API_KEY=...`
- `~/.openclaw/openclaw.json` → `env.XAI_API_KEY`
- `~/.openclaw/openclaw.json` → `skills.entries["grok-search"].apiKey`
- fallback: `skills.entries["search-x"].apiKey` or `skills.entries.xai.apiKey`
## Run
Use `{baseDir}` so the command works regardless of workspace layout.
### Search
- Web search (JSON):
- `node {baseDir}/scripts/grok_search.mjs "<query>" --web`
- X/Twitter search (JSON):
- `node {baseDir}/scripts/grok_search.mjs "<query>" --x`
### Chat
- Chat (text):
- `node {baseDir}/scripts/chat.mjs "<prompt>"`
- Chat (vision):
- `node {baseDir}/scripts/chat.mjs --image /path/to/image.jpg "<prompt>"`
### Models
- List models:
- `node {baseDir}/scripts/models.mjs`
## Useful flags
Output:
- `--links-only` print just citation URLs
- `--text` hide the citations section in pretty output
- `--raw` include the raw Responses API payload on stderr (debug)
Common:
- `--max <n>` limit results (default 8)
- `--model <id>` (default `grok-4-1-fast-reasoning`)
X-only filters (server-side via x_search tool params):
- `--days <n>` (e.g. 7)
- `--from YYYY-MM-DD` / `--to YYYY-MM-DD`
- `--handles @a,@b` (limit to these handles)
- `--exclude @bots,@spam` (exclude handles)
## Output shape (JSON)
```json
{
"query": "...",
"mode": "web" | "x",
"results": [
{
"title": "...",
"url": "...",
"snippet": "...",
"author": "...",
"posted_at": "..."
}
],
"citations": ["https://..."]
}
```
## Notes
- `citations` are merged/validated from xAI response annotations where possible (more reliable than trusting the model's JSON blindly).
- Prefer `--x` for tweets/threads, `--web` for general research.Related Skills
Apple Search Ads
Create, optimize, and scale Apple Search Ads campaigns with API automation, attribution integration, and bid strategy recommendations.
keyword-research
When the user wants to discover, evaluate, or prioritize App Store keywords. Also use when the user mentions "keyword research", "find keywords", "search volume", "keyword difficulty", "keyword ideas", or "what keywords should I target". For implementing keywords into metadata, see metadata-optimization. For auditing current keyword performance, see aso-audit.
writer
Write content in Eric's voice — articles, blog posts, tweets, social media posts, marketing copy, newsletter drafts. Loads WRITING-STYLE.md and enforces kill phrases.
positioning-angles
Use when defining product positioning, choosing strategic angles, crafting value propositions, competitive positioning, product messaging, differentiation strategy, or go-to-market angles. Also use for 'how should I position my app', 'what angle should I use', 'painkiller vs vitamin', or 'market positioning'.
outline-generator
Use when generating outlines, article structures, content outlines, blog outlines, planning article sections, structuring posts, breaking down topics into sections, or organizing ideas for long-form content. Also use for 'outline this', 'structure this article', or 'plan the sections'.
last30days-open
Use only when the user explicitly asks for the open variant of last30days, including watchlists, briefings, and history queries. Sources: Reddit, X, YouTube, web.
last30days
Use when researching what happened in the last 30 days on a topic. Also triggered by 'last30'. Sources: Reddit, X, YouTube, web. Produces expert-level summary with copy-paste-ready prompts.
hooks
Use when generating hooks, headlines, titles, and scroll-stopping openers for content. Also use when analyzing viral posts, Reels, TikToks, YouTube Shorts, or successful social examples to extract reusable hook patterns and improve hook guidance.
evaluate-content
Use when judging content quality OR editing/improving existing copy: shareability, readability, voice, cuttability, angle, copy sweeps.
editor-in-chief
Use when a first draft is complete and all Phase 1 gates are done: topic selected (seo-research), title approved (hooks), outline approved (outline-generator), draft written (writer). Runs autonomous diagnosis-prescribe-rewrite loop before Substack.
copywriting
Write or improve marketing copy for any surface: pages, ads, app stores, landing pages, TikTok/Meta scripts, push notifications, UGC. Combines page copy frameworks with direct response principles.
content-strategy
Use when building content strategy: hooks, angles, and ideas from what's trending now. Covers organic and paid creative across TikTok, X, YouTube, Meta, LinkedIn.