SKILL.md 26.1 KB

name: youtube-competitor-analyzer version: "1.3.0"

YouTube Competitor Analyzer

Find and analyze competitor channels using YouTube Data API v3.

Setup

  1. API Key: Get from Google Cloud Console - enable YouTube Data API v3
  2. Input: User's channel (for context) OR list of competitor channels to analyze directly
  3. Read API Key from environment: process.env.YOUTUBE_API_KEY or ask user to provide it

API Endpoints

BASE_URL = https://www.googleapis.com/youtube/v3

Search channels

GET /search?part=snippet&q={query}&type=channel&maxResults={n}&key={API_KEY}

Quota cost: 100 units per call. Use sparingly.

Channel details (batch up to 50 IDs)

GET /channels?part=snippet,statistics,contentDetails,brandingSettings&id={ids}&key={API_KEY}

Quota cost: 1 unit per call. Always batch IDs.

  • If subscriber count is hidden (hiddenSubscriberCount: true), estimate from viewCount/videoCount ratio or note as "hidden"

Get channel videos (BEST METHOD - use playlistItems)

GET /playlistItems?part=snippet&playlistId={uploadsPlaylistId}&maxResults=50&key={API_KEY}

Quota cost: 1 unit per call.

  • uploadsPlaylistId comes from channels.contentDetails.relatedPlaylists.uploads
  • Preferred over search.list(channelId=...) which costs 100 units

Alternative: Search channel videos (higher quota)

GET /search?part=snippet&channelId={id}&order=date&type=video&maxResults=50&key={API_KEY}

Quota cost: 100 units per call. Only use if uploads playlist is unavailable.

Video details (batch up to 50 IDs)

GET /videos?part=snippet,statistics,contentDetails&id={ids}&key={API_KEY}

Quota cost: 1 unit per call. Always batch IDs.

Error Handling

Code Meaning Action
400 Bad request Check parameters, retry once after fixing
403 Forbidden / quota exceeded Stop further searches, report quota status, suggest next-day retry
404 Not found Skip this channel/video, note in report
429 Too many requests Exponential backoff (wait 2s, 4s, 8s), max 3 retries
500+ Server error Retry once after 3s

Competitor Discovery Methods

Extract 3-5 core keywords from user's channel description, title, and brandingSettings.channel.keywords. Search each:

GET /search?q={keyword}&type=channel&maxResults=10

Quota cost: 100 per call. Limit to 5-8 essential keywords.

2. Content Similarity

  1. Get user's recent 20 video titles via playlistItems.list(uploadsPlaylistId) (1 unit, NOT search.list)
  2. Extract words > 4 characters, filter out stop words (the, and, for, with, etc.)
  3. Take top 5 frequent meaningful words
  4. Search channels with those terms combined: q=word1+word2+word3

Identify user's categoryId from recent videos, search for active channels in same category with similar upload volume.

Use 2-3 of user's best-performing video titles/descriptions as search queries to find channels creating similar content.

5. Direct Input

User provides specific channels: @handles, channel IDs (UC...), or URLs.

  • @handle: search q=@handle&type=channel (100 units)
  • /channel/UC...: extract ID directly
  • /c/name or /user/name: use search.list(q=name&type=channel) (100 units). Do NOT use forUsername as it only supports a small subset of legacy accounts and fails for most modern channels.

URL / Handle Parsing Decision Tree

Input Pattern Extraction Rule API Call
youtube.com/channel/UCxxxxxxxx Extract UCxxxxxxxx after /channel/ channels.list(id=UCxxx)
youtube.com/c/ChannelName Use search.list(q=ChannelName&type=channel) search.list (100 units)
youtube.com/user/Username Use search.list(q=Username&type=channel) search.list (100 units)
youtube.com/@handle Use search.list(q=@handle&type=channel) search.list (100 units)
youtu.be/any Treat as video URL; extract channel from video snippet videos.list then channels.list

Critical rule: If URL parsing fails (e.g., ambiguous short link), always fall back to search.list with the most distinctive text fragment rather than guessing IDs.

Competitor Filtering & Ranking

Step 1: Filter

Apply ALL of the following:

  • Scale relevance: abs(log10(compSubs+1) - log10(targetSubs+1)) <= 1.0 (within 10x)
  • Activity: At least 1 upload in the last 90 days
  • Content relevance: Minimum threshold (see below)
  • Language/Region match: Prefer same country and content language

Step 2: Calculate Relevance Score

// Content keyword overlap
const targetWords = extractTopWords(targetVideoTitles, 10);
const compWords = extractTopWords(compVideoTitles, 10);
const overlap = intersection(targetWords, compWords).length / union(targetWords, compWords).length;

// Description similarity (simple word overlap)
const descWords1 = targetChannel.description.toLowerCase().split(/\s+/);
const descWords2 = compChannel.description.toLowerCase().split(/\s+/);
const descOverlap = intersection(descWords1, descWords2).length / union(descWords1, descWords2).length;

relevanceScore = overlap * 0.6 + descOverlap * 0.4;

Minimum threshold: relevanceScore >= 0.3

Step 3: Size Similarity

sizeSimilarity = 1 - Math.abs(Math.log10(compSubs+1) - Math.log10(targetSubs+1)) / 10;
// If hiddenSubscriberCount, use estimatedSubscribers or default sizeSimilarity = 0.5

Step 4: Overall Score

overallScore = sizeSimilarity * 0.3 + relevanceScore * 0.7;

Sort descending. Return top 10-15 competitors.

Boundary Handling

Scenario Handling
videoCount == 0 viewsPerVideo = 0; note "no videos published"
hiddenSubscriberCount == true Note "subscriber count hidden"; use views/video as proxy for scale
viewCount == 0 Engagement rate = 0%; flag as new/inactive channel
Missing brandingSettings.channel.keywords Skip keyword extraction, rely on description only
Empty search results Broaden query by removing 1 modifier word, retry once

Comparative Analysis

For each competitor, extract and compute:

Metric Description Formula/Source
Subscribers Direct count statistics.subscriberCount
Total Views Channel lifetime views statistics.viewCount
Video Count Total videos published statistics.videoCount
Views/Video Average performance viewCount / max(videoCount, 1)
Upload Frequency Videos per month Count uploads in last 90 days / 3
Channel Age Days since creation Date.now() - new Date(publishedAt)
Engagement Rate Likes + Comments per video / views videos.statistics aggregated

Compare user channel vs competitor averages:

  • Above/below average positioning for each metric
  • Growth rate comparison (if historical data available)
  • Content volume gaps

Subscriber Growth Estimation

YouTube API does not provide historical subscriber data. To estimate growth:

  1. Method A (Preferred): If you have access to historical snapshots, compare current vs past subscriberCount
  2. Method B (Proxy): Compare recent 90-day viewCount velocity vs older periods. Faster view growth often correlates with subscriber growth
  3. Method C (Labeling): Always mark subscriber growth figures as "estimated" or "inferred" when not from direct historical data
  4. Transparency: State clearly in reports: "Subscriber growth is estimated based on view velocity and content frequency trends because YouTube API does not expose historical subscriber data."

Content Gap Analysis

  1. Topic Coverage: List topics covered by top 3 competitors but absent from user's recent uploads
  2. Duration Preferences: Compare average video duration. Identify if user is over/under-indexed
  3. Upload Schedule: Find low-competition time slots based on competitor publish times
  4. Title/Thumbnail Patterns: Note high-performing patterns (numbers, questions, how-to formats)
  5. High-Performing Topics: Identify which competitor topics have the highest views/video

Industry Benchmarks (Reference Context)

Use these benchmarks when interpreting competitor data and generating insights:

Channel Size Tiers

Tier Subscribers Characteristics
Micro Early stage, high volatility
Small 1K - 10K Seed audience, high growth potential
Medium 10K - 100K Stable output, niche authority
Large 100K - 1M Commercial maturity, brand strength
Mega > 1M Industry leader, resource moat

Engagement Rate Benchmarks (2024-2025)

Subscribers Views/Sub Ratio Like Rate Comment Rate
25-40% 4-8% 0.3-0.8%
10K-100K 15-25% 3-6% 0.2-0.5%
100K-1M 10-15% 2-4% 0.1-0.3%
> 1M 5-10% 1-3% 0.05-0.15%

Upload Frequency Classification

  • High frequency: >= 4 videos/week (news/hot topics)
  • Medium frequency: 1-3 videos/week (education/tutorials)
  • Low frequency:

Insight Generation Rules

DO NOT just list data. Every comparison must lead to an actionable insight. Use this framework:

Observation → Interpretation → Recommendation

Examples:

  • Bad: "Competitor A has 100K subscribers." ❌
  • Good: "Competitor A (100K subs) publishes 2x/week with 15-min tutorials, achieving 50K views/video. Given your similar niche, increasing upload frequency from 1x to 2x/week could close the views/video gap within 3 months." ✅

For each recommendation, include:

  • What: The specific action
  • Why: Data point supporting it
  • How: Measurable next step with a timeframe and quantified target whenever possible

Quantification Rule: Every recommendation MUST include at least ONE of: a percentage target, a deadline, a count, or a comparison threshold. Vague recommendations like "post more often" are FAILING. Transform them into "increase posting frequency from 1x/week to 2x/week for the next 30 days".

Insight Template Library

Use these templates as starting points for common competitive scenarios. Each template includes trigger conditions:

Template 1: Views/Video Higher But Frequency Lower

  • Trigger: Competitor's views/video > 1.5x user's, AND competitor's upload frequency
  • Output: "Competitor X achieves {X} views/video ({ratio}x your rate) while publishing only {freq}x/week vs your {target_freq}x/week. This suggests their content quality or SEO optimization drives disproportionate returns. Rather than matching their volume, prioritize improving thumbnail CTR and title keyword density to capture similar per-video performance. Target: Increase average views/video by 20% within 60 days through A/B testing 5 new title formats."

Template 2: Similar Size But Faster Growth

  • Trigger: User and competitor within same size tier, but competitor shows stronger view/sub momentum
  • Output: "Both you and Competitor X are in the {tier} tier (~{subs} subs), but their upload frequency ({freq}/week) and topic coverage ({topics} distinct themes) exceed yours ({target_freq}/week, {target_topics} themes). Growth attribution points to consistency + breadth. Short-term goal: Add 1 new content pillar per month and increase frequency by 20% over the next 90 days."

Template 3: Engagement Rate Gap

  • Trigger: User's engagement rate 2 percentage points
  • Output: "Your engagement rate ({rate}%) is below the {tier} benchmark ({benchmark}%). Competitor X achieves {x_rate}% through {observed tactic}. Action: Add an end-screen CTA and pinned comment in your next 5 videos; target lifting engagement rate to {benchmark}% within 60 days."

Template 4: Content Gap Opportunity

  • Trigger: Top 3 competitor topics are absent from user's catalog AND those topics show > avg views/video
  • Output: "Topics A, B, and C represent {pct}% of Competitor X's top-performing videos but are absent from your catalog. Based on their average {avg_views} views/video, entering this sub-niche could add an estimated {projected_views} monthly views. Action: Produce 1 video on Topic A within 2 weeks and track first-7-day performance against your current average."

Template 5: Upload Schedule Gap

  • Trigger: >= 60% of competitor uploads cluster on 1-2 specific days
  • Output: "Competitors cluster uploads on {days}, leaving {low_competition_days} relatively open. Publishing on {low_competition_days} could reduce direct competition in subscriber feeds. Action: Test shifting 1 video per week to {low_competition_day} for 4 weeks and measure early-view velocity (first 48h)."

Mini-Insights for Technical Requests

Even when the user asks a purely technical question (discover, filter, API sequence), add 1 sentence of strategic context at the end:

  • Discover requests: After listing found channels, add "These channels were selected because they match your scale tier and show {X}% content overlap."
  • Filter requests: After presenting the filtered list, add "The top {N} channels were retained based on {primary criterion}, which is the strongest predictor of competitive relevance."
  • API requests: After showing the sequence, add "This sequence uses {N} units; if quota is tight, you can replace Step X with {alternative} to save {saved} units."
  • Metric requests: After showing the calculation, add "In context, a score of {value} indicates {interpretation} relative to the {tier} tier benchmark."

Discover Response Format (for discover/filter requests)

When the user asks to "find competitors" or "analyze a @handle/URL," use this compact structure:

## Discovered Competitors for {Target}
| Channel | Subs | Relevance | Why Selected |
|---------|------|-----------|--------------|
| ...     | ...  | ...       | ...          |

**Discovery method**: {method}
**Strategic note**: {1-sentence mini-insight}

Metric Interpretation Example

When calculating sizeSimilarity or views/video, always interpret the result:

Calculation: sizeSimilarity = 1 - |log10(100,001) - log10(50,001)| / 10 = 0.97 Interpretation: These channels are in the same size tier (Small/Medium boundary), making them highly comparable.

Calculation: views/video = 8,000,000 / 200 = 40,000 Interpretation: This is strong for the Medium tier (benchmark ~15-25K views/video), indicating above-average content efficiency.

Pre-Execution Checklist

Before generating ANY output, verify:

  • [ ] Divide-by-zero protected: viewsPerVideo = viewCount / max(videoCount, 1)
  • [ ] Quota-aware: Have I stated or respected the API unit budget?
  • [ ] Insightful: Does every comparison lead to an actionable recommendation?
  • [ ] Quantified: Do recommendations include numbers, percentages, or deadlines?
  • [ ] Structured: Does the report (if any) follow the 7-section standard format?
  • [ ] Transparent: Are estimated/growth figures clearly labeled as inferred?
  • [ ] Table-valid: Are markdown tables properly formatted with separators?

Competitive Positioning Matrix

When generating reports, include a 2D positioning analysis. Choose the most relevant matrix based on data availability:

Matrix A: Scale vs Efficiency

  • X-axis: subscriberCount (log scale)
  • Y-axis: views/video
  • Plot user + top 5 competitors
  • Interpretation: Channels above the diagonal achieve higher efficiency per video than their size predicts

Matrix B: Volume vs Engagement

  • X-axis: Upload frequency (videos/month)
  • Y-axis: Engagement rate (%)
  • Plot user + top 5 competitors
  • Interpretation: The "high-volume + high-engagement" quadrant represents the most defensible position

Output Report Structure (MUST FOLLOW)

# Competitive Analysis Report: {Target Channel}

## Executive Summary
- {N} competitors analyzed across {timeframe}
- Key finding 1: {highest-level insight}
- Key finding 2: {strategic positioning}
- Key finding 3: {immediate opportunity}

## Competitor Discovery
- Methods used: {list}
- Initial pool: {N} channels → Final selection: {M} channels
- Selection criteria applied: scale within 10x, relevance score ≥ 0.3, active within 90 days

## Competitor Overview
| Channel | Subs | Videos | Views | Views/Video | Uploads/Mo | Score |
|---------|------|--------|-------|-------------|------------|-------|
| ...     | ...  | ...    | ...   | ...         | ...        | ...   |

## Competitive Positioning
- Your subscribers: {X} (vs avg {Y}: {diff}%)
- Your views/video: {X} (vs avg {Y}: {diff}%)
- Your upload frequency: {X} (vs avg {Y})
- Market position: {assessment}

### Positioning Matrix
{Describe the 2D matrix and user's position relative to competitors}

## Content Strategy Comparison
- What top competitors do differently:
  1. ...
  2. ...
- Common patterns among top performers:
  - ...

## Content Gaps & Opportunities
- Gap 1: {topic} — Opportunity: {specific action}
- Gap 2: {duration/format} — Opportunity: {specific action}
- Gap 3: {schedule/timing} — Opportunity: {specific action}

## Recommendations (Prioritized)
1. **{High priority}** — {What} | {Why} | {Next step with timeframe + quantified target}
2. **{Medium priority}** — {What} | {Why} | {Next step with timeframe + quantified target}
3. **{Low priority}** — {What} | {Why} | {Next step with timeframe + quantified target}

## Quota Usage
- Total API units consumed: {N}/10,000
- Breakdown: search={N}, channels={N}, videos={N}, playlistItems={N}

Markdown Table Format Rules

  • Use standard GFM table syntax with | delimiters
  • Header row must have | on both left and right edges
  • Separator row |---|---| is required
  • Right-align numeric columns by NOT centering; left-align text columns
  • Keep column widths consistent; truncate long channel names with ... if necessary

Niche-Specific Search Terms

For yoga/wellness channels:

yoga, meditation, mindfulness, spiritual, consciousness, wellness, self-help, awakening, breathwork

For spiritual/wellness channels:

meditation, mindfulness, yoga, spiritual, consciousness, wellness, self-help, awakening

For tech channels:

tech review, unboxing, tutorial, how to, comparison, tips, gadget

For gaming:

gameplay, let's play, walkthrough, gaming, stream, esports

For education:

tutorial, course, learn, explained, guide, tips, masterclass

Quota Optimization & Management

YouTube Data API v3 default daily quota: 10,000 units

Operation Quota Cost Optimization Rule
search.list 100 Limit strictly. Max 5-8 keywords in discovery phase
channels.list 1 Always batch (max 50 IDs per call)
videos.list 1 Always batch (max 50 IDs per call)
playlistItems.list 1 Always prefer over search.list for getting a channel's videos
Phase Budget (units) Calls
Discovery 500-800 5-8 search.list calls
Channel details 100-200 1-2 batch channels.list
Video details 500-1000 1-2 batch videos.list + 2-5 playlistItems.list
Buffer 20% reserve —

Dynamic Quota Downgrade Strategy

If remaining quota is constrained, follow this decision tree:

Tier 1: Quota > 5,000 (Normal)

  • Full analysis: 5-8 keywords discovery, top 15 competitors, 50 recent videos

Tier 2: Quota 2,000-5,000 (Reduced)

  • Discovery: 3-5 keywords, top 10 competitors
  • Reduce video analysis depth to 20 videos per competitor
  • Skip non-core positioning matrices

Tier 3: Quota

  • Discovery: 2-3 keywords OR skip discovery if user provided direct channel list
  • Analyze top 5 competitors only
  • Video analysis limited to 10 most recent videos
  • Focus on high-level metrics only; skip deep SEO and title pattern analysis
  • Generate condensed 1-page report

Quota Response Format (when user asks about remaining quota)

## Quota Status
- **Remaining**: {N}/10,000 units ({pct}%)
- **Analysis level available**: {Full / Reduced / Minimal}
- **Recommended scope**: {scope description}
- **Breakdown of what we can do**:
  - Discovery: {N} units → {description}
  - Channel details: {N} units → {description}
  - Video analysis: {N} units → {description}

API Sequence Response Format (when user asks for API call sequences)

Present the sequence as a numbered list with HTTP details:

### Step 1: {Action}

GET /{endpoint}?{params}&key={API_KEY}

**Cost**: {N} units | **Returns**: {description}

### Step 2: {Action}

GET /{endpoint}?{params}&key={API_KEY}

**Cost**: {N} units | **Returns**: {description}

Always include a "Total cost" line at the end of the sequence.

Low-Quota Working Example (1,500 units remaining)

If the user says "I have 1,500 units left," respond with this exact plan:

## Quota Status
- **Remaining**: 1,500/10,000 units (15%)
- **Analysis level available**: Minimal
- **Recommended scope**: Top 5 competitors with 10-video snapshot analysis
- **Breakdown of what we can do**:
  - Discovery: 200 units → 2 targeted search.list calls (skip if you already gave me channels)
  - Channel details: 10 units → batch channels.list for up to 5 IDs
  - Video basics: 50 units → playlistItems.list for 10 recent videos per competitor
  - Deep metrics: 50 units → batch videos.list for engagement data
  - Report generation: 0 units (local formatting)
  - **Reserve**: 1,190 units for retries and follow-up questions

Enhanced Insight Framework (v1.3)

Strategic Insight Ladder

Every insight must climb this ladder from data to strategy:

Raw Data → Pattern Recognition → Strategic Meaning → Actionable Recommendation

Example Ladder:

  1. Raw Data: Competitor X has 100K subs, 2 videos/week, 50K views/video
  2. Pattern: Their views/sub ratio (50%) is 2x your rate (25%)
  3. Strategic Meaning: They achieve higher content efficiency through quality over quantity
  4. Actionable Recommendation: Reduce frequency from 4x/week to 2x/week, reinvest time in thumbnail/title optimization. Target: Match their 50% views/sub ratio within 90 days.

Quantified Recommendation Formula

Every recommendation MUST follow this formula:

Action + Metric + Target + Deadline

Quality Example
❌ Poor "Post more engaging content"
⚠️ Okay "Post more videos to grow faster"
✅ Good "Increase upload frequency by 50% (from 2x/week to 3x/week) to close the 35% views/sub gap with Competitor X within 60 days"
🌟 Excellent "Shift 2 videos/week to Tuesday/Thursday slots (low-competition windows identified) + A/B test 5 new title formats to increase CTR from 4.2% to 6% within 30 days"

Context-Aware Insight Templates

Template 6: Cross-Tier Benchmarking

  • Trigger: User's metrics significantly differ from tier benchmarks
  • Output: "Your views/video ({actual}) is {pct}% {above/below} the {tier} tier benchmark ({benchmark}). This {suggests opportunity/indicates underperformance} because {reasoning}. Action: {specific steps to align with or exceed benchmark}. Timeline: {deadline}."

Template 7: Engagement Efficiency Gap

  • Trigger: Competitor has lower subscriber count but higher engagement per video
  • Output: "Despite having {X}% fewer subscribers, Competitor X achieves {Y}% higher engagement per video through {observed tactics: pinned comments, end screens, community posts}. Your engagement efficiency is {Z}% below tier average. Recommendation: Implement {specific tactic} in your next {N} videos. Target: Lift engagement rate from {current}% to {target}% within {timeframe}."

Template 8: Content Velocity Opportunity

  • Trigger: Competitor uploads 3x+ more frequently but maintains quality
  • Output: "Competitor X publishes {freq}x/week vs your {target_freq}x/week while maintaining {quality_metric}. Their content velocity correlates with {growth_metric}. Gap Analysis: Your production pipeline likely has {bottleneck: editing/thumbnails/research} bottlenecks. Action: Batch-produce {N} videos in a single session to build a {days}-day buffer. Target: Increase frequency by {pct}% within {timeframe} without quality degradation."

Automated Insight Triggers

Apply these rules automatically to generate insights without user prompting:

Data Pattern Auto-Generated Insight
views/video > 1.5x tier median "Above-average content efficiency detected. Analyze title/thumbnail patterns for replication."
upload frequency < 1/week AND subs > 10K "Quality-focused channel model. Consider premium/long-form content strategy."
engagement rate > 2x tier average "High community loyalty. Leverage with community posts and memberships."
subscriber growth > 20% MoM "Momentum channel identified. Study recent viral content for pattern replication."
title contains numbers AND views > avg "Listicle format performing. Test similar formats: '7 Ways to...', '3 Mistakes...'"

Insight Quality Checklist

Before delivering any insight, verify:

  • [ ] Specificity: Does it name exact numbers, percentages, or timeframes?
  • [ ] Context: Does it reference tier benchmarks or competitor comparisons?
  • [ ] Causality: Does it explain WHY the pattern matters (not just WHAT)?
  • [ ] Actionability: Can the user act on this within 7 days?
  • [ ] Measurability: Is there a clear metric to track success?
  • [ ] Realism: Is the target achievable given the user's current resources?