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

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:

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
• demo: Contains "demo", "showing", "watch me use", "in action"
• explainer: Contains "what is", "explained", "why you need", "everything about"

Hook Type Classification:

Detect from first sentence/title:

• question: Starts with or contains a question
• shock: Contains surprising numbers, "you won't believe", extreme claims
• bold_claim: "This replaced X", "The only tool you need", definitive statements
• demo_first: Starts with showing a result or end product
• relatable: "POV:", "When you...", shared experience pattern
• contrarian: "Stop using X", "X is overrated", against conventional wisdom

Step 3: Sort and Rank

Sort all collected content by the chosen sort_by parameter:

• engagement_score (default): Best for finding content that resonates regardless of creator size
• views: Best for finding content with broadest reach
• likes: Best for finding content people actively endorse
• recency: Best for finding what's working RIGHT NOW

Take top limit results after sorting.

Step 4: Analyze Patterns

From the top content, extract actionable patterns:

Format Analysis:

For each content_format in top results:
  count: how many of top 20 use this format
  avg_engagement: average engagement_score for this format
  best_example: highest engagement content in this format

Hook Analysis:

For each hook_type in top results:
  count: how many use this hook
  avg_engagement: average engagement_score
  best_example: highest engagement content with this hook

Duration Analysis (video platforms only):

Group videos by duration buckets:
  <30s, 30-60s, 60-120s, 2-5min, 5-10min, 10-20min, 20min+
For each bucket: count and average engagement
→ Identify optimal duration range

Creator Analysis:

For each unique creator in top results:
  content_count: how many pieces in top results
  avg_engagement: average engagement score
  platforms: which platforms they're on
  dominant_format: their most-used format

Gap Analysis:

This is the most strategically valuable output. Look for:

1. Format gaps: If 90% of top content is reviews, comparisons are underserved
2. Platform gaps: If YouTube is saturated but TikTok has few results → TikTok opportunity
3. Angle gaps: Common user questions (visible in comments/replies) that no top content addresses
4. Audience gaps: All content targets advanced users → beginner content is a gap
5. Recency gaps: Top content is 6+ months old → fresh take on same topic is an opportunity
6. Honesty gaps: All content is positive/promotional → honest cons/limitations review is a gap

For gap analysis with web_search fallback:

• web_search "[keyword] reddit questions" → find unanswered user questions
• web_search "[keyword] alternatives nobody talks about" → find underserved angles

Step 5: Calculate Engagement Benchmark

Set benchmark ranges so user knows what "good" looks like:

engagement_benchmark:
  sample_size: number           # how many content pieces analyzed
  median_views: number          # 50th percentile views
  median_engagement_score: number
  top_10_percent_threshold:
    views: number               # views needed to be in top 10%
    engagement_score: number    # engagement_score needed for top 10%
  platform_averages:            # per-platform breakdown
    youtube:
      median_views: number
      median_engagement: number
    tiktok:
      median_views: number
      median_engagement: number

Step 6: Self-Validation

Before presenting output, verify:

• Data source is clearly stated (API vs web_search)
• Engagement scores are calculated consistently using the standard formula
• Content format and hook classifications are based on actual title/description analysis, not guesses
• Gap analysis includes at least 3 specific, actionable gaps
• Benchmark numbers are derived from actual data, not made up
• Recommendations connect to specific downstream skills

If any check fails, fix the output before delivering. Do not flag the checklist to the user.

Output Schema

Other skills can consume these fields from conversation context:

output_schema_version: "1.0.0"
keyword: string
platforms_scanned: string[]
data_source: "api" | "web_search" | "mixed"   # transparency
total_content_analyzed: number
top_content: ContentItem[]                     # top results sorted by sort_by
pattern_analysis:
  winning_formats:
    - format: string           # "comparison"
      count: number            # 9
      percentage: number       # 45
      avg_engagement: number   # 35.2
      best_example:
        title: string
        url: string
        engagement_score: number
  winning_hooks:
    - hook_type: string
      count: number
      avg_engagement: number
      best_example:
        title: string
        url: string
  optimal_duration:
    range: string              # "45-60 seconds"
    platform: string           # "tiktok"
    avg_engagement: number
  top_creators:
    - name: string
      platform: string
      content_count: number
      avg_engagement: number
      dominant_format: string
  content_gaps: string[]       # specific, actionable gaps
engagement_benchmark:
  sample_size: number
  median_views: number
  median_engagement_score: number
  top_10_percent_threshold:
    views: number
    engagement_score: number
  platform_averages: object
recommended_angles: string[]   # top 3 content angles based on gaps + engagement
recommended_next_skill: string # "content-angle-ranker"

Output Format

## Trending Content Scout: [Keyword]

### Data Source
📊 **[API: YouTube Data API + RapidAPI TikTok | web_search (no API configured)]**
Scanned: [X] content pieces across [Y] platforms
Time range: [30 days]

---

### 🏆 Top Performing Content

| # | Title | Platform | Creator | Views | Eng. Score | Format | Hook |
|---|-------|----------|---------|-------|------------|--------|------|
| 1 | [Title] | YouTube | @creator | 150K | 42.3 | comparison | bold_claim |
| 2 | [Title] | TikTok | @creator | 800K | 38.1 | demo | demo_first |
| 3 | [Title] | YouTube | @creator | 95K | 35.7 | tutorial | question |
| ... | ... | ... | ... | ... | ... | ... | ... |

---

### 📈 Pattern Analysis

**Winning Formats:**
| Format | Count | % of Top 20 | Avg Engagement | Verdict |
|--------|-------|-------------|----------------|---------|
| Comparison | 9 | 45% | 35.2 | 🔥 Dominant — proven winner |
| Tutorial | 5 | 25% | 28.4 | ✅ Solid performer |
| Review | 4 | 20% | 22.1 | ⚡ Works but competitive |
| Listicle | 2 | 10% | 18.5 | ➖ Below average |

**Best Hooks:**
1. 🥇 **Bold claim** — "This tool replaced my $5K/mo agency" (avg engagement: 41.3)
2. 🥈 **Demo first** — Show end result in first 3 seconds (avg: 36.8)
3. 🥉 **Contrarian** — "Stop using X, use this instead" (avg: 33.2)

**Duration Sweet Spot:**
- TikTok: 45-60 seconds (avg engagement: 34.2)
- YouTube: 8-12 minutes (avg engagement: 31.5)

**Top Creators in This Space:**
| Creator | Platform | Pieces in Top 20 | Avg Engagement | Style |
|---------|----------|-------------------|----------------|-------|
| @creator1 | YouTube | 4 | 38.5 | In-depth comparisons |
| @creator2 | TikTok | 3 | 35.2 | Quick demos |

---

### 🕳️ Content Gaps (Opportunities)

1. **[Gap 1]:** Nobody comparing [Product A] vs [Product B] on TikTok — YouTube has 5 comparisons, TikTok has zero
2. **[Gap 2]:** No "honest cons" content — all top content is positive. Authentic negative review = differentiation
3. **[Gap 3]:** Missing "[keyword] for [specific audience]" — all content targets general audience
4. **[Gap 4]:** Top content is 4-6 months old — fresh 2024 take is an opportunity
5. **[Gap 5]:** Reddit has high engagement (avg score: 450) but no affiliate content → underserved platform

---

### 📏 Engagement Benchmark

| Metric | Median | Top 10% Threshold | Your Target |
|--------|--------|-------------------|-------------|
| Views | 12,000 | 85,000 | Beat median to start |
| Engagement Score | 18.5 | 45.0 | Aim for top 10% |

**Per Platform:**
| Platform | Median Views | Median Engagement |
|----------|-------------|-------------------|
| YouTube | 25,000 | 22.3 |
| TikTok | 45,000 | 16.8 |

---

### 🎯 Recommended Next Steps

Based on this data, the highest-opportunity path is:

1. **Run `content-angle-ranker`** — rank specific angles for [best platform]
2. **Create a [winning format]** using a [best hook] hook
   → Skill: `viral-post-writer` (format: [format], hook: [hook])
3. **Fill [Gap 1]** — this is the lowest-competition, highest-potential opportunity
   → Skill: `tiktok-script-writer` (if TikTok) or `comparison-post-writer` (if blog)

Error Handling

• No API configured: Fall back to web_search. Include note: "Data from web_search is approximate. For exact engagement metrics, configure an API provider — see shared/references/social-data-providers.md"
• API rate limited: Fall back to web_search for remaining platforms. Note which platforms used API vs web_search in output.
• No content found for keyword: The keyword may be too niche or too new.
  1. Try broadening: "[keyword]" → "[parent category]"
  2. Try removing platform filter: search across all platforms
  3. If still empty, this is itself a signal — could be a gap opportunity. Report: "No existing content found — this keyword is either too new or too niche. This could be a first-mover opportunity."
• Platform blocked/unavailable: Skip that platform, continue with others. Note: "[Platform] was unavailable. Results are from [remaining platforms] only."
• web_search returns only a few results: Present what's available. Note: "Limited data available ([X] results). Patterns may not be representative. Consider configuring an API for better coverage."
• Engagement data partially available: If only views are available (no likes/comments), sort by views and estimate engagement. Note: "Engagement scores are estimated — only view counts were available."

Examples

Example 1: User: "What content is working about HeyGen on TikTok?" → keyword: "HeyGen", platforms: ["tiktok"] → web_search "HeyGen tiktok" + "HeyGen site:tiktok.com" + "HeyGen TikTok viral" → Find 15 TikTok videos, extract view counts and creators → Pattern: demo_first hooks dominate (60%), 30-45s duration optimal → Gap: nobody doing "HeyGen for [specific profession]" content → Recommend: tiktok-script-writer with demo_first hook, 30s, angle: "HeyGen for real estate agents"

Example 2: User: "I want to create content about email marketing tools. What's performing well?" → keyword: "email marketing tools", platforms: ["youtube", "tiktok", "reddit"] → Scout all 3 platforms → YouTube: dominated by listicles ("Top 10 email marketing tools 2024") — avg 45K views → TikTok: very few results — gap opportunity → Reddit: high engagement on comparison threads in r/emailmarketing → Recommend: Fill TikTok gap with comparison format, or target Reddit with authentic discussion

Example 3: User: "Scout trending content about AI writing tools, I have RapidAPI configured" → Use configured APIs for YouTube + TikTok → Get exact engagement data: views, likes, comments, shares → Engagement scores calculated precisely → Pattern: "I replaced my copywriter with AI" hook has 3x average engagement → Output includes exact benchmark: median 18K views, top 10% needs 120K+ → Recommend: content-angle-ranker to pick best angle, then viral-post-writer

Feedback & Issue Reporting

When this skill produces unexpected, incomplete, or incorrect output, generate a skill_feedback block (see shared/references/feedback-protocol.md for full schema).

Skill-specific failure modes:

• Empty results on all platforms: Keyword too niche or all APIs/web_search returned nothing. Report as data_quality with the keyword used.
• Engagement scores all zero: Metrics unavailable — only titles retrieved. Report as data_quality, note which platforms had no metrics.
• Format/hook classification wrong: Agent classified a tutorial as a review. Report as wrong_output with the misclassified content.

Auto-detect triggers:

• top_content array has <5 items after scanning all platforms
• engagement_benchmark.sample_size < 10

• 50% of content_gaps are generic rather than specific

Report issues: GitHub Issues | Discussions

References

• shared/references/social-data-providers.md — API configuration and provider options
• shared/references/flywheel-connections.md — master flywheel connection map
• shared/references/affiliate-glossary.md — affiliate marketing terminology
• shared/references/feedback-protocol.md — issue detection and reporting standard

Flywheel Connections

Feeds Into

• content-angle-ranker (S1) — full scout output for angle scoring
• viral-post-writer (S2) — pattern_analysis (winning formats, hooks, benchmark)
• tiktok-script-writer (S2) — top TikTok content + engagement data
• twitter-thread-writer (S2) — top X threads + engagement data
• reddit-post-writer (S2) — top Reddit posts + engagement data
• content-pillar-atomizer (S2) — platform performance data for allocation
• competitor-spy (S1) — top_creators data (who's dominating this keyword)
• keyword-cluster-architect (S3) — engagement data per keyword for cluster prioritization
• affiliate-blog-builder (S3) — winning formats and gaps for blog content angles

Fed By

• competitor-spy (S1) — competitor URLs/channels to analyze specifically
• niche-opportunity-finder (S1) — niche keywords to scout
• performance-report (S6) — your content metrics to compare against benchmark

Feedback Loop

• S6 performance-report provides your actual content metrics → compare against engagement_benchmark from this skill → identify where you're beating or trailing the benchmark → refine content strategy in the next scout run

chain_metadata:
  skill_slug: "trending-content-scout"
  stage: "research"
  timestamp: string
  suggested_next:
    - "content-angle-ranker"
    - "viral-post-writer"
    - "tiktok-script-writer"