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
npx skills add bradautomates/head-of-content --skill x-research -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/x-research/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/x-research/
1Skills CLI (Vercel)
npx skills add bradautomates/head-of-content --skill x-research -a codex2Manually: put the files in place
.agents/skills/x-research/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bradautomates/head-of-content --skill x-research -a cursor2Manually: put the files in place
.cursor/skills/x-research/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bradautomates/head-of-content .claude/skills/x-research2Manually: put the files in place
.github/skills/x-research/SKILL.md1Skills CLI (Vercel)
npx skills add bradautomates/head-of-content --skill x-research -a gemini-cli2Platform CLI
gemini skills install https://github.com/bradautomates/head-of-content --path .claude/skills/x-researchManually: put the files in place
.devin/skills/x-research/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bradautomates/head-of-content --skill x-research -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.