/x-research

name: x-research
description: >
  Searches X/Twitter for real-time perspectives, dev discussions, product feedback,
  breaking news, and expert opinions using the X API v2. Provides search with
  engagement sorting, user profiles, thread fetching, watchlists, and result caching.
  Use when: (1) user says "x research", "search x for", "search twitter for",
  "what are people saying about", "what's twitter saying", "check x for", "x search",
  (2) user needs recent X discourse on a topic (library releases, API changes, product
  launches, industry events), (3) user wants to find what devs/experts/community thinks
  about a topic. NOT for: posting tweets or account management.
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
  - WebFetch

X Research

Agentic research over X/Twitter. Decompose research questions into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize sourced briefings.

For X API details (endpoints, operators, response format): read `{baseDir}/skills/x-research/references/x-api.md`.

Prerequisites

• **X API Bearer Token** -- set `X_BEARER_TOKEN` (or `XAI_API_KEY`) env var
• **Python 3.11+** and **uv** (`pip install uv` or https://docs.astral.sh/uv/)

CLI Tool

All commands use `uv run` for automatic dependency management:

Search

uv run {baseDir}/skills/x-research/scripts/x_search.py search "<query>" [options]

**Options:**

• `--sort likes|impressions|retweets|recent` -- sort order (default: likes)
• `--since 1h|3h|12h|1d|7d` -- time filter (default: last 7 days)
• `--min-likes N` -- filter by minimum likes
• `--min-impressions N` -- filter by minimum impressions
• `--pages N` -- pages to fetch, 1-5 (default: 1, 100 tweets/page)
• `--limit N` -- max results to display (default: 15)
• `--quick` -- quick mode: 1 page, max 10 results, auto noise filter, 1hr cache
• `--from-user <username>` -- shorthand for `from:username` in query
• `--quality` -- filter low-engagement tweets (min 10 likes, post-hoc)
• `--no-replies` -- exclude replies
• `--save` -- save results to `~/x-research-output/`
• `--json` -- raw JSON output
• `--markdown` -- markdown output for research docs

Auto-adds `-is:retweet` unless query already includes it. All searches display estimated API cost.

**Examples:**

uv run {baseDir}/skills/x-research/scripts/x_search.py search "claude code" --sort likes --limit 10
uv run {baseDir}/skills/x-research/scripts/x_search.py search "from:anthropic" --sort recent
uv run {baseDir}/skills/x-research/scripts/x_search.py search "(cursor OR windsurf) AI editor" --pages 2 --save
uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quick
uv run {baseDir}/skills/x-research/scripts/x_search.py search "AI agents" --quality --quick

Profile

uv run {baseDir}/skills/x-research/scripts/x_search.py profile <username> [--count N] [--replies] [--json]

Fetches recent tweets from a specific user (excludes replies by default).

Thread

uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id> [--pages N]

Fetches full conversation thread by root tweet ID.

Single Tweet

uv run {baseDir}/skills/x-research/scripts/x_search.py tweet <tweet_id> [--json]

Watchlist

uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist                        # Show all
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist add <user> [note]      # Add account
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist remove <user>           # Remove
uv run {baseDir}/skills/x-research/scripts/x_search.py watchlist check                   # Check recent

Watchlist stored in `{baseDir}/skills/x-research/data/watchlist.json`.

Cache

uv run {baseDir}/skills/x-research/scripts/x_search.py cache clear

15-minute TTL. Avoids re-fetching identical queries.

Research Loop (Agentic)

When doing deep research (not just a quick search), follow this loop:

1. Decompose the Question into Queries

Turn the research question into 3-5 keyword queries using X search operators:

• **Core query**: Direct keywords for the topic
• **Expert voices**: `from:` specific known experts
• **Pain points**: Keywords like `(broken OR bug OR issue OR migration)`
• **Positive signal**: Keywords like `(shipped OR love OR fast OR benchmark)`
• **Links**: `url:github.com` or `url:` specific domains
• **Noise reduction**: `-is:retweet` (auto-added), add `-is:reply` if needed
• **Spam filter**: Add `-airdrop -giveaway -whitelist` for crypto-adjacent topics

2. Search and Extract

Run each query via CLI. After each, assess:

• Signal or noise? Adjust operators.
• Key voices worth searching `from:` specifically?
• Threads worth following via `thread` command?
• Linked resources worth deep-diving with `WebFetch`?

3. Follow Threads

When a tweet has high engagement or is a thread starter:

uv run {baseDir}/skills/x-research/scripts/x_search.py thread <tweet_id>

4. Deep-Dive Linked Content

When tweets link to GitHub repos, blog posts, or docs, fetch with `WebFetch`. Prioritize links that:

• Multiple tweets reference
• Come from high-engagement tweets
• Point to technical resources directly relevant to the question

5. Synthesize

Group findings by theme, not by query:

### [Theme/Finding Title]

[1-2 sentence summary]

- @username: "[key quote]" (NL, NI) [Tweet](url)
- @username2: "[another perspective]" (NL, NI) [Tweet](url)

Resources shared:
- [Resource title](url) -- [what it is]

6. Save

Use `--save` flag or save manually.

Refinement Heuristics

• **Too much noise?** Add `-is:reply`, use `--sort likes`, narrow keywords
• **Too few results?** Broaden with `OR`, remove restrictive operators
• **Spam flooding results?** Add `-$ -airdrop -giveaway -whitelist`
• **Expert takes only?** Use `from:` or `--min-likes 50`
• **Substance over hot takes?** Search wit