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:

1. XAI_API_KEY env var
2. ~/.clawdbot/clawdbot.json → env.XAI_API_KEY
3. ~/.clawdbot/clawdbot.json → skills.entries.xai-plus.apiKey
4. ~/.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:

1. Command-line --model flag (highest priority)
2. XAI_MODEL env var
3. ~/.clawdbot/clawdbot.json → env.XAI_MODEL
4. ~/.clawdbot/clawdbot.json → skills.entries.xai-plus.model
5. 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 or --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