agentleFS
deeployCOdeeployCO/youtube-seo-skills/youtube-seo/SKILL.md

youtube-seo

Skill9 starsChanged 7 months agoMITView on GitHub

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.

  • Reads credentials

We split this skill into the rules it gives an agent

5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search. Translated captions unlock international impressions.

    line 102
  2. Distinctive:

    SERP differentiation: must pattern-break against the top-10 thumbnails for the target keyword (CLIP-embedding or manual grid check)

    line 115
  3. Distinctive:

    Made-for-Kids flag: must match content truthfully.

    line 154
  4. Distinctive:

    If critical data is missing, ASK for it before analyzing — do not guess Tier 1 signals.

    line 210
  5. Distinctive:

    If the user's numbers are 1.5x median, recommend scaling (more similar content).

    line 229

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 / inputSub-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:

SurfacePrimary objectiveDominant signal
Browse (Home feed)Session watch time + return rateCTR-on-impression, persona match, freshness
Suggested (sidebar / autoplay)Next-video watch timeTopical adjacency, session continuation, co-view graph
SearchQuery satisfactionKeyword/entity match, APV for that query, click depth
Shorts feedSwipe-through rate + watch loopsHook in <1s, loopability, audio trend
NotificationsOpen rate in first hourSubscriber affinity, bell-on CTR history
ExternalRetention of new viewersIntro 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):

SourceUseHow
YouTube Data API v3Full snippet, tags, statistics, topicDetails, contentDetails, playerCaptions, commentThreads, search, channels, playlistItemsYOUTUBE_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 signalsAsk user to export from Studio → Analytics → Advanced Mode → download CSV
yt-dlpFull metadata, auto + manual captions, chapters, transcript, audio extract, ytsearch: SERP, channel playlists — works without an API keyyt-dlp --dump-json --skip-download URL, yt-dlp "ytsearch50:query" --flat-playlist -J
YouTube suggest APIKeyword 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 topicstrends.google.com/trends/api/explore...
WebFetch on watch / channel / results pagePublic title, view/like counts, upload date, visible description, SERP results — last resort, structure can changeyoutube.com/results?search_query=..., youtube.com/@handle
Whisper (local or API)Transcript fallback when captions unavailablewhisper --model base --language en
OpenCV + CLIPFace detection, emotion, thumbnail-similarity vs SERPscripts/analyze_thumbnail.py
FFmpeg / loudnormAudio loudness (LUFS), true peak, loudness rangeffmpeg -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 estimatesserp_youtube_organic_live_advanced, keywords_for_youtube — skip on any error, do not retry

Data Source Matrix (what you need for what)

AnalysisMinimum dataIdeal data
Metadata scoreWebFetch onlyAPI + Studio CSV
Retention diagnosisStudio CSVStudio CSV + transcript
Thumbnail scoreImage URLImage + SERP grid + CLIP embeddings
Competitor intelAPI + WebFetchAPI + yt-dlp transcripts + Studio benchmarks
Audio/loudnessyt-dlp audio extractFFmpeg 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:

NicheCTR (Browse)APV (long-form)Like/view ratio
Tech review4-8%40-50%3-5%
Gaming5-10%45-55%4-6%
Education / how-to4-7%40-50%4-6%
Vlog / lifestyle3-6%35-45%3-5%
Finance / business5-9%45-55%3-5%
Music / entertainment6-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)

  1. Score card (0-100) with weighted sub-scores
  2. Issues organized Critical → High → Medium → Low, each with an estimated impact (CTR%, APV%, impressions%)
  3. Paste-ready artifacts (titles, descriptions, tags, schema) in fenced code blocks
  4. Rationale block citing which Tier signal each fix targets
  5. 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.

ScenarioAction
Video private/unlistedAsk user to make unlisted-shareable or paste raw metadata + Studio CSV
No API key AND WebFetch blockedFall 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 errorsLog it, skip that source, continue with YouTube Data API + yt-dlp
yt-dlp fails on a single videoRetry once with --extractor-args "youtube:player_client=web"; on second failure, skip that video and note it
API quota exhaustedSwitch to yt-dlp + suggest API; report which checks are degraded
Age-restricted / region-blockedNote limitation; analyze what is accessible
Channel <10 videosFocus on channel setup, keyword research, and format selection — not ranking diagnosis
Studio CSV not provided but user asks for retention diagnosisExplicitly refuse to guess; ask for the export
MFK channelSkip engagement/comment analysis (disabled); focus on thumbnail, title, playlist binge
User asks for SocialBlade/VidIQ/TubeBuddy/Ahrefs dataExplain these are not used (rate-limit / error-prone); offer the native equivalent (API + yt-dlp) instead

Download now (ZIP)

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. kostja94/marketing-skills★ 1.1ksame name
    2. AlekseiUL/sprut-agent-kit★ 66same name
    3. dalroot/agentic-seo★ 23same name
    4. jsath/claude-skills★ 14same name
    5. aya-taleb/multimedia-skills★ 1same name
    6. donatassimkus/claude-ai-skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use local-seo.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • huiferSkill

      local-seo

      本地 SEO 分析和优化专家。自动检测项目是否需要本地 SEO,分析 NAP(Name, Address, Phone)一致性、本地关键词优化、Google Business Profile (GBP) 优化和本地结构化数据生成。提供本地商家搜索引擎排名优化建议,包括 NAP 标准化、本地关键词策略、GBP 完整性检查、评论策略、地图嵌入和本地 SEO 审计。

      Also in 3 projects that use this

  • In this repository7 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.