creator-insights

What this skill does

# Twitter Creator Insights

This skill provides Twitter/X content creators with actionable intelligence about their account performance, trending topics in their niche, and competitive analysis. Includes account analytics, viral content discovery, thread/follower intelligence, and AI-powered content generation.

## When to Use This Skill

Invoke this skill when:
- A creator requests analysis of their Twitter account or another account
- User asks about trending content or viral tweets in a specific niche
- User wants to understand what content performs well in their space
- User needs recommendations for improving their Twitter strategy
- User asks about competitor or similar account activity
- User wants to find influential accounts in a niche
- **User wants to identify VIP followers or "hidden gem" accounts** (NEW)
- **User asks which threads attracted high-value engagement** (NEW)
- **User needs help drafting tweets or analyzing viral patterns with AI** (NEW)
- **User wants to optimize an existing tweet before posting** (NEW)


## Core Workflow

The skill follows a **fetch → analyze → score → recommend** pipeline:

### 1. Account Analysis Phase

**Objective**: Deep-dive into a Twitter account's performance and content patterns.

**Process**:
1. Run `python scripts/twitter_analyzer.py --username [handle] --tweets 100`
2. The system fetches:
   - User profile (followers, bio, verification status)
   - Recent tweets (up to 100)
   - Engagement metrics (likes, RTs, replies, quotes, views)
3. Calculates:
   - Engagement rate (weighted by follower count)
   - Content patterns (hashtag usage, thread frequency, tweet types)
   - Posting schedule optimization
   - Viral content identification (outliers >2σ above mean)

**Key Metrics**:
- **Engagement Rate**: (likes + RTs + replies) / followers × 100
- **Like/RT Ratio**: Indicates passive vs. active engagement
- **Thread Performance**: Threads vs. standalone tweet comparison
- **Viral Multiplier**: How many times above average a tweet performed

**Output Structure**:
```
TWITTER ANALYSIS: @username
├── Profile metrics (followers, tweets, verification)
├── Engagement metrics (rates, averages, ratios)
├── Viral content (top 5 tweets with multiplier)
├── Thread analysis (performance comparison)
├── Hashtag performance (which hashtags drive engagement)
├── Posting schedule (best times based on data)
└── Recommendations (7 actionable insights)
```

### 2. Niche Detection Phase

**Objective**: Identify a creator's content niche and posting style.

**Process**:
1. Run `python scripts/profile_analyzer.py --profile @username`
2. Analyzes last 30 tweets for:
   - Keyword frequency across 14 predefined niches
   - Content themes (most common topics)
   - Tone analysis (professional, casual, educational, entertaining)
   - Posting cadence and consistency

**Niche Categories**:
- Tech, AI/ML, Crypto/Web3, Business, Marketing
- Gaming, Fitness, Beauty, Food, Travel
- Comedy, Education, Music, Art

**Scoring Method**:
```python
niche_score = Σ(keyword_matches) for niche in all_niches
primary_niche = max(niche_scores)
secondary_niches = scores > (primary_score × 0.5)
```

### 3. Trend Discovery Phase

**Objective**: Find viral content and trending topics in a specific niche.

**Process**:
1. Run `python scripts/trend_aggregator.py --niche "[topic]" --viral-examples --limit 10`
2. Search for tweets matching: `"{niche}" min_faves:1000 -is:retweet`
3. Rank by total engagement: `likes + (retweets × 2) + (replies × 1.5)`
4. Analyze viral factors:
   - Hashtag usage patterns
   - Tweet length optimization
   - Thread vs. single tweet
   - Question-based engagement
   - Quote tweet ratio (conversation starter indicator)

**Viral Factor Detection**:
```python
if len(hashtags) > 0: "used {n} hashtags"
if '?' in text: "engaged audience with question"
if len(text) > 200: "detailed/thorough content"
elif len(text) < 100: "concise and punchy"
if quotes > retweets/2: "sparked conversation"
```

### 4. Competitive Intelligence Phase

**Objective**: Identify top performers and rising accounts in a niche.

**Process**:
1. Run `python scripts/trend_aggregator.py --niche "[topic]" --find-accounts --limit 10`
2. Aggregate top 50 viral tweets in niche
3. Group by author and calculate:
   - Total engagement across all tweets
   - Average engagement per tweet
   - Follower count
4. Sort by engagement/follower ratio (efficiency metric)

**Account Scoring**:
```python
account_score = (total_engagement / follower_count) × tweet_frequency
# Identifies accounts that punch above their weight
```

### 5. Thread Intelligence Phase **NEW**

**Objective**: Identify high-performing threads and track engagement from influential accounts.

**Process**:
1. Run `python scripts/thread_intelligence.py --username [handle] --tweets 50 --threshold 10000`
2. Fetches user's timeline and identifies multi-tweet threads
3. For each thread:
   - Gets full thread context
   - Fetches all replies
   - Identifies high-value repliers (accounts with >10K followers by default)
   - Tracks engagement patterns
4. Ranks threads by number of high-value replies

**Influence Threshold**:
```python
high_value_account = follower_count >= threshold  # Default: 10,000
# Configurable via --threshold parameter
```

**Output Structure**:
```
THREAD INTELLIGENCE: @username
├── Thread Statistics (total, high-value reply count, engagement rate)
├── Top Threads (ranked by high-value replies)
│   ├── Thread text preview
│   ├── Tweet count in thread
│   ├── Total replies vs high-value replies
│   └── Reply engagement score
├── Top Thread Details (deep-dive on #1 thread)
│   ├── Full text preview
│   ├── High-value repliers list
│   └── Follower counts
└── Most Engaged High-Value Accounts (across all threads)
    ├── Reply count per account
    └── Number of threads engaged with
```

**Comparison Mode**:
```bash
python scripts/thread_intelligence.py --username [handle] --compare --tweets 50
```
Compares thread performance vs standalone tweets to determine optimal content format.

### 6. Follower Intelligence Phase **NEW**

**Objective**: Discover VIP followers using combined influence scoring and engagement tracking.

**Process**:
1. Run `python scripts/follower_intelligence.py --username [handle] --tweets 20 --max-followers 500`
2. Fetches user's followers (newest first, up to 500)
3. Tracks engagement across recent tweets:
   - Who retweeted (via `get_tweet_retweeters` endpoint)
   - Who replied (via `get_tweet_replies` endpoint)
4. Calculates influence score for each follower:
   ```python
   influence_score = (followers × 0.7) + (engagement_count × 1000 × 0.3)
   ```
5. Identifies special segments:
   - **VIP Followers**: Top 50 by influence score
   - **Hidden Gems**: <5K followers but ≥2 interactions
   - **Top Engagers**: Most interactions regardless of follower count

**Influence Score Formula**:
```python
# Balanced scoring: audience size (70%) + actual engagement (30%)
influence = (follower_count × 0.7) + (total_interactions × 1000 × 0.3)

# Example:
# Account A: 100K followers, 0 interactions = 70,000 influence
# Account B: 10K followers, 5 interactions = 8,500 influence
# Account C: 2K followers, 10 interactions = 4,400 influence (hidden gem!)
```

**Output Structure**:
```
VIP FOLLOWERS: @username
├── Engagement Statistics
│   ├── Total followers analyzed
│   ├── Engaged followers (who interacted)
│   └── Engagement rate %
├── Top VIP Followers (by influence score)
│   ├── Username, follower count, verified status
│   ├── Engagement breakdown (RTs, replies)
│   └── Influence score
├── Hidden Gems (high engagement, low followers)
│   └── Rising creators to nurture
└── Top Engagers (most interactions)
    └── Your biggest supporters
```

**Growth Analysis Mode**:
```bash
python scripts/follower_intelligence.py --username [handle] --growth --max-followers 200
```
Analyzes follower quality distribution (micro, small, medium, large, mega).

### 7. AI Content Generation Phase **NEW**