Skip to content

ericrisco/rsc-harness / skills/youtube-packaging

youtube-packaging

Verified

Use when writing or fixing the text that ships with a YouTube upload — title, description, tags, hashtags and chapters — when click-through is weak and the words are the suspect, or when closing the loop on what last performed. NOT designing the thumbnail image (that is `youtube-thumbnails`), NOT inventing the idea or angle (that is `youtube-ideation`), NOT the channel growth plan (that is `youtube-strategy`), NOT pushing the fields via the Data API (that is `youtube-api`).

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; 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 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.

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):

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 modeTitle shapeExample
Search-led (tutorial, how-to, "best X")Keyword first, literal, benefit-clearFix Slow Next.js Builds: 5 Proven Steps
Browse-led (commentary, vlog, story)Curiosity/stakes first, keyword secondaryI 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.

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:

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.

Tags & hashtags

Different fields, different rules — and one of them barely matters:

FieldCountPlacementWeight
Tags5-8 (up to 10-20), ~500-char budgetthe Tags input boxminimal ranking impact; first tag weighted slightly more
Hashtags3-5 relevant; max 15inside the descriptionfirst 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):

| 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.

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:

AskOwner
Design/generate the thumbnail imageyoutube-thumbnails
Come up with the idea / topic / angleyoutube-ideation
Channel growth plan, niche, cadenceyoutube-strategy
Upload/update metadata via the Data APIyoutube-api
Cross-platform short caption/hook (TikTok/Reels)video-shorts
Keyword research for web/AI search (not YouTube)seo-geo
Schedule/publish the post to socialssocial-publisher

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-patternWhy it failsDo instead
"In this video I'll show you…" openerBurns the visible ~60-char budget on fillerFront-load keyword + hook in the first 5 words
Shipping ONE titleNo hypothesis, nothing to learnAlways a SET of 2-3 for Test & Compare
Keyword-stuffing the descriptionReads as spam, helps nothing~200-350 words of natural prose, keyword woven in
Clickbait the video can't cashWins the click, loses the viewer, LOSES the A/BPromise what the video delivers
Chapters with no 00:00 / <3 / <10s / out of orderYouTube silently ignores ALL chaptersRun the four-rule checklist
>15 hashtagsYouTube strips every one — you get zero3-5 relevant, best three first
Obsessing over tagsThey have minimal ranking impact5-8, first = target phrase, move on
Ignoring the feedback logEvery package stays a fresh guessRead prior winners, carry them as priors
Optimizing CTR while view duration tanksTest & Compare scores watched-time-per-impressionLog both; write for click AND stay

Verify

Run 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

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall