rsc-universal 0.1.1

package/skills/youtube-ideation/scripts/verify.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for the `youtube-ideation` idea ledger + outcome log.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a produced idea ledger (Markdown). It validates the SHAPE of
+#   the decision, never whether the ideas are good. For each ledger found:
+#     1. Every scored idea row (a table row with seven 1-5 cells) has all 7 rubric
+#        dimensions filled 1-5 AND a /35 total that equals their sum.
+#     2. The /35 total matches its verdict band:
+#          >=30 produce | 24-29 improve | 18-23 gray | <18 abandon
+#        A mismatch (e.g. total 31 tagged "abandon") fails; the 18-23 gray band warns.
+#     3. Every "produce" idea has demand evidence on the row (non-empty Evidence).
+#     4. If a hypothesis/outcome log section is present, it is append-only-shaped:
+#        each dated bet is either "status: pending" OR carries actual + a verdict of
+#        validated|killed|inconclusive + a lesson. A bet that is neither fails.
+#
+#   A missing/empty target is a SKIP, never a failure. Pure text/awk, no deps.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *ledger*/*idea*.md
+#   ./verify.sh --path ledger.md     # check one ledger
+#   ./verify.sh --path 02-DOCS/      # scan a directory
+#   ./verify.sh --strict             # treat warnings (gray-band rows) as failures
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (bad row, band mismatch, broken hypothesis/outcome shape)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)   SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+summary() { printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"; }
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%s[skip]%s path not found: %s — nothing to check\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  printf '%s[skip]%s awk not found — cannot parse ledger\n' "$YELLOW" "$NC"
+  skip_count=1; summary; exit 0
+fi
+
+# Collect candidate ledger files: prefer named ledger/idea files, else any .md.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.md' \( -iname '*ledger*' -o -iname '*idea*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.md' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  printf '%s[skip]%s no idea ledger found under %s — nothing to check (clean)\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+# check_one <file>: one awk pass emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { printf 'SKIP empty file: %s\n' "$f"; return; }
+  printf 'HDR %s\n' "$f"
+
+  awk '
+    # Lowercase compare; BSD awk has no IGNORECASE.
+    {
+      line=$0
+      lc=tolower($0)
+
+      # ---- scored idea rows: a markdown table row with >=7 integer cells (1-5) ----
+      # Heuristic: pipe-delimited row, not the header/separator, that contains a
+      # verdict word AND a standalone /35-style total. We split on | and read cells.
+      # separator row = only pipes, dashes, colons and spaces (no letters/digits)
+      issep = (line ~ /^[ ]*\|[ |:-]*$/)
+      if (line ~ /\|/ && !issep && (lc ~ /produce|improve|abandon|gray|grey/)) {
+        n=split(line, c, "|")
+        ints=0; sum=0; total=""; verdict=""; firstint=""
+        for (i=1;i<=n;i++) {
+          cell=c[i]; gsub(/[ \t*]/,"",cell)
+          if (cell ~ /^[1-5]$/) { ints++; sum+=cell+0; if(firstint=="") firstint=cell+0 }
+          else if (cell ~ /^[0-9]+$/ && (cell+0)>=0 && (cell+0)<=35) { total=cell+0 }
+          lcell=tolower(cell)
+          if (lcell ~ /^produce$/)  verdict="produce"
+          if (lcell ~ /^improve$/)  verdict="improve"
+          if (lcell ~ /^abandon$/)  verdict="abandon"
+          if (lcell ~ /^gr[ae]y$/)  verdict="gray"
+        }
+        if (verdict=="") next   # not actually an idea row
+        rows++
+
+        # A leading "#" index column is itself a 1-5 integer; if we counted 8, the
+        # first is the row index, not a rubric dimension — drop it from the sum.
+        if (ints == 8) { ints=7; sum=sum-firstint }
+
+        if (ints < 7) {
+          print "FAIL row " rows ": only " ints " of 7 rubric dimensions are integers 1-5"
+          next
+        }
+        if (ints > 7) {
+          print "FAIL row " rows ": " ints " integer cells 1-5 — expected exactly 7 rubric dimensions"
+          next
+        }
+        if (total=="") {
+          print "FAIL row " rows ": no /35 total cell found"
+          next
+        }
+        if (total != sum) {
+          print "FAIL row " rows ": total " total " != sum of dimensions " sum
+        } else {
+          print "OK row " rows ": 7 dims, total " total " matches sum"
+        }
+
+        # band check against verdict
+        band=""
+        if (total>=30) band="produce"
+        else if (total>=24) band="improve"
+        else if (total>=18) band="gray"
+        else band="abandon"
+        if (band != verdict)
+          print "FAIL row " rows ": total " total " is band \"" band "\" but verdict is \"" verdict "\""
+        else if (verdict=="gray")
+          print "WARN row " rows ": gray band (" total ") — re-angle or shelve, do not produce as-is"
+        else
+          print "OK row " rows ": verdict \"" verdict "\" matches band"
+
+        # produce rows need demand evidence somewhere on the row
+        if (verdict=="produce") {
+          producerows++
+          # crude evidence test: an outlier multiple like 3.4x or a digit-bearing note
+          if (lc ~ /[0-9]+(\.[0-9]+)?x/ || lc ~ /outlier|trends|autocomplete|search/) {
+            # ok
+          } else {
+            print "WARN row " rows ": produce idea has no visible demand evidence (outlier/search) on its row"
+          }
+        }
+      }
+
+      # ---- hypothesis/outcome log shape ----
+      # A dated bet header: "## YYYY-MM-DD — <idea>"
+      if (line ~ /^#+[ ]+(19|20)[0-9][0-9]-[0-1][0-9]-[0-3][0-9]/) {
+        # close out the previous bet before opening a new one
+        if (inbet) closebet()
+        inbet=1; bettitle=$0; haspending=0; hasactual=0; hasverdict=0; haslesson=0
+        bets++
+      }
+      else if (inbet) {
+        if (lc ~ /status:[ ]*pending/) haspending=1
+        if (lc ~ /actual:/) hasactual=1
+        if (lc ~ /verdict:[ ]*(validated|killed|inconclusive)/) hasverdict=1
+        if (lc ~ /lesson:/) haslesson=1
+        # a non-date top-level heading also closes the bet
+        if (line ~ /^#[ ]/ && line !~ /(19|20)[0-9][0-9]-/) { closebet(); inbet=0 }
+      }
+    }
+    function closebet() {
+      if (haspending) { print "OK bet pending: " substr(bettitle,1,60); return }
+      if (hasactual && hasverdict && haslesson) { print "OK bet closed (actual+verdict+lesson): " substr(bettitle,1,60); return }
+      m=""
+      if (!hasactual)  m=m" actual"
+      if (!hasverdict) m=m" verdict(validated|killed|inconclusive)"
+      if (!haslesson)  m=m" lesson"
+      print "FAIL bet neither pending nor complete — missing:" m " :: " substr(bettitle,1,60)
+    }
+    END {
+      if (inbet) closebet()
+      if (rows==0) print "WARN no scored idea rows detected (is this an idea ledger?)"
+      if (rows>0)  print "OK " rows " scored idea row(s) parsed; " producerows " promoted to produce"
+      if (bets>0)  print "OK " bets " hypothesis/outcome bet(s) parsed"
+    }
+  ' "$f" 2>/dev/null
+}
+
+printf 'Checking idea ledgers under: %s\n\n' "$SCAN_PATH"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > "/tmp/ytid_verify.$$" 2>&1 || true
+
+# Render with colored tags.
+while IFS= read -r line; do
+  case "$line" in
+    HDR*)  printf '%s—— %s%s\n' "$YELLOW" "${line#HDR }" "$NC" ;;
+    FAIL*) printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL }" ;;
+    WARN*) printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN }" ;;
+    OK*)   printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK }" ;;
+    SKIP*) printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "${line#SKIP }" ;;
+    *)     printf '%s\n' "$line" ;;
+  esac
+done < "/tmp/ytid_verify.$$"
+
+tally() { { grep -c "$1" "/tmp/ytid_verify.$$" 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '^FAIL'); fail_count=${fail_count:-0}
+warn_count=$(tally '^WARN'); warn_count=${warn_count:-0}
+ok_count=$(tally '^OK');     ok_count=${ok_count:-0}
+skip_count=$(tally '^SKIP'); skip_count=${skip_count:-0}
+rm -f "/tmp/ytid_verify.$$" 2>/dev/null || true
+
+summary
+
+cat <<'EOF'
+
+Note: this gate proves the ledger is SHAPED RIGHT (7 dims sum to a /35 that matches its
+verdict band, produce rows carry demand evidence, and every logged bet is pending or fully
+graded). It does NOT judge whether the ideas are good — that is the capability eval's job.
+Re-run with --strict to gate CI on a clean pass (gray-band rows then fail).
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/youtube-packaging/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: youtube-packaging
+description: "Use when writing or fixing the text that ships with a YouTube upload — title, description, tags, hashtags, chapters — or when click-through is weak and the words are the suspect, or when closing the loop on what last performed. Triggers: 'write the title and description for this video', 'give me 3 titles to A/B test', 'add chapters to my description', 'what tags and hashtags should I use', the non-obvious 'my CTR is terrible and the title isn't landing, fix it' and 'log how the last upload performed and apply it to the next package', plus Spanish/Catalan 'escríbeme el título y la descripción del vídeo' / 'afegeix capítols a la descripció i dona'm 3 títols per testejar'. NOT designing the thumbnail image (that is youtube-thumbnails), NOT inventing the idea/angle (youtube-ideation), NOT the channel growth plan (youtube-strategy), NOT pushing the fields via the Data API (youtube-api)."
+tags: [youtube, video-seo, titles, descriptions, chapters]
+recommends: [youtube-thumbnails, youtube-ideation, youtube-strategy, youtube-api, video-shorts, seo-geo, social-publisher]
+profiles: []
+origin: risco
+---
+
+# 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/`.
+
+## 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:
+
+```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.

package/skills/youtube-packaging/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — youtube-packaging
+
+These cases are read by the repo's skill-eval harness. `should_trigger` and
+`should_not_trigger` check routing precision: each prompt is matched against this
+skill's description versus its siblings, and the `route_to` ids
+(`youtube-thumbnails`, `youtube-ideation`, `youtube-api`, `youtube-strategy`,
+`seo-geo`) must win their own cases — the thumbnail, the idea, the API call, the
+channel plan, and non-YouTube SEO all belong elsewhere. The `capability` case is
+scored by a judge against its `must_include` rubric: it checks that a generated
+package grounds in `02-DOCS` first, emits a 2-3 title A/B set within the char
+budget, an above-the-fold description line plus a natural ~200-350 word body and a
+3-5 hashtag line, chapters obeying all four rules, 5-8 tags with the right first
+tag, a feedback-log update, correct handoffs, and the watched-time-per-impression
+framing. Run them through the repo's eval runner; no live YouTube account, upload,
+or network access is required — the capability run is a dry-run producing text
+artifacts and a feedback-log row only.

package/skills/youtube-packaging/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: youtube-packaging
+
+should_trigger:
+  - prompt: "Write the title and description for my new tutorial video."
+    why: Core packaging ask — the text fields of the upload.
+  - prompt: "Give me 3 title options to A/B test for this video."
+    why: Title SET / Test & Compare hypothesis, the signature output rule.
+  - prompt: "Add chapters with timestamps to my video description."
+    why: Chapters mechanics — the four exact rules live here.
+  - prompt: "My video's CTR is terrible and the title just isn't landing — fix it."
+    why: Non-obvious — a CTR complaint with no 'title/description' keyword leading; the rescue case for the words on the upload.
+  - prompt: "Log how the last upload performed and apply the lesson to the next package."
+    why: Non-obvious — the learning loop, reading the 02-DOCS feedback log and carrying winners forward.
+  - prompt: "Escríbeme el título, la descripció i els hashtags del vídeo i afegeix capítols."
+    why: Catalan/Spanish — full metadata write (title, description, hashtags, chapters).
+
+should_not_trigger:
+  - prompt: "Design a thumbnail image for this video."
+    route_to: youtube-thumbnails
+    why: The picture, not the text fields — co-owned hypothesis but image work is the sibling's.
+  - prompt: "What video should I make next? Give me ideas for my channel."
+    route_to: youtube-ideation
+    why: The idea/angle, which packaging consumes but never invents.
+  - prompt: "Programmatically update the title and description via the YouTube Data API."
+    route_to: youtube-api
+    why: The API call/plumbing, not the copy.
+  - prompt: "Build my channel growth plan and posting cadence."
+    route_to: youtube-strategy
+    why: Channel-level strategy, not a single video's metadata.
+  - prompt: "Do keyword research for our website blog so it ranks on Google."
+    route_to: seo-geo
+    why: Non-YouTube web/AI-search SEO, a different surface entirely.
+
+capability:
+  - scenario: >
+      Here is a video: a 12-minute beginner Python tutorial. The channel's last 5
+      uploads are logged in 02-DOCS with their title sets, CTR, and avg view
+      duration. Package this upload.
+    must_include:
+      - "Grounds in 02-DOCS first: reads the channel brand voice and the feedback log, and carries a prior winner forward into the new set."
+      - "Emits a SET of 2-3 titles framed as an A/B hypothesis, each ≤100 chars with the keyword + hook in the first ~60 chars / first 5 words."
+      - "Above-the-fold description first line ≤ ~150 chars containing the primary keyword + who-it's-for."
+      - "Full description ~200-350 words of natural prose (no keyword stuffing), plus a links block and a 3-5 hashtag line."
+      - "Chapters obey all four rules: ≥3 timestamps, first is 00:00, each ≥10s, ascending order."
+      - "5-8 tags with the first tag = the exact target phrase, and notes tags' minimal ranking impact."
+      - "Appends/updates a feedback-log entry in 02-DOCS for this package."
+      - "Routes the thumbnail image to youtube-thumbnails, the idea to youtube-ideation, and any API upload to youtube-api."
+      - "States that the A/B winner is chosen by watched-time-per-impression, not raw CTR."

package/skills/youtube-packaging/references/description-and-chapters.md

@@ -0,0 +1,135 @@
+# Description, chapters & feedback-log formats
+
+Offloaded depth for [../SKILL.md](../SKILL.md). Three things live here: the full
+description template with a filled example, the chapter format spec with the four
+failure cases worked through, and the feedback-log entry schema with a filled row.
+
+## 1. Description template
+
+Structure every description in this order. Only the first ~125 chars are
+above-the-fold, so the first line carries the keyword and the audience.
+
+```text
+<ABOVE-FOLD LINE: primary keyword + who-it's-for, ~100-150 chars max>
+
+<BODY: 2-4 short paragraphs, ~200-350 words total. Natural prose. Weave the
+primary keyword + 1-2 variants in once each. Say what the video covers and the
+payoff. No keyword lists.>
+
+🔗 Resources
+- <link 1>
+- <link 2>
+
+▶️ Watch next: <link to a relevant video>
+
+👉 Subscribe for <one concrete promise>
+
+#hashtag1 #hashtag2 #hashtag3
+```
+
+### Filled example (12-minute beginner Python tutorial)
+
+```text
+Learn Python from scratch in 2026 — a 12-minute beginner tutorial that takes you
+from zero to your first working program, no prior coding needed.
+
+In this beginner Python tutorial you'll install Python, write your first function,
+and fix the error every newcomer hits. By the end you'll have a small program
+running on your own machine and a clear path to the next step. I keep the jargon
+out and the typing in — you build alongside me the whole way. If you've bounced off
+Python before because tutorials moved too fast, this one is paced for a true
+beginner.
+
+🔗 Resources
+- Starter code: https://example.com/python-starter
+- Free cheat sheet: https://example.com/python-cheatsheet
+
+▶️ Watch next: Python Projects for Beginners — https://example.com/next
+
+👉 Subscribe for one beginner-friendly coding tutorial every week.
+
+#Python #LearnToCode #ProgrammingForBeginners
+```
+
+The above-fold line is 132 characters — under the ~150 ceiling, keyword
+("Learn Python") first, audience ("beginner") explicit. The body is ~150 words of
+natural prose (scale to 200-350 for a longer video). Exactly 3 hashtags, all shown
+above the title.
+
+## 2. Chapter format spec
+
+Four rules, all enforced by YouTube. Break ANY one and every chapter is ignored.
+
+1. **≥ 3 timestamps.**
+2. **First timestamp is `00:00`.**
+3. **Each chapter ≥ 10 seconds long.**
+4. **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
+```
+
+### The four failure cases
+
+```text
+# FAIL 1 — no 00:00 first (the silent killer): ALL chapters ignored
+00:42 Installing the tools
+03:15 Writing your first function
+07:50 Debugging
+Fix: add a 00:00 first line.
+
+# FAIL 2 — only 2 timestamps: below the 3 minimum, chapters do not render
+00:00 Intro
+05:00 Outro
+Fix: add at least one more chapter.
+
+# FAIL 3 — a chapter shorter than 10s: 00:05 -> 00:11 is only 6s
+00:00 Intro
+00:05 Setup
+00:11 Demo
+Fix: no two adjacent timestamps closer than 10 seconds.
+
+# FAIL 4 — out of order: 03:15 precedes 00:42
+00:00 Intro
+03:15 Demo
+00:42 Setup
+Fix: sort ascending.
+```
+
+Use `M:SS` or `MM:SS`; for videos over an hour use `H:MM:SS`. Each chapter title
+should be short and scannable — it doubles as a search jump-to target.
+
+## 3. Feedback-log entry schema
+
+One markdown table in `02-DOCS/wiki/youtube/packaging-log.md`. One row per A/B
+test, appended when Test & Compare resolves (~2 weeks).
+
+| Column | Meaning |
+|---|---|
+| `date` | resolution date of the test (YYYY-MM-DD) |
+| `video` | video title slug or ID |
+| `title set tried` | the 2-3 titles entered into Test & Compare, `\|`-separated |
+| `winner` | which title YouTube auto-applied |
+| `CTR` | click-through rate of the winner (%) |
+| `impressions` | impressions over the test window |
+| `avg view duration` | average view duration (mm:ss) — the retention half |
+| `note` | the transferable lesson (the pattern, not the data point) |
+
+Filled row:
+
+```text
+| date | video | title set tried | winner | CTR | impressions | avg view duration | note |
+|------|-------|-----------------|--------|-----|-------------|-------------------|------|
+| 2026-05-28 | python-beginner-tut | Learn Python in 2026: 12-Min Beginner Tutorial \| Python in 12 Minutes (Total Beginner) \| I Taught a Beginner Python in 12 Min | Learn Python in 2026: 12-Min Beginner Tutorial | 7.8% | 41,200 | 04:31 | Numeric + year title beat curiosity title again (3rd time) — keep leading with the number on tutorials |
+```
+
+The `note` column is the point: it turns one data row into a prior the next
+package carries forward. Always grade the winner by watched-time-per-impression
+(reflected in CTR *and* avg view duration together), never CTR alone — a high-CTR /
+low-duration row is a warning, not a win.