xAI Skill

Search X (Twitter), search the web, chat with Grok models (including vision), and analyze X content patterns using xAI's API.

Features

X Search: Search posts, threads, and accounts with date/handle filters
Web Search: Search the web via Grok's web_search tool
Chat: Text and vision (image analysis) with Grok models
Analysis: Voice patterns, trend research, post safety checks
Models: List available xAI models

Setup

API Key

Get your xAI API key from console.x.ai.

# Via clawdbot config (recommended)
clawdbot config set skills.entries.xai-plus.apiKey "xai-YOUR-KEY"
Or environment variable

export XAI_API_KEY="xai-YOUR-KEY"

The scripts check these locations in order:

```
XAI_API_KEY
```
env var

~/.clawdbot/clawdbot.json

→

env.XAI_API_KEY

~/.clawdbot/clawdbot.json

→

skills.entries.xai-plus.apiKey

~/.clawdbot/clawdbot.json

→

skills.entries["grok-search"].apiKey

(fallback)

Default Model (Optional)

Override the default model (

grok-4-1-fast

# Via config
clawdbot config set skills.entries.xai-plus.model "grok-3"
Or environment variable

export XAI_MODEL="grok-3"

Model priority:

Command-line
```
--model
```
flag (highest priority)
```
XAI_MODEL
```
env var
```
~/.clawdbot/clawdbot.json
```
→
```
env.XAI_MODEL
```

~/.clawdbot/clawdbot.json

→

skills.entries.xai-plus.model

Default:
```
grok-4-1-fast
```

Search

X Search

Search X posts and threads with optional filters.

Basic search:

node {baseDir}/scripts/grok_search.mjs "query" --x

With date filter:

# Last 7 days
node {baseDir}/scripts/grok_search.mjs "Claude AI" --x --days 7
Specific date range

node {baseDir}/scripts/grok_search.mjs "AI agents" --x --from 2026-01-01 --to 2026-01-31

Filter by handles:

# Only from specific accounts
node {baseDir}/scripts/grok_search.mjs "AI news" --x --handles @AnthropicAI,@OpenAI
Exclude accounts

node {baseDir}/scripts/grok_search.mjs "GPT" --x --exclude @spam1,@spam2

Output formats:

# JSON (default, agent-friendly)
node {baseDir}/scripts/grok_search.mjs "query" --x
Links only
node {baseDir}/scripts/grok_search.mjs "query" --x --links-only
Human-readable text
node {baseDir}/scripts/grok_search.mjs "query" --x --text

JSON output schema:

{
  "query": "search query",
  "mode": "x",
  "results": [
    {
      "title": "@handle",
      "url": "https://x.com/handle/status/123",
      "snippet": "Post text...",
      "author": "@handle",
      "posted_at": "2026-01-15T10:30:00Z"
    }
  ],
  "citations": ["https://x.com/..."]
}

Web Search

Search the web via Grok.

node {baseDir}/scripts/grok_search.mjs "TypeScript best practices 2026" --web

JSON output schema:

{
  "query": "search query",
  "mode": "web",
  "results": [
    {
      "title": "Page title",
      "url": "https://example.com/page",
      "snippet": "Description...",
      "author": null,
      "posted_at": null
    }
  ],
  "citations": ["https://example.com/..."]
}

Search Options

Flag	Description	Example
`--x`	Search X/Twitter	Required for X search
`--web`	Search the web	Required for web search
`--days N`	Last N days (X only)	`--days 7`
`--from YYYY-MM-DD`	Start date (X only)	`--from 2026-01-01`
`--to YYYY-MM-DD`	End date (X only)	`--to 2026-01-31`
`--handles a,b`	Only these accounts (X only)	`--handles @user1,@user2`
`--exclude a,b`	Exclude accounts (X only)	`--exclude @spam`
`--max N`	Max results	`--max 20`
`--model ID`	Override model	`--model grok-3`
`--json`	JSON output (default)	-
`--links-only`	Just URLs	-
`--text`	Human-readable	-
`--raw`	Include debug output	-

See references/search-patterns.md for advanced query patterns and optimization tips.

Chat

Text Chat

Ask Grok anything.

node {baseDir}/scripts/chat.mjs "What is quantum computing?"

With model override:

node {baseDir}/scripts/chat.mjs --model grok-3 "Explain transformers in ML"

JSON output:

node {baseDir}/scripts/chat.mjs --json "What is TypeScript?"

JSON schema:

{
  "model": "grok-4-1-fast",
  "prompt": "What is TypeScript?",
  "text": "TypeScript is...",
  "citations": ["https://..."]
}

Vision Chat

Analyze images with Grok.

node {baseDir}/scripts/chat.mjs --image ./screenshot.png "What's in this image?"

Multiple images:

node {baseDir}/scripts/chat.mjs --image ./pic1.jpg --image ./pic2.jpg "Compare these"

Supported formats: JPG, PNG, WebP, GIF

Chat Options

Flag	Description	Example
`--model ID`	Model to use	`--model grok-2-vision-1212`
`--image PATH`	Attach image (can repeat)	`--image ./pic.jpg`
`--json`	JSON output	-
`--raw`	Include debug output	-

See references/models.md for model comparison and capabilities.

Analysis

Analyze X content for voice patterns, trends, and post quality.

Voice Analysis

Analyze an account's voice and writing patterns.

node {baseDir}/scripts/analyze.mjs voice @username

Custom date range:

# Last 60 days
node {baseDir}/scripts/analyze.mjs voice @username --days 60

JSON output schema:

{
  "handle": "@username",
  "analyzed_posts": 150,
  "voice": {
    "tone": "casual, technical",
    "personality": ["curious", "direct", "helpful"],
    "perspective": "practitioner sharing lessons",
    "energy_level": "medium"
  },
  "patterns": {
    "sentence_structure": ["short declarative", "occasional fragments"],
    "vocabulary": ["technical", "accessible"],
    "formatting_quirks": ["line breaks for emphasis", "minimal punctuation"],
    "recurring_phrases": ["here's the thing", "turns out"]
  },
  "topics": ["AI", "software engineering", "startups"],
  "best_posts": [
    {
      "url": "https://x.com/username/status/123",
      "text": "Post text...",
      "why": "Authentic voice, specific example"
    }
  ],
  "anti_patterns": ["never uses em-dashes", "avoids numbered lists"]
}

Trend Research

Research trends and discussions about a topic.

node {baseDir}/scripts/analyze.mjs trends "AI agents"

JSON output schema:

{
  "topic": "AI agents",
  "trends": [
    {
      "pattern": "Shift from chatbots to autonomous agents",
      "description": "Discussion focuses on...",
      "example_posts": ["https://x.com/..."]
    }
  ],
  "perspectives": [
    {
      "viewpoint": "Agents will replace most SaaS",
      "supporters": ["@user1", "@user2"]
    }
  ],
  "hashtags": ["#AIAgents", "#AutonomousAI"],
  "key_accounts": ["@researcher1", "@founder2"],
  "posting_angles": [
    {
      "angle": "Practical implementation challenges",
      "hook": "Everyone talks about AI agents. Nobody talks about...",
      "target_audience": "Engineers building with AI"
    }
  ]
}

Post Safety Check

Check a draft post or existing post for AI signals and platform flag patterns.

Check draft text:

node {baseDir}/scripts/analyze.mjs post "Your draft post text here"

Check existing post:

node {baseDir}/scripts/analyze.mjs post --url "https://x.com/user/status/123"

JSON output schema:

{
  "post_text": "Your post...",
  "ai_detection_score": 3,
  "ai_signals": [
    "Contains em-dash",
    "Ends with engagement bait question"
  ],
  "platform_flag_score": 2,
  "platform_risks": [
    "Generic question could trigger spam filter"
  ],
  "quality_score": 7,
  "suggestions": [
    "Replace em-dash with period or comma",
    "Remove 'What do you think?' closer",
    "Add specific personal detail"
  ]
}

Scoring:

AI Detection: 0-10 (10 = definitely AI)
Platform Flag Risk: 0-10 (10 = high spam risk)
Quality: 0-10 (10 = excellent)

Analysis Options

Flag	Description	Example
`--days N`	Date range for analysis	`--days 60`
`--url URL`	Analyze existing post	`--url https://x.com/...`
`--model ID`	Override model	`--model grok-3`
`--json`	JSON output	-
`--raw`	Include debug output	-

See references/analysis-prompts.md for detailed prompt structures and scoring criteria.

Models

List available xAI models.

node {baseDir}/scripts/models.mjs

Output:

grok-2-vision-1212
grok-3
grok-4-1-fast
grok-4-fast

JSON output:

node {baseDir}/scripts/models.mjs --json

Quick model comparison:

Model	Speed	Quality	Vision	Best For
grok-4-1-fast	Fast	Good	No	Default (search, chat, analysis)
grok-4-fast	Fast	Good	No	Alternative fast model
grok-3	Slower	Best	No	Complex reasoning, detailed analysis
grok-2-vision-1212	Medium	Good	Yes	Image analysis

See references/models.md for detailed model capabilities and use cases.

Advanced Usage

Citation Deduplication

For X searches, the tool automatically deduplicates tweet URLs, preferring canonical

/@handle/status/id

over

/i/status/id

format.

Custom Model Selection

Override the default model for any operation:

# Search with grok-3 for better quality
node {baseDir}/scripts/grok_search.mjs "complex query" --x --model grok-3
Chat with vision model
node {baseDir}/scripts/chat.mjs --model grok-2-vision-1212 --image pic.jpg "Describe"
Analysis with grok-3 for deeper insights

node {baseDir}/scripts/analyze.mjs voice @username --model grok-3

Debugging

Add

--raw

to any command to see the full API response:

node {baseDir}/scripts/grok_search.mjs "query" --x --raw

Reference Documentation

API Reference - xAI API endpoints and parameters
Search Patterns - Query patterns, filters, optimization tips
Models - Model comparison and capabilities
Analysis Prompts - Structured prompts and scoring criteria
X Algorithm - Ranking, engagement weights, spam detection

Examples

Research a topic

# Find recent discussions
node {baseDir}/scripts/grok_search.mjs "Claude Sonnet 4.5" --x --days 3
Get trend analysis

node {baseDir}/scripts/analyze.mjs trends "Claude Sonnet 4.5"

Analyze voice before drafting

# Study the target account
node {baseDir}/scripts/analyze.mjs voice @target_account --days 30
Check your draft

node {baseDir}/scripts/analyze.mjs post "Your draft here"

Multi-modal research

# Search web for context
node {baseDir}/scripts/grok_search.mjs "TypeScript 5.7 features" --web
Ask follow-up
node {baseDir}/scripts/chat.mjs "What are the key TypeScript 5.7 improvements?"
Analyze screenshot

node {baseDir}/scripts/chat.mjs --image ./code.png "Review this code"

Error Handling

Common errors and solutions:

Missing API key:

Missing XAI_API_KEY

→ Set

XAI_API_KEY

environment variable or add to

~/.clawdbot/clawdbot.json

Invalid mode:

Must specify --web or --x

→ Add

--web

--x

flag to search command

Image format error:

Unsupported image type

→ Use JPG, PNG, WebP, or GIF format

API error:

xAI API error: 401 Unauthorized

→ Check API key is valid and active

Tips

Default model (
```
grok-4-1-fast
```
) is fast and good for most tasks
Use
```
grok-3
```
for complex analysis or when quality matters more than speed
X searches are limited by recency (xAI x_search tool constraints)
Web searches work best with specific, current queries
Voice analysis needs sufficient post history (30+ posts recommended)
Post safety checks are advisory; use judgment for final decisions
JSON output is best for agent/script consumption
Text output is better for terminal/human reading

Troubleshooting

No results from X search:

Try broader query or longer date range
Check if handles exist and are public
Remove overly restrictive filters

Voice analysis incomplete:

Increase
```
--days
```
to get more post history
Check if account is public and active
Verify handle is correct (with or without @)

API rate limits:

xAI enforces rate limits per API key
Spread requests over time if hitting limits
Consider upgrading xAI plan for higher limits

Content Writing Workflow

Use the analysis tools to improve your X content:

# Research before writing
node {baseDir}/scripts/analyze.mjs trends "your topic"
node {baseDir}/scripts/grok_search.mjs "your topic" --x --days 7
Study voice patterns
node {baseDir}/scripts/analyze.mjs voice @target_account
Check draft before posting
node {baseDir}/scripts/analyze.mjs post "$(cat draft.txt)"

Use the JSON output to:

Research current discussions and posting angles
Learn from successful voices in your niche
Catch AI signals and platform flags before publishing

xAI Plus

AI Skill Market Insights

Be Part of the 2,119+ Developer Community

xAI Skill

Features

Setup

API Key

Or environment variable

Default Model (Optional)

Or environment variable

Search

X Search

Specific date range

Exclude accounts

Links only

Human-readable text

Web Search

Search Options

Chat

Text Chat

Vision Chat

Chat Options

Analysis

Voice Analysis

Trend Research

Post Safety Check

Analysis Options

Models

Advanced Usage

Citation Deduplication

Custom Model Selection

Chat with vision model

Analysis with grok-3 for deeper insights

Debugging

Reference Documentation

Examples

Research a topic

Get trend analysis

Analyze voice before drafting

Check your draft

Multi-modal research

Ask follow-up

Analyze screenshot

Error Handling

Tips

Troubleshooting

Content Writing Workflow

Study voice patterns

Check draft before posting

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company