| name | youtube-seo |
| description | Advanced YouTube SEO analysis and optimization for channels and videos. Routes to specialized sub-skills for audits, single-video deep dives, metadata optimization, channel branding, keyword research, thumbnails, and competitor intel. Models YouTube's modern recommender (session watch time / Reinforce / persona matching) not just keyword match. Use when user says "YouTube SEO", "optimize my video", "rank my YouTube video", "YouTube channel audit", "YouTube keywords", or provides a YouTube URL.
|
| user-invokable | true |
| argument-hint | [channel-url | video-url | query] |
| allowed-tools | ["Read","Grep","Glob","Bash","WebFetch","Agent"] |
YouTube SEO Orchestrator (Advanced)
Master skill for YouTube SEO work. Detect intent, delegate to the right
sub-skill, and provide the shared advanced ranking model that every
sub-skill references. If intent is ambiguous, ask once before proceeding.
Routing Table
| User intent / input | Sub-skill |
|---|
| "audit my channel", channel URL alone, "full YouTube check" | youtube-seo-audit |
| Single video URL, "analyze this video", "why isn't this ranking" | youtube-seo-video |
| "optimize title/description/tags", "rewrite metadata", "improve CTR copy" | youtube-seo-optimize |
| "channel branding", "about page", "banner", "playlists", "channel trailer" | youtube-seo-channel |
| "YouTube keywords", "topic research", "what should I make a video about" | youtube-seo-keywords |
| "thumbnail review", "CTR thumbnail", "is my thumbnail good" | youtube-seo-thumbnail |
| "competitor analysis", "what are [channel] doing", "competing videos" | youtube-seo-competitor |
Advanced Ranking Model
YouTube's recommender is NOT a keyword-match system. It is a multi-surface
reinforcement-learning recommender that optimizes for long-term user
satisfaction (the "Reinforce" paper, Covington et al. 2016 + DRL updates).
Each surface has its own objective:
| Surface | Primary objective | Dominant signal |
|---|
| Browse (Home feed) | Session watch time + return rate | CTR-on-impression, persona match, freshness |
| Suggested (sidebar / autoplay) | Next-video watch time | Topical adjacency, session continuation, co-view graph |
| Search | Query satisfaction | Keyword/entity match, APV for that query, click depth |
| Shorts feed | Swipe-through rate + watch loops | Hook in <1s, loopability, audio trend |
| Notifications | Open rate in first hour | Subscriber affinity, bell-on CTR history |
| External | Retention of new viewers | Intro strength, subscribe-from-external rate |
A video can be strong on one surface and dead on others. Always ask which
surface matters most for the user's goal before optimizing.
Tier 1 — Watch-time & session signals (dominant)
- CTR by surface (Browse CTR ≠ Search CTR ≠ Suggested CTR)
- APV (Average Percentage Viewed) — the single best retention metric for
videos <20 min. Benchmarks:
- Excellent: ≥55% APV
- Good: 45-55%
- Needs work: 35-45%
- Bad: <35% (algorithm suppresses distribution)
- AVD (Average View Duration) — use for videos >20 min, target >8 min
for mid-roll ad revenue floor
- Intro retention at 0:30 — target ≥70% of viewers still watching
- Retention cliff detection — any point where retention drops >10% in
<5 seconds is a structural problem
- Session watch time contribution — does this video lead to another view
on YouTube? Studio "Suggested videos" + "Browse" outbound CTR proxy this
- Returning viewer rate — % of viewers who come back within 7/28 days
- Relative performance — vs your own channel median and vs niche median
for the same length bucket
Tier 2 — Metadata & semantic signals
- Title: 60-70 char sweet spot (mobile cutoff ~56 on small screens, ~70
on desktop). Keyword in first 40 chars for Search; emotional driver first
for Browse.
- Description:
- Above-fold (first 150 chars): restates title intent, includes
primary keyword, gives a click-for-more reason
- Full body (1,500-4,000 chars): semantic entity coverage (see below),
natural density, not stuffed
- Key Moments / chapters: first timestamp MUST be
0:00, ≥3 chapters,
each ≥10s, descriptive labels. Triggers Google Search "Key Moments"
rich result and VideoObject.hasPart[].Clip schema eligibility.
- Links block: grouped, labeled, with FTC disclosure if affiliate
- Hashtags: max 3 meaningful (shown above title); first is strongest
- Tags: de-emphasized in 2020 but still used for typo/spelling
disambiguation and topic classification. 5-15, first = exact keyword,
total <500 chars.
- Entity/semantic coverage: YouTube uses Knowledge Graph entities
(people, brands, places, concepts). Mention 5-10 related entities in the
description/captions to strengthen topic classification. Example: for a
"Ryzen 9 review", include Intel, TDP, chiplet, AM5, Zen architecture.
- Captions: manually uploaded
.srt/.vtt outrank auto-captions for
Search. Translated captions unlock international impressions.
- Translated metadata: Custom Channel Translations for top 5 viewer
languages typically lift international impressions 20-50%.
- Category: correct primary category
- Audio language tag + default language set correctly
Tier 3 — Thumbnail / pre-click signals
- 1280x720, <2MB, JPG/PNG, 16:9
- Readable at 120px wide (mobile feed) — the binding constraint
- Face + strong emotion lifts CTR ~20-30% in most niches (exceptions:
product, gaming, tutorial close-ups)
- ≤4 words text, ideally ≤3, bold sans-serif ≥80pt effective
- SERP differentiation: must pattern-break against the top-10 thumbnails
for the target keyword (CLIP-embedding or manual grid check)
- Native A/B test via Studio "Test & Compare" (3 variants, 2-week window)
- No bait-mismatch with title or content — long-term CTR decay if broken
Tier 4 — Engagement & velocity signals
- Like ratio vs channel baseline (not absolute count)
- Comment velocity in first 60 min, creator reply rate
- Pinned comment engagement (replies to pinned)
- Shares, saves-to-playlist, playlist-add events
- End-screen CTR (slots filled; hotspot 60-70% through video)
- Card CTR at attention moments
- Subscribe-from-video rate (per 1,000 views)
- Bell-notification open rate (for subscribed audience)
- First-24h velocity — for trending/topical content this is 60-80% of
lifetime distribution; for evergreen, 10-20%
Tier 5 — Channel-level signals
- Topical authority: concentration of topic clusters (YouTube classifies
channels by topic IDs inherited from Knowledge Graph)
- Upload cadence consistency: predictable rhythm feeds the Browse
surface
- Channel persona profile: who the algorithm believes watches you
- Playlist binge-ability (session chains)
- Cross-video retention (do viewers of video A also finish video B?)
- Subscriber growth slope (more signal than raw count)
- Community tab engagement (pre-upload momentum)
- Verification + monetization status
- Strike / community-guidelines standing
Tier 6 — Technical / safety signals
- Video format: 1080p minimum (4K bonus on supporting devices)
- Audio loudness: target -14 LUFS (YouTube's normalization target).
Under -16 LUFS feels quiet and correlates with lower retention.
- Duration: >8 min unlocks mid-roll ads; >10 min is the legacy watch-time
optimum; <60s (vertical) goes to Shorts feed
- Made-for-Kids flag: must match content truthfully; incorrect setting
disables engagement features and suppresses discovery
- Altered/synthetic content disclosure for AI-generated video/voice
- Copyright claims (Content ID): block/monetize/track status affects
revenue share and can cap reach
- Embedding enabled (third-party embed views count)
- Comments enabled with active moderation
Shorts-specific signals
- First 0.5-1.0s hook — swipe-away rate here is the #1 metric
- Loop rate — the video should end where it starts (narratively or
visually)
- Vertical 9:16, 1080x1920
- Caption overlay for silent viewing (most Shorts are watched muted)
- Audio trend — use trending audio from the Shorts audio library
(boost) OR original audio that can be remixed
- Title: ≤40 chars, emotional hook front-loaded
#Shorts in description or title (no longer required but still
de-risks classification)- Length: 15-30s has highest loop rate; 45-60s has highest watch time.
Pick based on goal (discovery vs watch time)
Data Sources
First-party only. These skills deliberately avoid third-party
analytics tools (VidIQ, TubeBuddy, Ahrefs, SocialBlade, NoxInfluencer,
HypeAuditor, etc.) — they rate-limit, change their HTML, or return
errors. Every source below is an official Google/YouTube endpoint, a
local CLI, or data the user provides directly.
Priority order (degrade gracefully from top to bottom):
| Source | Use | How |
|---|
| YouTube Data API v3 | Full snippet, tags, statistics, topicDetails, contentDetails, playerCaptions, commentThreads, search, channels, playlistItems | YOUTUBE_API_KEY env var + scripts/fetch_video.py / scripts/fetch_channel.py |
| YouTube Studio CSV exports (user-provided) | Real CTR, APV, retention curves, traffic sources, audience, impressions — the only source for Tier 1 signals | Ask user to export from Studio → Analytics → Advanced Mode → download CSV |
| yt-dlp | Full metadata, auto + manual captions, chapters, transcript, audio extract, ytsearch: SERP, channel playlists — works without an API key | yt-dlp --dump-json --skip-download URL, yt-dlp "ytsearch50:query" --flat-playlist -J |
| YouTube suggest API | Keyword expansion (no key, no rate limit in practice) | suggestqueries.google.com/complete/search?client=firefox&ds=yt&q={seed} |
| Google Trends (WebFetch) | Trending vs evergreen, seasonality, breakout topics | trends.google.com/trends/api/explore... |
| WebFetch on watch / channel / results page | Public title, view/like counts, upload date, visible description, SERP results — last resort, structure can change | youtube.com/results?search_query=..., youtube.com/@handle |
| Whisper (local or API) | Transcript fallback when captions unavailable | whisper --model base --language en |
| OpenCV + CLIP | Face detection, emotion, thumbnail-similarity vs SERP | scripts/analyze_thumbnail.py |
| FFmpeg / loudnorm | Audio loudness (LUFS), true peak, loudness range | ffmpeg -i IN -af loudnorm=print_format=json -f null - |
| seo-dataforseo MCP (OPTIONAL — only if explicitly available and not erroring) | Extra YouTube SERP positions and volume estimates | serp_youtube_organic_live_advanced, keywords_for_youtube — skip on any error, do not retry |
Data Source Matrix (what you need for what)
| Analysis | Minimum data | Ideal data |
|---|
| Metadata score | WebFetch only | API + Studio CSV |
| Retention diagnosis | Studio CSV | Studio CSV + transcript |
| Thumbnail score | Image URL | Image + SERP grid + CLIP embeddings |
| Competitor intel | API + WebFetch | API + yt-dlp transcripts + Studio benchmarks |
| Audio/loudness | yt-dlp audio extract | FFmpeg loudnorm pass |
If critical data is missing, ASK for it before analyzing — do not guess
Tier 1 signals.
Niche Benchmarks (APV, CTR, like ratio)
Benchmarks vary. When possible, compute live from top-10 SERP for the
target keyword. Use these as fallback medians:
| Niche | CTR (Browse) | APV (long-form) | Like/view ratio |
|---|
| Tech review | 4-8% | 40-50% | 3-5% |
| Gaming | 5-10% | 45-55% | 4-6% |
| Education / how-to | 4-7% | 40-50% | 4-6% |
| Vlog / lifestyle | 3-6% | 35-45% | 3-5% |
| Finance / business | 5-9% | 45-55% | 3-5% |
| Music / entertainment | 6-12% | 50-65% | 5-8% |
| Kids (MFK compliant) | 8-15% | 55-70% | N/A (disabled) |
| Shorts (any) | 8-20% | 80-100%+ (loops) | 5-10% |
If the user's numbers are 1.5x median, recommend scaling (more similar
content); if <0.7x median, recommend structural change.
Output Conventions (all sub-skills must follow)
- Score card (0-100) with weighted sub-scores
- Issues organized Critical → High → Medium → Low, each with an
estimated impact (CTR%, APV%, impressions%)
- Paste-ready artifacts (titles, descriptions, tags, schema) in fenced
code blocks
- Rationale block citing which Tier signal each fix targets
- Measurement plan: which Studio metric to watch after the change,
over what window, with what success threshold
Error Handling
Fail loud, degrade gracefully, never fabricate. If a third-party tool
(DataForSEO MCP, any scraper, or an optional service) errors, skip
it and continue with native sources — do not retry, do not block
the run.
| Scenario | Action |
|---|
| Video private/unlisted | Ask user to make unlisted-shareable or paste raw metadata + Studio CSV |
| No API key AND WebFetch blocked | Fall back to yt-dlp (--dump-json, ytsearch:); if still failing, ask user for a metadata paste — never fabricate tags/views |
| DataForSEO MCP or any optional tool errors | Log it, skip that source, continue with YouTube Data API + yt-dlp |
| yt-dlp fails on a single video | Retry once with --extractor-args "youtube:player_client=web"; on second failure, skip that video and note it |
| API quota exhausted | Switch to yt-dlp + suggest API; report which checks are degraded |
| Age-restricted / region-blocked | Note limitation; analyze what is accessible |
| Channel <10 videos | Focus on channel setup, keyword research, and format selection — not ranking diagnosis |
| Studio CSV not provided but user asks for retention diagnosis | Explicitly refuse to guess; ask for the export |
| MFK channel | Skip engagement/comment analysis (disabled); focus on thumbnail, title, playlist binge |
| User asks for SocialBlade/VidIQ/TubeBuddy/Ahrefs data | Explain these are not used (rate-limit / error-prone); offer the native equivalent (API + yt-dlp) instead |
