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`).
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`).
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:
A title SET — 2-3 titles, never one. (Why: YouTube tests titles, so you
ship a hypothesis to measure, not a guess to defend.)
A description block — above-the-fold line + body + links + hashtag line.
A tag list — 5-8 tags, first = exact target phrase.
A hashtag line — 3-5 hashtags inside the description.
A chapter list — timestamps that obey four exact rules.
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 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).
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:
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):
| 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:
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 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 — the image the title sits on; the pair is tested together.
