youtube-packaging

# YouTube packaging You write the text that ships with the upload — title, description, tags, hashtags, chapters — and you optimize it against what actually performed, not against a hunch. A strong video dies on a weak package. You are not the picture, not the idea, not the channel plan, and not the API that uploads any of it. ## What you produce Five concrete text artifacts plus one feedback entry, every time: 1. **A title SET** — 2-3 titles, never one. (Why: YouTube tests titles, so you ship a hypothesis to measure, not a guess to defend.) 2. **A description block** — above-the-fold line + body + links + hashtag line. 3. **A tag list** — 5-8 tags, first = exact target phrase. 4. **A hashtag line** — 3-5 hashtags inside the description. 5. **A chapter list** — timestamps that obey four exact rules. 6. **A feedback-log update** in `02-DOCS` — what you tried, what won, the numbers. **Co-ownership note, up front:** YouTube tests the title+thumbnail pair as ONE unit. The *title hypothesis to test* is co-owned with [youtube-thumbnails](../youtube-thumbnails/SKILL.md); the **wordsmithing of the title and all other metadata lives here**. Draw the image there, write the words here. ## Ground first (STOP gate) Before you write a single title, read the channel. Skipping this is how you produce generic copy in someone else's voice. - Read `02-DOCS/wiki/youtube/` for the channel's **brand voice**, prior packages, and the **performance feedback log** (winners and losers from past tests). - Pull the decided **idea/angle** from [youtube-ideation](../youtube-ideation/SKILL.md) output if it exists. - **No decided topic/angle yet? Route OUT to `youtube-ideation`. Never invent the topic here.** (Why: packaging a video with no settled angle is guessing at the hook, the keyword, and the audience all at once.) Persist what you write under `02-DOCS/wiki/youtube/` (the package) and raw test results under `02-DOCS/raw/youtube/`. `02-DOCS/wiki/` is an **OKF v0.1** bundle: every package or log file persisted there carries YAML frontmatter with a non-empty `type` (`youtube-package`) plus the OKF surface (`title`, `description`, `tags`, `timestamp`) shared with the strategy/thumbnail/api siblings, and all cross-references use standard markdown links — never `[[wikilinks]]`. The OKF frontmatter shape for the persisted package and log is in [references/description-and-chapters.md](references/description-and-chapters.md). ## The title The single highest-leverage field. Rules, each with one reason: - **Hard limit 100 chars; visible budget ~60.** Titles truncate around 60-70 chars on desktop and ~50-60 on mobile. The most compelling words + the primary keyword must land in the first ~60 chars / first 5 words — everything after that may never be seen. - **Front-load the keyword and the hook.** Shape: Hook + Keyword + Benefit inside the first 60 chars. Channels report 15-25% higher CTR for titles kept in the 60-70 char range. - **Use numbers and specificity.** Titles with numbers report ~20-30% higher CTR; a parenthetical qualifier (year, difficulty, format) adds precision without burning the budget. - **Emit a SET of 2-3 titles framed as an A/B hypothesis** — never ship one. Test & Compare auto-applies the variant with the highest *watched time per impression*, **not raw CTR**. (Why this matters: a clickbait title that wins the click but loses the viewer will LOSE the test. Write for the click AND the stay.) Bad -> Good (front-load, cut the filler, add specificity): ```text Bad In this video I'll show you how to learn Python Good Learn Python in 2026: 12-Minute Beginner Tutorial Bad My honest thoughts after using the new framework for a while Good I Shipped 3 Apps on This Framework — Here's the Verdict Bad Tips for better sleep that actually work I promise Good 7 Sleep Fixes That Doubled My Deep Sleep (No Pills) ``` Decide the title shape by how the video will be found — this is a real branch: | Discovery mode | Title shape | Example | |---|---|---| | Search-led (tutorial, how-to, "best X") | Keyword first, literal, benefit-clear | `Fix Slow Next.js Builds: 5 Proven Steps` | | Browse-led (commentary, vlog, story) | Curiosity/stakes first, keyword secondary | `I Rebuilt My App and Regretted Everything` | Search-led titles answer a query; browse-led titles win a scroll. Most videos lean one way — pick it deliberately, then write the set inside that shape. ## The description Only the first ~125 chars are above the fold — the rest hides behind "Show more" and is unseen by most viewers. - **First 1-2 lines (~100-150 chars): primary keyword + who-it's-for.** This is the one part that shows in search and the watch page before the fold. Spend it on substance, not "Welcome to my channel." - **Body: ~200-350 words of natural, keyword-rich prose. No stuffing.** Write for a human; weave the keyword and 1-2 variants in naturally. Keyword lists read as spam and help nothing. - **Links block** (resources, socials, gear) then the **3-5 hashtag line**. - **One clear CTA** (subscribe / next video / comment prompt). The full template + a fully filled example live in [references/description-and-chapters.md](references/description-and-chapters.md). ## Chapters Chapters obey **four exact rules. Break any one and YouTube ignores ALL chapters.** Run this checklist on every chapter block: - [ ] **At least 3 timestamps.** - [ ] **The first timestamp is `00:00`.** (This is the silent killer — omit `0:00` and every later timestamp is discarded.) - [ ] **Each chapter is at least 10 seconds long.** - [ ] **Timestamps are in ascending order.** Compliant block: ```text 00:00 Intro — what you'll build 00:42 Installing the tools 03:15 Writing your first function 07:50 Debugging the common error 11:20 Recap & next steps ``` Why bother: chapters lift watch time and give search a jump-to target. The four failure cases worked through line by line are in [references/description-and-chapters.md](references/description-and-chapters.md). ## Tags & hashtags Different fields, different rules — and one of them barely matters: | Field | Count | Placement | Weight | |---|---|---|---| | Tags | 5-8 (up to 10-20), ~500-char budget | the Tags input box | **minimal ranking impact**; first tag weighted slightly more | | Hashtags | 3-5 relevant; **max 15** | inside the description | first 3 render above the title; **>15 = ALL stripped** | - **Tags: make the first tag the exact target phrase; do not over-invest.** YouTube calls tags' discovery role "minimal" — they mainly fix misspellings and disambiguate. Spend 2 minutes here, not 20. - **Hashtags: pick 3-5 relevant ones; never exceed 15.** Only the first three show above the title, so order them best-first. Exceed 15 and YouTube strips every hashtag — you get zero, not 15. ## The learning loop This is what makes the skill *learn* instead of guess. Because Test & Compare measures variant performance directly, every package is logged and graded. **Read before you write.** Open the feedback log in `02-DOCS/wiki/youtube/` and carry forward what won as priors: if numeric titles beat curiosity titles 3 tests running on this channel, the new set leans numeric. If a hashtag set tanked, drop it. **Append after you test.** One row per test, into `02-DOCS/wiki/youtube/packaging-log.md` (OKF v0.1: file-level `type: youtube-package` frontmatter at the top, the table below it, newest rows appended, past rows immutable): ```text | date | video | title set tried | winner | CTR | impressions | avg view duration | note | ``` The cycle: read winners/losers -> write the new package as informed priors -> ship the A/B set -> when Test & Compare resolves (~2 weeks), append the result -> the next package is a little less of a guess. The full schema with a filled row is in [references/description-and-chapters.md](references/description-and-chapters.md). **Grade by watched-time-per-impression, not raw CTR.** A title can win clicks and still lose the test by losing viewers. Log both so the lesson is honest. ## Handoffs Stay inside the text fields. Everything else routes out: | Ask | Owner | |---|---| | Design/generate the thumbnail image | [youtube-thumbnails](../youtube-thumbnails/SKILL.md) | | Come up with the idea / topic / angle | [youtube-ideation](../youtube-ideation/SKILL.md) | | Channel growth plan, niche, cadence | [youtube-strategy](../youtube-strategy/SKILL.md) | | Upload/update metadata via the Data API | [youtube-api](../youtube-api/SKILL.md) | | Cross-platform short caption/hook (TikTok/Reels) | [video-shorts](../video-shorts/SKILL.md) | | Keyword research for web/AI search (not YouTube) | [seo-geo](../seo-geo/SKILL.md) | | Schedule/publish the post to socials | [social-publisher](../social-publisher/SKILL.md) | The tell: if the ask is **the text fields of the YouTube upload**, it is here. The picture, the idea, the channel plan, the API call — each is a sibling. ## Anti-patterns | Anti-pattern | Why it fails | Do instead | |---|---|---| | "In this video I'll show you…" opener | Burns the visible ~60-char budget on filler | Front-load keyword + hook in the first 5 words | | Shipping ONE title | No hypothesis, nothing to learn | Always a SET of 2-3 for Test & Compare | | Keyword-stuffing the description | Reads as spam, helps nothing | ~200-350 words of natural prose, keyword woven in | | Clickbait the video can't cash | Wins the click, loses the viewer, LOSES the A/B | Promise what the video delivers | | Chapters with no `00:00` / <3 / <10s / out of order | YouTube silently ignores ALL chapters | Run the four-rule checklist | | >15 hashtags | YouTube strips every one — you get zero | 3-5 relevant, best three first | | Obsessing over tags | They have minimal ranking impact | 5-8, first = target phrase, move on | | Ignoring the feedback log | Every package stays a fresh guess | Read prior winners, carry them as priors | | Optimizing CTR while view duration tanks | Test & Compare scores watched-time-per-impression | Log both; write for click AND stay | ## Verify Run [scripts/verify.sh](scripts/verify.sh) on an emitted package file (the title set, description, tags, hashtags, and chapters as one structured block). It is read-only and lints the mechanical constraints: ≥2 titles, each ≤100 chars; above-the-fold first line present and not over-long; ≥3 chapters with first `0:00`, ascending, ≥10s gaps; 1-15 hashtags; tags within the ~500-char budget. A clean or empty file exits 0. ## See also - [youtube-thumbnails](../youtube-thumbnails/SKILL.md) — the image the title sits on; the pair is tested together. - [youtube-ideation](../youtube-ideation/SKILL.md) — the idea/angle you package here. - [youtube-strategy](../youtube-strategy/SKILL.md) — channel positioning, niche, cadence. - [youtube-api](../youtube-api/SKILL.md) — programmatic upload/update of these fields.