/x-research

name: x-research
description: |
  X/Twitter research via xAI Grok API with x_search tool.
  Digests, thread analysis, trending topics, custom search.
  Designed for finding Telegram post ideas from X discussions.
  Triggers: x research, twitter research, x digest, twitter digest,
  что в твиттере, дайджест твиттера, тренды x, trending x,
  analyze tweet, анализ твита, x search, поиск в твиттере.

x-research

Research X/Twitter via xAI Grok API. Grok's `x_search` tool searches X in real-time and returns synthesized analysis with citations.

Перед запуском

Перед любым запуском скриптов создай рабочую копию скилла в `/home/claude/x-research` и работай уже из неё:

sh scripts/prepare_runtime.sh
cd /home/claude/x-research

`prepare_runtime.sh` копирует скилл и, если есть `config/.env`, нормализует его через `sed -i`: некавыченные значения с пробелами оборачиваются в кавычки в рабочей копии. Не выводи содержимое `.env` в ответ; при ошибке формата подскажи пользователю, какие строки нужно заключить в кавычки.

Config

Get an xAI API key at [console.x.ai](https://console.x.ai/), then:

cp config/.env.example config/.env

Edit `config/.env`: paste your key into `XAI_API_KEY`, configure accounts and topics. Quote any value that contains spaces so the file stays shell-compatible. Шаг подготовки также чинит некавыченные значения с пробелами в скопированном `.env`.

**Without `.env`:** skill works with explicit `--accounts`, `--query`, `--topics`.

**With `.env`:** digests and trending ready out of the box.

**Category registry** (same pattern as telegram-channel-parser):

X_CATEGORIES=ai,crypto         # available categories
X_DEFAULT_CATEGORY=ai           # default for "digest" without specifying

X_ACCOUNTS_AI_LABEL="AI & ML"
X_ACCOUNTS_AI=elonmusk,sama,AndrewYNg

X_TOPICS_AI=AI,LLM,GPT,Claude,agents,AGI

**Agent algorithm for digest/trending:** 1. Read `config/.env` 2. Parse `X_CATEGORIES` to get available categories 3. For each: `X_ACCOUNTS_<ID>` = handles, `X_TOPICS_<ID>` = topics, `X_ACCOUNTS_<ID>_LABEL` = name 4. Match user request to category label or use `X_DEFAULT_CATEGORY` 5. Pass to script via `--accounts` / `--topics`

**Priority:** `--accounts`/`--topics` explicit > category from `.env` > agent asks.

Details: [config/README.md](config/README.md).

Philosophy

1. **Live-first** — every call makes a fresh API request. Real-time data, never stale. 2. **Artifact store** — each run saves an immutable snapshot in `cache/runs/`. Use `--prefer-cache` to reuse. 3. **Structured output** — digest/trending/search return JSON with individual items for machine consumption. 4. **Context hygiene** — stdout limited to 30 lines. Full data in artifact file. 5. **Config-driven model** — model set in `.env`, auto-fallback if unavailable.

Workflow

Digest of subscribed accounts

# Default category from .env
bash scripts/digest.sh --period today

# Specific category
bash scripts/digest.sh --category crypto --period week

# Explicit accounts (no .env needed)
bash scripts/digest.sh --accounts "elonmusk,sama" --period today

Returns: structured items (author, date, summary, engagement, URL, topic) + Telegram post ideas.

Analyze a post/thread/topic

# By description
bash scripts/analyze.sh --query "Elon Musk's thread about open source AI"

# By URL
bash scripts/analyze.sh --url "https://x.com/elonmusk/status/123456" --query "context about the post"

# With time period
bash scripts/analyze.sh --query "debate about AI regulation" --period week

Returns: main thesis, key arguments, community reaction, sentiment, interesting findings, Telegram post angles.

Trending topics

# Default topics from .env
bash scripts/trending.sh --period today

# Specific topics
bash scripts/trending.sh --topics "Bitcoin,Ethereum,DeFi" --period today

# Category
bash scripts/trending.sh --category ai --period week

Returns: structured items (topic, summary, sentiment, key voices, engagement) + Telegram post ideas.

Custom search

# Free search
bash scripts/search.sh --query "Claude 4 reactions" --period week

# Search within specific accounts
bash scripts/search.sh --query "AI safety" --accounts "sama,ylecun" --period today

Returns: structured items + narrative summary + Telegram post ideas.

Reuse previous results

# Read last digest without making an API call
bash scripts/digest.sh --category ai --period today --prefer-cache

# Find artifact manually
bash scripts/find_latest.sh --script digest --category ai --period today

Scripts

bash scripts/<script>.sh [params]

| Script | Description | Key params | |--------|-------------|------------| | `digest.sh` | Digest of subscribed accounts | `--category`, `--accounts`, `--period` | | `analyze.sh` | Deep analysis of post/thread/topic | `--query`, `--url`, `--period` | | `trending.sh` | Trending topics by interests | `--category`, `--topics`, `--period` | | `search.sh` | Custom search query | `--query`, `--accounts`, `--period` | | `find_latest.sh` | Find latest cached artifact | `--script`, `--category`, `--query`, `--period` |

Common parameters

| Param | Required | Default | Description | |-------|----------|---------|-------------| | `--accounts` | no | from .env | X handles, comma-separated (without @) | | `--category` | no | from .env | Category ID from X_CATEGORIES | | `--period` | no | today | Time range: `1h`, `today`, `yesterday`, `week`, `Nd` | | `--query` | varies | — | Search query or post description | | `--topics` | no | from .env | Topics for trending, comma-separated | | `--url` | no | — | X post URL for analyze | | `--limit` | no | 30 | Max output lines | | `--prefer-cache` | no | — | Use latest cached artifact if available | | `--refresh` | no | — | Force live request (default behavior) |

Artifact store

Each run saves a JSON artifact in `cache/runs/` with full metadata:

{
  "meta": {
    "script": "di