Introduction
# 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](https://console.x.ai).
```bash # 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`):
```bash # 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:** ```bash node {baseDir}/scripts/grok_search.mjs "query" --x ```
**With date filter:** ```bash # 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:** ```bash # 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:** ```bash # 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:** ```json { "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.
```bash node {baseDir}/scripts/grok_search.mjs "TypeScript best practices 2026" --web ```
**JSON output schema:** ```json { "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](references/search-patterns.md) for advanced query patterns and optimization tips.
## Chat
### Text Chat
Ask Grok anything.
```bash node {baseDir}/scripts/chat.mjs "What is quantum computing?" ```
**With model override:** ```bash node {baseDir}/scripts/chat.mjs --model grok-3 "Explain transformers in ML" ```
**JSON output:** ```bash node {baseDir}/scripts/chat.mjs --json "What is TypeScript?" ```
JSON schema: ```json { "model": "grok-4-1-fast", "prompt": "What is TypeScript?", "text": "TypeScript is...", "citations": ["https://..."] } ```
### Vision Chat
Analyze images with Grok.
```bash node {baseDir}/scripts/chat.mjs --image ./screenshot.png "What's in this image?" ```
**Multiple images:** ```bash 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](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.
```bash node {baseDir}/scripts/analyze.mjs voice @username ```
**Custom date range:** ```bash # Last 60 days node {baseDir}/scripts/analyze.mjs voice @username --days 60 ```
**JSON output schema:** ```json { "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.
```bash node {baseDir}/scripts/analyze.mjs trends "AI agents" ```
**JSON output schema:** ```json { "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:** ```bash node {baseDir}/scripts/analyze.mjs post "Your draft post text here" ```
**Check existing post:** ```bash node {baseDir}/scripts/analyze.mjs post --url "https://x.com/user/status/123" ```
**JSON output schema:** ```json { "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](references/analysis-prompts.md) for detailed prompt structures and scoring criteria.
## Models
List available xAI models.
```bash node {baseDir}/scripts/models.mjs ```
**Output:** ``` grok-2-vision-1212 grok-3 grok-4-1-fast grok-4-fast ```
**JSON output:** ```bash 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](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:
```bash # 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:
```bash node {baseDir}/scripts/grok_search.mjs "query" --x --raw ```
## Reference Documentation
- [API Reference](references/api-reference.md) - xAI API endpoints and parameters - [Search Patterns](references/search-patterns.md) - Query patterns, filters, optimization tips - [Models](references/models.md) - Model comparison and capabilities - [Analysis Prompts](references/analysis-prompts.md) - Structured prompts and scoring criteria - [X Algorithm](references/x-algorithm.md) - Ranking, engagement weights, spam detection
## Examples
### Research a topic ```bash # 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 ```bash # 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 ```bash # 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:
```bash # 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