Skip to main content
skill CX Codex

x-research · trailofbits — Claude Code skill: X search and installation

The x-research skill for Claude Code searches recent X discussions, opens threads, and gathers sources to check developer reactions to a release or API change.

MIT ★ 540 updated 2026-07-14

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add trailofbits/skills-curated
/plugin install x-research@skills-curated
Open on GitHub

What x-research does

x-research turns a research question into focused searches, sorts posts by engagement, and helps follow threads and linked material. It can fetch profiles and individual posts, keep an account watchlist, and save results. Identical searches use a cache with a 15-minute TTL.

You need an X API token set as X_BEARER_TOKEN or XAI_API_KEY, plus Python 3.11+ and uv. The CLI runs its script through uv run; API endpoint details are in a reference file. This is a read-only research tool, so it cannot publish posts or manage an X account.

What it helps with

  • find recent views on a library or API
  • sort posts by likes or impressions
  • fetch a conversation from its root post
  • check recent posts from watched accounts
  • assemble linked sources into a research briefing

Example prompts for the agent

  • Search X for recent discussion of this library release and group the views by theme.
  • Check what people are saying about this API change and follow the key threads.
  • Add this account to the watchlist and check its recent posts.

How to install x-research

1Plugin marketplace

/plugin marketplace add trailofbits/skills-curated
/plugin install x-research@skills-curated

This installs the whole x-research plugin with all its skills

2Skills CLI (Vercel)

npx skills add trailofbits/skills-curated --skill x-research -a claude-code

3Manually: put the files in place

~/.claude/skills/x-research/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/x-research/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about x-research

How do I install x-research in Claude Code?

Run /plugin marketplace add trailofbits/skills-curated, then run /plugin install x-research@skills-curated.

What does x-research do?

It searches X, ranks posts, fetches threads, and helps assemble a sourced briefing. It can also retrieve profiles and track selected accounts.

What does x-research need to run?

Provide an X API token through X_BEARER_TOKEN or XAI_API_KEY. Python 3.11+ and uv are also required.

Source text

SKILL.md · MIT
---
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

```bash
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:**
```bash
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

```bash
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

```bash
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

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

### Watchlist

```bash
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

```bash
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:
```bash
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 with `has:links`

## When to Use

- Researching what developers/experts/community thinks about a topic
- Getting real-time perspectives on breaking news or product launches
- Finding technical discussions about libraries, frameworks, or APIs
- Monitoring what key accounts are posting about
- Gathering sourced evidence for competitive analysis or market research
- Quick pulse check on a topic before deeper investigation

## When NOT to Use

- Posting tweets, replying, or managing an X account (read-only tool)
- Historical research beyond 7 days (uses recent search endpoint only)
- Searching non-X platforms (use web search tools instead)
- Tasks where web search provides better results (X is best for real-time
  opinions, discussions, and breaking news -- not reference docs)

## Cost Awareness

X API uses pay-per-use pricing ($0.005/post read, $0.01/user lookup). Quick mode
keeps costs under ~$0.50/search. Always check the cost display after each search.
Cache prevents duplicate charges. See `references/x-api.md` for full pricing.

## File Structure

```
skills/x-research/
  SKILL.md           (this file)
  scripts/
    x_search.py      (CLI entry point, run with uv)
    x_api.py         (X API wrapper)
    x_cache.py       (file-based cache, 15min TTL)
    x_format.py      (terminal + markdown formatters)
  data/
    watchlist.json   (accounts to monitor)
    cache/           (auto-managed)
  references/
    x-api.md         (X API endpoint reference)
```

© rohunvora · MIT · trailofbits/skills-curated

Similar skills

All skills for Science and research →

x-research by other authors comes first.

x-research bradautomates x-research discovers top-performing X/Twitter posts and content patterns via Apify Tweet Scraper V2, outputting structured analytics reports. CX Codex +1 286installs x-research PostPlusAI x-research — a skill that turns a question about public X posts, threads, replies or accounts into a bounded research run. Handy when a marketing or product call needs evidence. CX Codex +1 284installs ai-research-reproduction lllllllama ai-research-reproduction is a Claude Code skill for reproducing deep-learning runs from a repository README. It picks a small documented target and saves the evidence bundle to repro_outputs/. CX Codex +1 363,300installs firecrawl-research-papers firecrawl firecrawl-research-papers is a Claude Code skill that finds and synthesizes academic literature into structured reviews from PubMed, bioRxiv, medRxiv, and arXiv. CX Codex +1 34,200installs firecrawl-research-index firecrawl firecrawl-research-index — a skill to search papers in Firecrawl's index, covering abstracts from PubMed, bioRxiv, medRxiv, and arXiv. CX Codex +1 25,900installs tavily-research tavily-ai tavily-research — a skill for Claude Code and other platforms that gathers and weighs info from multiple sources. It triggers when performing in-depth analysis of markets, tech, or trends. CX Codex +1 25,100installs parallel-deep-research parallel parallel-deep-research runs multi-step deep research jobs using parallel-cli. Use it when you need an exhaustive markdown report with citations rather than a quick web search. CX Codex +1 16,400installs x-read Eugeniu Ghelbur x-read — a command that performs deep analysis of X (Twitter) posts or threads using Grok. Extracts the original text, thread chain, key claims, reply sentiment, and notable voices in the conversation. CX Codex +1 ★ 5,412repo stars

From the same set51

The whole set →
ffuf-web-fuzzing ffuf-web-fuzzing guides Claude Code through web fuzzing using ffuf during authorized penetration testing engagements. CX Codex +1 ★ 540repo stars openai-cloudflare-deploy openai-cloudflare-deploy is a Claude Code skill that automates deploying apps and infrastructure to Cloudflare. It activates for requests to deploy, host, publish, or set up a Cloudflare project. CX Codex +1 ★ 540repo stars scv-scan scv-scan is a Claude Code skill that scans Solidity projects for contract vulnerabilities. It runs for pre-release security checks or reviews after code changes. CX Codex +1 ★ 540repo stars review-plugin review-plugin audits a plugin directory for script flaws and project standard violations, automatically fixing detected issues. CX Codex +1 ★ 540repo stars skill-extractor skill-extractor turns a finished session into a reusable Claude skill: the cause of a failure, a workaround, the symptom that points to it. CX Codex +1 ★ 540repo stars openai-screenshot openai-screenshot captures desktop screenshots, active windows, or pixel regions directly from Claude Code. Built for OS-level interface inspection. CX Codex +1 ★ 540repo stars openai-develop-web-game openai-develop-web-game guides an agent through building HTML and JavaScript browser games with incremental changes and Playwright-based tests. CX Codex +1 ★ 540repo stars writing-great-skills Use this skill to shape, review, or trim SKILL.md files. It helps when a skill behaves inconsistently or its instructions have grown unwieldy. CX Codex +1 ★ 540repo stars

Project sponsors

Companies that keep this analytics open