--- name: video_seo description: Optimize a video for discovery on YouTube and Google. Use when packaging a new upload, auditing an existing video's metadata, or fixing weak search/suggested performance. Covers keyword research, titles, descriptions, tags and hashtags, chapters, thumbnails with Test & Compare, and the retention signals that decide whether the algorithm keeps pushing the video. --- # Video SEO ## Purpose Get a video found and clicked, then keep viewers watching long enough that YouTube keeps recommending it. Metadata (title, description, tags, chapters) gets you into search results. CTR (title plus thumbnail) and retention (watch time, average percentage viewed) decide whether you stay there. One without the other fails. ## Workflow ### 1. Keyword research Pick one primary keyword phrase per video. Sources, in order of reliability: YouTube search autocomplete for the query (the suggestions are real searches), YouTube Analytics "Reach" tab traffic sources showing what already brings impressions, and competitor tags via a vidIQ/TubeBuddy-style inspector. Long-tail beats broad: a new channel cannot win "fitness" but can win "kettlebell swing form for beginners". ### 2. Title Formula: primary keyword in the first 60 characters, then a curiosity or value promise. Under 60 characters so it is never truncated in search or the feed. Pattern: `Keyword: Specific Benefit [Context]`. Example: `Sourdough Starter Day 1: The Foolproof Method [No Waste]`. Never keyword-stuff the title; one exact phrase is enough. See `references/title-description-templates.md` for patterns that fit different video types. ### 3. Description Write 200-500 words for long-form, at least 150. Structure, in order: 1. First 125 characters: the hook, with the primary keyword. This shows above "Show more" and in search snippets. 2. One-paragraph summary using the keyword 2-3 times naturally plus related terms. 3. Chapter list (see step 5). 4. Links (subscribe, related videos, resources) and a call to action. 5. 3-5 hashtags at the very end. The first 3 display above the title. Never more than 15 hashtags in total, or YouTube ignores all of them. ### 4. Tags and captions Add 10-15 tags: exact primary keyword first, then variations, long-tail phrases, and the channel name. Tags matter less than they used to (they have been de-emphasized since 2018) but still help YouTube disambiguate, especially for niche topics. Never stuff unrelated popular tags; it trips spam filters. Upload a manual caption file or correct the auto-captions. Accurate transcripts give YouTube more text to index and match against queries. ### 5. Chapters Chapter timestamps feed Google search key moments and let viewers jump to what they need, which protects retention on long videos. Rules are hard, from YouTube Help: - The first timestamp must start at `00:00`. - At least 3 timestamps, in ascending order. - Every chapter at least 10 seconds long. - The list lives in the DESCRIPTION. Pinned comments and captions do not count. - A manual list overrides YouTube's automatic chapters, so write it yourself when the section names matter. - Format: `mm:ss Title` for videos under an hour, `hh:mm:ss Title` over an hour. Name chapters with real search phrases when the section is a standalone answer (e.g. `04:12 Feeding schedule: day 3 to 7`), not cutesy labels. - Full rules and format checks: `references/chapters.md`. ### 6. Thumbnail The thumbnail plus title is the click decision. Specs from YouTube: 1280x720 px, 16:9, minimum 640 px width, JPG/PNG/GIF/BMP, under 2 MB. Design for the phone feed, not the editor canvas: most discovery thumbnails render at roughly 168x94 in suggested and ~320x180 on mobile. Keep overlay text to 3-5 words in a bold font with a stroke or shadow so it survives the squint test. High contrast against YouTube's white/dark chrome. Keep the bottom-right corner clear, the duration stamp sits there. Faces with real emotion raise engagement but never fake the video's content: a misleading thumbnail buys a click and loses the retention that matters. Title and thumbnail together make one honest promise; they should not repeat each other word for word. Full spec and safe-zone diagram: `references/thumbnail-spec.md`. ### 7. Test & Compare For any video that earns real impressions, run YouTube Studio's Test & Compare with up to 3 thumbnail variants. The winner is chosen by watch time share, NOT by CTR alone, so a high-CTR bait variant can lose. Let it run 2 days to 2 weeks until impressions are meaningful. Vary exactly one axis per round (emotion, text, background) so the result teaches something reusable. Titles can also be tested the same way. ### 8. Retention signals that matter In Studio Analytics, watch these, not raw view counts: - **Average percentage viewed (APV).** Roughly: 50-60% is solid, 70%+ earns suggested-feed priority, under 40% gets deprioritized. (Practitioner consensus, 2025 sources; YouTube confirms APV and average view duration inform ranking.) - **Average view duration (AVD).** Total watch time divided by views. A 6-minute video at 80% retention beats a 20-minute video at 30% despite less raw watch time. - **The first 30 seconds.** The retention graph's steepest drop is almost always here; typically more than half of viewers leave within the first minute. No logo sting, no "welcome back". Open on the title's promise, restated in your own voice, then raise the stakes. If the 0:15-0:30 segment dips, re-cut the opening before touching anything later. - **Spikes and dips** in the retention graph show rewatched moments (make more of those) and abandonment points (tighten those). - **Shorts.** Aim for 70%+ average view duration; loopable endings can push AVD over 100%. Since March 2025 YouTube counts "engaged views" (viewers who actively chose to watch) as the primary Shorts metric, so thumbnail/title choice matters even in the swipe feed. - You cannot fix weak retention on an already-published video by re-uploading the content, but you can re-target: a new title and thumbnail attract a better-matched audience, which lifts retention on future views. ### 9. Validate before publishing Run the checker against the full metadata package before upload: ``` python3 ~/workspace/skills/video-seo/bin/video-seo-check.py --package package.json ``` It verifies title length and keyword placement, description length and keyword presence, hashtag count, chapter rule compliance, and thumbnail file specs. Fix every failure it reports. Exit code 0 means the package passes; non-zero lists the failures. ## Output Contract When asked to package a video, return: (1) 3 title options with the primary keyword marked, (2) the full description text ready to paste, (3) the tag list, (4) the chapter list if the video has sections, (5) thumbnail art direction notes or a brief a designer can execute, (6) the retention metrics to watch in the first week. Also return the `package.json` the video-seo-check script validates, so the metadata is machine-checked, not eyeballed. ## Operating Rules 1. Every factual claim about platform behavior must trace to YouTube Help, Creator documentation, or a documented study. Never invent thresholds, dimensions, or limits. When a number comes from practitioner consensus rather than YouTube, say so. 2. One primary keyword per video. If the user hands you a topic without a keyword, do the research step first. 3. Chapters are checked, not assumed. Run the validator before shipping a chapter list. 4. The thumbnail and title make one promise and the first 30 seconds must keep it. Call out any mismatch you see. 5. Do not claim a video will rank. You can say the packaging is optimized; ranking depends on the competition and the retention the content earns. 6. Follow Anthony's style law in all generated text: no em dashes, no AI filler phrasing. Plain, direct, varied rhythm.