Skill: mischasigtermans/xai-plus (version 2.0.2)

--- name: xai-plus description: | Search X/Twitter and the web, chat with Grok models (text + vision), and analyze X content using xAI's API. Use when: searching X posts/threads, web research via Grok, chatting with Grok, analyzing voice patterns, researching trends, or checking post quality. Triggers: grok, xai, search x, search twitter, x search, ask grok, grok chat, analyze voice, x trends. metadata: openclaw: emoji: "🔎" requires: bins: ["node"] env: ["XAI_API_KEY"] primaryEnv: "XAI_API_KEY" --- # 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


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)