Skip to main content
skill CX Codex

x-research · bradautomates — Claude Code skill: what it does, how to install

x-research discovers top-performing X/Twitter posts and content patterns via Apify Tweet Scraper V2, outputting structured analytics reports.

MIT 286 installs ★ 333 updated 2026-01-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bradautomates/head-of-content --skill x-research -a claude-code
Open on GitHub

What x-research does

The skill automates research across tracked X/Twitter profiles. It runs fetch_tweets.py against Apify Tweet Scraper V2 to grab posts over a specified period, enforcing a minimum query size of 50 tweets. Next, analyze_posts.py spots outliers using weighted metrics: bookmarks count 4x, replies 3x, retweets and quote tweets 2x, and likes 1x.

When posts contain video, an optional step with analyze_videos.py breaks down hooks and script structures via the Gemini API. Output lands in timestamped folders containing raw JSON feeds, an outliers list with hashtag trends, and report.md.

Execution requires valid APIFY_TOKEN credentials and a populated .claude/context/x-accounts.md list. Without apify-client installed in your Python environment, the fetch command fails immediately.

What it helps with

  • track high-performing competitor tweets on X
  • extract trending hashtags and recurring post formats
  • calculate weighted engagement rates across accounts
  • inspect video hooks with Gemini models

Example prompts for the agent

  • Run research on tracked X accounts for the last 30 days
  • Find outlier tweets and summarize top content patterns
  • Analyze high-performing X posts and compile the markdown report

How to install x-research

1Skills CLI (Vercel)

npx skills add bradautomates/head-of-content --skill x-research -a claude-code

2Manually: 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 to install x-research in Claude Code?

Run npx skills add bradautomates/head-of-content --skill x-research -a claude-code.

What does x-research do?

It pulls tweets via Apify, identifies statistical engagement outliers with weighted metrics, and writes an analytical markdown report.

What prerequisites are required?

You need an APIFY_TOKEN, the apify-client package, and accounts listed in .claude/context/x-accounts.md. A GEMINI_API_KEY is needed only for video hooks analysis.

Source text

SKILL.md · MIT
---
name: x-research
description: |
  Research high-performing X/Twitter content from tracked accounts using Apify's Tweet Scraper V2.
  Identifies outlier tweets, trending topics, and content patterns to inform content strategy.

  Use when asked to:
  - Find trending tweets or content in a niche
  - Research what's performing on X/Twitter
  - Identify high-performing tweet patterns
  - Analyze competitors' X content
  - Generate content ideas from X trends
  - Run X/Twitter research

  Triggers: "x research", "twitter research", "find trending tweets", "analyze x accounts",
  "what's working on twitter", "content research x", "tweet analysis"
---

# X/Twitter Research

Research high-performing tweets from tracked accounts, identify outliers, and optionally analyze video content for hooks and structure.

## Prerequisites

- `APIFY_TOKEN` environment variable or in `.env`
- `GEMINI_API_KEY` environment variable or in `.env` (for video analysis)
- `apify-client` and `google-genai` Python packages
- Accounts configured in `.claude/context/x-accounts.md`

Verify setup:
```bash
python3 -c "
import os
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass
from apify_client import ApifyClient
assert os.environ.get('APIFY_TOKEN'), 'APIFY_TOKEN not set'
" && echo "Prerequisites OK"
```

## Workflow

### 1. Create Run Folder

```bash
RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && echo "$RUN_FOLDER"
```

### 2. Fetch Tweets

```bash
python3 .claude/skills/x-research/scripts/fetch_tweets.py \
  --days 30 \
  --max-items 100 \
  --output {RUN_FOLDER}/raw.json
```

Parameters:
- `--days`: Days back to search (default: 30)
- `--max-items`: Max tweets per account (default: 100)
- `--handles`: Override accounts file with specific handles

**API Limits:** Minimum 50 tweets per query required. Wait a couple minutes between runs.

### 3. Identify Outliers

```bash
python3 .claude/skills/x-research/scripts/analyze_posts.py \
  --input {RUN_FOLDER}/raw.json \
  --output {RUN_FOLDER}/outliers.json \
  --threshold 2.0
```

Output JSON contains:
- `total_posts`: Number of tweets analyzed
- `outlier_count`: Number of outliers found
- `topics`: Top hashtags, mentions, and keywords
- `content_patterns`: Analysis of what formats perform well
- `accounts`: List of accounts analyzed
- `outliers`: Array of outlier tweets with engagement metrics

### 4. Analyze Videos with AI (Optional)

If outliers contain video content:

```bash
python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform x \
  --max-videos 5
```

Note: X/Twitter is primarily text-based. Video analysis is optional and only useful when outliers contain video posts.

### 5. Generate Report

Read `{RUN_FOLDER}/outliers.json` (and optionally `{RUN_FOLDER}/video-analysis.json`), then generate `{RUN_FOLDER}/report.md`.

**Report Structure:**

```markdown
# X/Twitter Research Report

Generated: {date}

## Summary

- **Total tweets analyzed**: {total_posts}
- **Outlier tweets identified**: {outlier_count}
- **Outlier rate**: {percentage}%

## Top Performing Tweets (Outliers)

### 1. @{username} ({name})

> {tweet_text}

- **URL**: {url}
- **Date**: {created_at}
- **Engagement**: {likes} likes | {retweets} RTs | {replies} replies | {bookmarks} bookmarks
- **Engagement Score**: {score}
- **Engagement Rate**: {rate}%
- **Followers**: {followers}

[Repeat for top 15 outliers]

## Top Performing Hooks (if video analysis available)

### Hook 1: {technique} - @{username}
- **Opening**: "{opening_line}"
- **Why it works**: {attention_grab}
- **Replicable Formula**: {replicable_formula}
- [Watch Video]({url})

## Trending Topics

### Top Hashtags
[From outliers.json topics.hashtags]

### Top Keywords
[From outliers.json topics.keywords]

### Top Mentions
[From outliers.json topics.mentions]

## Content Patterns in Outliers

| Pattern | Count | Percentage |
|---------|-------|------------|
| Contains media | {count} | {pct}% |
| Contains external link | {count} | {pct}% |
| Thread format | {count} | {pct}% |
| Quote tweet | {count} | {pct}% |
| Asks a question | {count} | {pct}% |
| List/numbered format | {count} | {pct}% |
| Short (<100 chars) | {count} | {pct}% |
| Medium (100-200 chars) | {count} | {pct}% |
| Long (>200 chars) | {count} | {pct}% |

## Actionable Takeaways

[Synthesize patterns into 4-6 specific recommendations]

## Accounts Analyzed

[List accounts]
```

Focus on actionable insights. Content patterns and trending topics are key for X/Twitter research.

## Quick Reference

Full pipeline:
```bash
RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && \
python3 .claude/skills/x-research/scripts/fetch_tweets.py -o "$RUN_FOLDER/raw.json" && \
python3 .claude/skills/x-research/scripts/analyze_posts.py -i "$RUN_FOLDER/raw.json" -o "$RUN_FOLDER/outliers.json"
```

With video analysis (optional):
```bash
python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py -i "$RUN_FOLDER/outliers.json" -o "$RUN_FOLDER/video-analysis.json" -p x
```

Then read JSON files and generate the report.

## Engagement Metrics

**Engagement Score (weighted):**
- Bookmarks: 4x (highest signal - saved for reference)
- Replies: 3x (active conversation)
- Retweets: 2x (amplification)
- Quotes: 2x (engagement with commentary)
- Likes: 1x (passive approval)

**Outlier Detection:** Tweets with engagement rate > mean + (threshold x std_dev)

**Engagement Rate:** (score / followers) x 100

## Output Location

All output goes to timestamped run folders:
```
x-research/
└── {YYYY-MM-DD_HHMMSS}/
    ├── raw.json            # Raw tweet data from Apify
    ├── outliers.json       # Outliers with metadata and topics
    ├── video-analysis.json # AI video analysis (optional)
    └── report.md           # Final report
```

© bradautomates · MIT · bradautomates/head-of-content

Similar skills

All skills for Marketing and content →

x-research by other authors comes first.

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 x-research rohunvora 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. CX Codex +1 ★ 540repo stars analyzing-twitter-sentiment-for-topic apidojo analyzing-twitter-sentiment-for-topic gathers posts on Twitter/X via Apify and evaluates public tone for brands, events, or keywords. Generates sentiment breakdown, key recurring issues, and top posts. CX Codex +1 966installs building-full-social-audit-for-brand apidojo building-full-social-audit-for-brand audits brand profiles across Twitter, Instagram, TikTok, and YouTube via Apify scrapers. Computes engagement metrics and an aggregate brand health score. CX Codex +1 962installs x-content-intelligence MSApps-Mobile x-content-intelligence is a Claude Code plugin that studies X posts and helps shape content for a particular community. It kicks in for trend research, audience analysis, and drafting posts or replies. ★ 11repo stars x-twitter-scraper official github x-twitter-scraper — a GitHub Copilot skill that connects Xquik X API to code, pipelines, and agents. Covers tweet search, follower exports, extraction jobs, webhooks, and MCP tooling. CX Codex +1 80installs apify-influencer-brand-collabs Natasha Lekh apify-influencer-brand-collabs is a Claude Code skill that finds Instagram sponsorships through Meta Ad Library. It identifies brands that paid a creator or creators who promoted a brand. CX Codex +1 194installs

From the same set6

Project sponsors

Companies that keep this analytics open