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.

Security Scan

The skill's code, declared requirements, and runtime instructions are coherent for a Grok/xAI search wrapper; primary risks are local config access and that its self-test performs real API calls which may consume your XAI quota.

Purpose & Capability

Name/description (Grok/xAI web and X/Twitter search) align with the code and declared requirements: the scripts call xAI Responses API endpoints and require node + XAI_API_KEY as expected.

Instruction Scope

Runtime instructions and scripts are focused on searching and chat via xAI and do not attempt to contact unexpected remote endpoints. They do read local files you supply (image paths) and explicitly read ~/.clawdbot/clawdbot.json as a lookup for the API key (the SKILL.md documents this lookup). The selftest script runs multiple real API calls (live queries) which can incur API usage; that behavior is visible in the scripts but may be surprising to users who run the selftest without realizing it.

Install Mechanism

No install spec; this is instruction+script-based and requires node on PATH. No remote installers or downloads are used.

Credentials

Only XAI_API_KEY is declared and used as the primary credential, which fits the skill's purpose. The scripts also attempt to read fallback API keys from ~/.clawdbot/clawdbot.json (including skills.entries[...].apiKey). That lookup is intended as convenience but means the skill will read a local config file that may contain other stored keys; the script only extracts the XAI key fields, but users should be aware of this local file access.

Persistence & Privilege

always is false and the skill does not request permanent platform presence or modify other skills. It runs as invoked and does not attempt to change agent/system-wide settings.

Assessment

This skill appears to do what it says: call xAI (Grok) search tools and return structured JSON. Before installing/using: - Provide an XAI_API_KEY via environment variable if you prefer to avoid the skill reading ~/.clawdbot/clawdbot.json. The scripts will try that config file as a fallback and will look for apiKey entries for other skills there. - Be aware the included selftest runs multiple live API calls (chat, searches, model listing). Running it will use your XAI API key and may consume quota or incur cost; only run it intentionally. - The scripts accept image file paths and will base64-embed those images in requests — don't pass sensitive images unless you want them uploaded to x.ai. - If you store secrets in ~/.clawdbot/clawdbot.json, inspect that file or move/limit sensitive entries before using this skill. The code is readable (no obfuscated network calls) — you can review the scripts locally to confirm behavior.

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
• ~/.clawdbot/clawdbot.json → env.XAI_API_KEY
• ~/.clawdbot/clawdbot.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)

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)

{
  "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.