trending-content-scout

# Trending Content Scout

Scan YouTube, TikTok, X, and Reddit for top-performing content by real engagement data.
Find winning formats, hooks, and content gaps — **before** you create anything. Stop
guessing what works. See what's already winning, then build on proven patterns.

This skill is the **data foundation** for the entire content pipeline. Run it first,
then feed its output into `content-angle-ranker`, `viral-post-writer`, `tiktok-script-writer`,
or any S2/S3 content skill.

## Stage

This skill belongs to Stage S1: Research

## When to Use

- Before creating any content for a keyword or niche
- When entering a new niche and need to understand what content works
- When comparing engagement across platforms for a topic
- When looking for content gaps competitors haven't filled
- When benchmarking your existing content against what's performing
- As the first step in any content creation workflow (before S2 skills)

## Input Schema

```yaml
keyword: string               # (required) Search keyword — "AI video tools", "email marketing tips"
platforms: string[]            # (optional, default: ["youtube", "tiktok"])
                               # Options: "youtube" | "tiktok" | "x" | "reddit"
sort_by: string                # (optional, default: "engagement_score")
                               # Options: "views" | "likes" | "engagement_score" | "recency"
time_range: string             # (optional, default: "30d") "7d" | "30d" | "90d" | "all"
limit: number                  # (optional, default: 20) Max content pieces to analyze
product: object                # (optional) Specific product to focus on
  name: string                 # "HeyGen"
  url: string                  # "https://heygen.com"
```

No `api_config` needed in input — skills auto-detect configuration from conversation
context, project settings, or CLAUDE.md. See `shared/references/social-data-providers.md`
for setup instructions.

## Workflow

### Step 1: Determine Data Source

Check if the user has API configuration available:

```
IF social_data_config exists in context/settings for a platform:
  → Use configured API for that platform
  → Structured data: exact views, likes, comments, shares
  
ELSE (default — no API):
  → Use web_search + web_fetch
  → Still effective — see fallback methods below
```

**API mode** (when configured):

For each platform in `platforms`:
- YouTube: Search API → get video list → Details API → get statistics (views, likes, comments)
- TikTok: Search API → get video list with stats (playCount, diggCount, commentCount, shareCount)
- X: Search API → get tweets with public_metrics (impressions, likes, retweets, replies)
- Reddit: Search API → get posts with score and comment count

See `shared/references/social-data-providers.md` for specific API endpoints and config.

**web_search fallback** (no API — default):

```
For YouTube:
  web_search "[keyword] site:youtube.com" → top 10-15 video results
  For each result: extract title, channel, view count from search snippet
  Optional: web_fetch individual video pages for likes/comments (slower)

For TikTok:
  web_search "[keyword] tiktok" → find popular TikTok content
  web_search "[keyword] site:tiktok.com" → direct TikTok results
  Extract: titles, creators, approximate view counts from snippets

For X:
  web_search "[keyword] site:x.com" OR "[keyword] site:twitter.com" → top tweets
  Extract: tweet text, author, engagement signals from snippets

For Reddit:
  web_search "[keyword] site:reddit.com" → top Reddit discussions
  web_fetch top results → extract upvotes, comments from page
  web_search "reddit [keyword] top upvoted" → find popular threads
```

Note which data source was used — include in output for transparency.

### Step 2: Collect and Normalize Data

For each content piece found, extract and normalize into a standard schema:

```yaml
ContentItem:
  title: string                # Video title, tweet text (first line), post title
  url: string                  # Direct link to content
  platform: string             # "youtube" | "tiktok" | "x" | "reddit"
  creator: string              # Channel name, @handle, username
  views: number                # View/impression count (0 if unavailable)
  likes: number                # Like/upvote count (0 if unavailable)
  comments: number             # Comment/reply count (0 if unavailable)
  shares: number               # Share/retweet count (0 if unavailable)
  published_date: string       # ISO date or relative ("3 days ago")
  duration: string             # Video duration ("2:34") — video only
  engagement_score: number     # Calculated — see formula below
  content_format: string       # Detected format (see classification below)
  hook_type: string            # Detected hook style (see classification below)
```

**Engagement Score Formula** (consistent across all Affitor skills):

```
engagement_score = (likes × 2 + comments × 3 + shares × 5) / max(views, 1) × 1000
```

Platform-specific adjustments:
- **Reddit:** `(score × 2 + num_comments × 3) / max(score, 1) × 1000` (no share count)
- **X:** Use retweets as shares, replies as comments
- **YouTube:** Estimate shares as `comments × 0.5` (not available via most APIs)
- **web_search fallback:** If only views are available, use `views` as the ranking signal and note that engagement_score is estimated

See `shared/references/social-data-providers.md` for full formula documentation.

**Content Format Classification:**

Detect format from title and description:
- **comparison:** Contains "vs", "versus", "compared to", "X or Y", "better than"
- **review:** Contains "review", "honest review", "worth it", "my experience"
- **tutorial:** Contains "how to", "step by step", "guide", "tutorial", "walkthrough"
- **listicle:** Contains "top X", "best X", "X tools", "X ways", numbers in title
- **reaction:** Contains "I tried", "testing", "first time using", "is it worth"
- **story:** Contains "how I", "my journey", "I made $X", personal narrative
- *