rsc-universal 0.1.1

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

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for a youtube-strategy wiki under 02-DOCS/wiki/youtube/.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free checks on the decision records the skill writes back.
+#     1. The target directory exists.
+#     2. At least one decision record is present: a file under decisions/*.md
+#        OR a running decisions.md log at the target root.
+#     3. Each decision record carries the three required signals:
+#          - a date            (a YYYY-MM-DD anywhere in the file)
+#          - a Decision: line   (the concrete choice)
+#          - a named metric/bet (a "Bets on metric:" / "metric" / "bet" field)
+#        A record missing the metric/bet field is a HARD FAILURE — a decision with
+#        no metric is an opinion, not a checkable bet.
+#
+#   Missing date or Decision line is also a hard failure. A missing/empty target
+#   (a fresh channel with no wiki yet) is reported and exits 0 — no false failure.
+#   Pure bash + grep, no dependencies. It is a lint, not a strategy oracle.
+#
+# HOW TO RUN
+#   ./verify.sh 02-DOCS/wiki/youtube/    # lint a channel's strategy wiki
+#   ./verify.sh                          # no target -> nothing to check, exit 0
+#
+# EXIT CODES
+#   0  clean, or nothing to check
+#   1  a hard structural failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2.
+
+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; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,34p' "$0" | sed 's/^# \{0,1\}//'; }
+
+summary_exit() {
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  [ "$fail_count" -gt 0 ] && exit 1
+  exit 0
+}
+
+# --- arg parse --------------------------------------------------------------
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown flag: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+# No target, or missing dir -> nothing to check, clean exit (no false fail).
+if [ -z "$TARGET" ]; then
+  ok "no wiki path given — nothing to lint"
+  summary_exit
+fi
+if [ ! -d "$TARGET" ]; then
+  warn "directory not found: $TARGET — nothing to lint (fresh channel?)"
+  summary_exit
+fi
+ok "wiki directory exists: $TARGET"
+
+# --- collect decision records ----------------------------------------------
+# Per-decision files under decisions/, plus an optional running decisions.md log.
+RECORDS=""
+if [ -d "$TARGET/decisions" ]; then
+  for f in "$TARGET"/decisions/*.md; do
+    [ -f "$f" ] && RECORDS="$RECORDS$f
+"
+  done
+fi
+[ -f "$TARGET/decisions.md" ] && RECORDS="$RECORDS$TARGET/decisions.md
+"
+
+# Trim trailing newline / handle empty.
+RECORDS="$(printf '%s' "$RECORDS" | sed '/^$/d')"
+
+if [ -z "$RECORDS" ]; then
+  warn "no decision records yet (decisions/*.md or decisions.md) — nothing to lint"
+  summary_exit
+fi
+
+# --- per-record structural checks ------------------------------------------
+DATE_RE='[0-9]{4}-[0-9]{2}-[0-9]{2}'
+
+while IFS= read -r rec; do
+  [ -z "$rec" ] && continue
+  if [ ! -s "$rec" ]; then
+    fail "$rec: empty record"
+    continue
+  fi
+
+  miss=""
+  grep -Eq "$DATE_RE"                    "$rec" || miss="$miss date"
+  grep -Eiq '^[[:space:]-]*Decision:'    "$rec" || miss="$miss decision-line"
+  grep -Eiq '(bets on metric:|metric|bet:)' "$rec" || miss="$miss metric/bet"
+
+  if [ -n "$miss" ]; then
+    fail "$rec: missing required field(s):$miss"
+  else
+    ok "$rec: date + decision + metric present"
+  fi
+done <<EOF
+$RECORDS
+EOF
+
+summary_exit

package/skills/youtube-thumbnails/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: youtube-thumbnails
+description: "Use when designing or fixing a YouTube thumbnail, making variants for a thumbnail A/B test, or figuring out which thumbnail style wins on a channel. Triggers: 'design a thumbnail', 'make 3 thumbnail variants to A/B test', 'set up Test & Compare on this upload', 'why is my CTR low', the non-obvious 'CTR is fine but the test keeps picking the boring thumbnail' (the watch-time-share trap), 'which thumbnail style actually wins on my channel', and Catalan/Spanish 'fes la miniatura del vídeo' / 'diseña la portada del vídeo'. NOT pairing the title with the thumbnail as one click-promise (that is youtube-packaging), NOT channel positioning or niche (youtube-strategy), NOT setting a thumbnail through the Data API (youtube-api)."
+tags: [youtube, thumbnails, ctr, ab-testing, design]
+recommends: [youtube-packaging, youtube-strategy, ab-testing, design]
+profiles: []
+origin: risco
+---
+
+# YouTube thumbnails
+
+Design thumbnails that survive the mobile feed, test them so the winner is a
+*lesson* and not a coin flip, and write every outcome back to the channel's wiki
+so the next thumbnail is evidence-led. A thumbnail you cannot learn from is half
+wasted.
+
+## The loop
+
+This skill runs a closed loop, not a one-off design pass:
+
+1. **Design** 2-3 candidate concepts that differ on exactly ONE testable axis.
+2. **Test** them in YouTube Studio "Test & Compare".
+3. **Log** the outcome to `02-DOCS/wiki/youtube/thumbnail-experiments.md`.
+4. **Learn**: mine the log into `thumbnail-patterns.md` (what wins on THIS
+   channel) and let that pick the next concept.
+
+The reason for the discipline: Test & Compare hands you a winner, never a reason.
+One varied axis per round is what turns a winner into a transferable rule.
+
+## Hard constraints
+
+These are objective and machine-checkable. `scripts/verify.sh` enforces the image
+ones; the rest are your job. Source facts: socialrails.com / thumbnailtest.com
+specs, accessed 2026-06-02.
+
+| Constraint | Value | Why |
+|---|---|---|
+| Resolution | 1280x720 px | YouTube's recommended size; anything smaller upscales soft |
+| Aspect ratio | 16:9 | The only ratio that fills the player and feed cleanly |
+| Min width | 640 px | Below this YouTube may reject the upload |
+| File size | under 2 MB | Hard cap for standard video (10 MB only for podcast thumbnails) |
+| Format | JPG or PNG | Also accepts GIF/BMP, but ship JPG/PNG |
+| Legibility | reads at 320x180 | Most discovery is the mobile feed at ~that scale — the "squint test" |
+| Safe zone | clear bottom-right | The duration stamp overlays that corner — no critical text/face/logo there |
+
+The squint test: shrink the image to 320x180 (or step back two meters from the
+screen). If the subject and any text are not instantly readable, it fails — design
+for the feed, not for the editor canvas. See
+`references/composition-and-specs.md` for the contrast math and export workflow.
+
+## Composition rules
+
+Each rule, one reason. Concrete beats abstract.
+
+- **One dominant focal point.** The eye must land in under a second; a thumbnail
+  with two competing subjects reads as none at 320x180.
+- **A face with one strong emotion** when the video allows it. Faces with clear
+  emotion lift CTR roughly 20-30%, and custom thumbnails run ~60-70% higher CTR
+  than auto-generated frames. One emotion, not a neutral stare.
+- **Subject ~30% brighter or darker than its background.** Separation is what
+  makes the subject pop in a scroll; a subject the same luminance as the bg
+  vanishes. Add a subtle outline or glow if the background is busy.
+- **2-3 bold colors, complementary.** More than three and the image turns to mud
+  at feed scale. Target a text/background contrast ratio of about 4.5:1 (a
+  usability heuristic, not a YouTube rule).
+- **Kill motion blur and clutter.** Anything that softens or crowds the frame dies
+  first when the image shrinks.
+
+## Text rules
+
+- **3-4 words maximum, maximum weight.** Heavy bold sans, large enough to read at
+  320x180. If it needs a second line of small type, cut it.
+- **Never in the bottom-right.** That is the duration-stamp safe zone.
+- **The thumbnail text must NOT just repeat the title.** They are two surfaces of
+  one promise, so make them add up instead of echo.
+
+Bad -> Good (text that wastes the surface):
+
+```text
+Bad   title: "I built a PC in 24 hours"   thumb text: "BUILT A PC IN 24H"
+Good  title: "I built a PC in 24 hours"   thumb text: "$200 BUDGET?!"
+```
+
+The Bad version spends both surfaces on the same words. The Good version lets the
+thumbnail carry the stakes the title leaves implicit. The *full* title<->thumbnail
+promise pairing — which surface owns which half of the hook — belongs to
+[youtube-packaging](../youtube-packaging/SKILL.md). Here, just don't duplicate.
+
+## Variant design for the A/B test
+
+This is where the flow branches, so decide deliberately.
+
+**Vary exactly ONE axis per variant set.** Change face vs object AND text AND
+color at once and a winning variant teaches you nothing — you cannot attribute the
+lift. Pick one axis from the menu and hold everything else constant.
+
+| Axis | Variant A | Variant B | What a win tells you |
+|---|---|---|---|
+| Subject | human face | the object/result | does your audience click people or things |
+| Expression | shock | calm/confident | which emotion this niche rewards |
+| Text | text present | no text | whether words help or clutter here |
+| Color | warm dominant | cool dominant | the channel's palette pull |
+| Layout | subject left | subject right | reading-order fit |
+| Zoom | tight crop | wide context | intimacy vs setting |
+
+Two variants is enough to isolate one axis cleanly; use the third slot only when a
+third level of the SAME axis is genuinely informative.
+
+## Test & Compare procedure
+
+YouTube's native A/B tool (broad rollout 2025). In Studio: open the video ->
+Thumbnail -> "Test & Compare" -> add variants.
+
+- **Up to 3 thumbnails** (and/or titles) per video.
+- **Winner is chosen by watch-time share, NOT raw CTR.** This is the trap that
+  breaks intuition: a punchy over-promising thumbnail can win the click and still
+  *lose* the test because the viewers it lured bounce, dragging watch time down.
+- **Runs up to ~2 weeks**, then YouTube auto-promotes the winner.
+- Let it reach significance — don't call it after two days of noise.
+
+The over-promise trap is the seam to [youtube-packaging](../youtube-packaging/SKILL.md):
+if your tests keep crowning the "boring" variant, the flashy one is writing a check
+the video doesn't cash. That is a promise problem, not an image problem.
+
+## The feedback loop (wiki)
+
+Every test result goes to the channel wiki. Exact path:
+`02-DOCS/wiki/youtube/`.
+
+**Log file** — `thumbnail-experiments.md`, one row per test:
+
+```text
+| date | video | variants | axis tested | winner | CTR | watch-time share | note |
+```
+
+**Derived file** — `thumbnail-patterns.md`, a running table of what wins on THIS
+channel (e.g. "faces beat objects 4/5 tests", "no-text wins on tutorials"). You
+update this after each logged test.
+
+**Next-concept rule:** the next thumbnail keeps the winning level of every axis
+already settled by the log, and tests the next unsettled axis. You only re-test a
+settled axis when the channel's content or audience visibly shifts.
+
+**Caveat:** on a small channel a single test is noise. Treat a pattern as real only
+after it holds across ~3+ tests or a clear, repeated margin. Full schema, filled
+example rows, and the pattern-mining heuristic live in
+`references/experiment-log-format.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Tiny or thin text | Illegible at 320x180 feed scale | 3-4 words, heavy bold, squint-tested |
+| 5+ colors | Muddies into noise when shrunk | 2-3 complementary bold colors |
+| Clipart / stock faces | No emotion, no trust, reads as spam | Real face, one strong emotion |
+| Thumb text == title text | Wastes both surfaces of the promise | Thumb adds the stake the title omits |
+| Varying 3 axes per test | Winner is uninterpretable | One axis per variant set |
+| Trusting one test on a small channel | That's noise, not signal | Wait for ~3+ tests / repeated margin |
+| Designing in the full editor only | Looks great at 1280, dies in the feed | Check the 320x180 squint view |
+| Subject/logo in bottom-right | Duration stamp covers it | Keep that corner clear |
+| Chasing CTR while watch time tanks | Test & Compare scores watch-time share | Fix the over-promise (see youtube-packaging) |
+
+## Pre-publish checklist
+
+- [ ] Exactly 1280x720, 16:9, under 2MB, JPG or PNG (run `scripts/verify.sh`)
+- [ ] Passes the 320x180 squint test
+- [ ] Bottom-right corner clear of text/face/logo
+- [ ] Single dominant focal point; subject ~30% contrast vs background
+- [ ] 3-4 words max, heavy weight; text not duplicating the title
+- [ ] 2-3 colors only
+- [ ] Variant set differs on exactly ONE named axis
+- [ ] Test & Compare configured (<=3 variants, watch-time-share, ~2-week window)
+- [ ] Log row staged for `02-DOCS/wiki/youtube/thumbnail-experiments.md`
+
+## See also
+
+- [youtube-packaging](../youtube-packaging/SKILL.md) — the title<->thumbnail promise pair and hook framing.
+- [youtube-strategy](../youtube-strategy/SKILL.md) — channel positioning, niche, cadence.
+- [ab-testing](../ab-testing/SKILL.md) — rigorous experiment design on non-YouTube surfaces.
+- [design](../design/SKILL.md) — general visual systems and composition theory.

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

@@ -0,0 +1,11 @@
+# Evals — youtube-thumbnails
+
+These cases are LLM-graded against the rubric in `cases.yaml`, run through the
+repo's standard eval runner. `should_trigger` and `should_not_trigger` check
+routing — does the skill fire on real thumbnail/A-B work and stay quiet when the
+request belongs to a sibling (packaging, strategy, ideation, the API, ab-testing,
+or brand-identity)? `capability` checks the end-to-end behavior on the PC-build
+scenario: one-axis variants, the hard image constraints, correct Test & Compare
+setup (watch-time-share, not CTR), and a logged wiki row with the next-concept
+rule. No live YouTube account or Data API access is needed — grading is on the
+agent's plan and outputs, not on real uploads.

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

@@ -0,0 +1,48 @@
+skill: youtube-thumbnails
+
+should_trigger:
+  - prompt: "Design 3 thumbnail variants to A/B test for my new video."
+    why: Core job — concept generation feeding a Test & Compare run.
+  - prompt: "My CTR dropped this month, can you fix this thumbnail?"
+    why: Diagnostic entry point into the craft rules.
+  - prompt: "Set up a Test & Compare experiment on this upload."
+    why: The skill owns the native thumbnail A/B mechanics.
+  - prompt: "CTR is fine but the test keeps picking the boring thumbnail — why?"
+    why: Non-obvious — the watch-time-share metric vs CTR and the over-promise trap.
+  - prompt: "Which thumbnail style actually wins on my channel?"
+    why: Reads the per-channel wiki log and mines patterns; distinctive feedback-loop job.
+  - prompt: "Fes la miniatura del vídeo perquè tingui més clics."
+    why: Catalan phrasing for thumbnail design — language + craft trigger.
+
+should_not_trigger:
+  - prompt: "Write 5 title options for this video."
+    route_to: youtube-packaging
+    why: Title wording and the click-promise pairing live in packaging, not image craft.
+  - prompt: "What niche should my channel focus on?"
+    route_to: youtube-strategy
+    why: Channel-level positioning and cadence, not a single thumbnail.
+  - prompt: "Give me 10 video ideas for this week."
+    route_to: youtube-ideation
+    why: Topic/idea generation, upstream of any thumbnail.
+  - prompt: "Programmatically upload and set the thumbnail via the YouTube Data API."
+    route_to: youtube-api
+    why: API integration, not design or A/B mechanics.
+  - prompt: "Design a logo and a brand color palette for my company."
+    route_to: brand-identity
+    why: General visual identity, not a YouTube thumbnail.
+  - prompt: "Run a statistically rigorous A/B test on my landing page."
+    route_to: ab-testing
+    why: Generic experiment design on a non-YouTube surface.
+
+capability:
+  - scenario: >
+      A creator has a video "I built a PC in 24 hours", current CTR ~3%, and wants
+      better thumbnails plus a test they can actually learn from. Walk them from
+      brief to logged result.
+    must_include:
+      - Proposes 2-3 variants that differ on exactly ONE named axis each (e.g. subject: face vs object)
+      - Enforces hard constraints — 1280x720, 16:9, under 2MB, 320x180 legibility, bottom-right safe zone
+      - Applies face+emotion and the ~30% contrast/luminance guidance concretely
+      - Sets up Test & Compare correctly — up to 3 variants, winner by watch-time share not CTR, ~2-week window, auto-promote
+      - Writes/updates a log row under 02-DOCS/wiki/youtube/thumbnail-experiments.md and states the next-concept rule
+      - Defers title wording and the title<->thumbnail promise to youtube-packaging rather than rewriting the title

package/skills/youtube-thumbnails/references/composition-and-specs.md

@@ -0,0 +1,69 @@
+# Composition & specs reference
+
+Depth for the hard constraints and composition rules in SKILL.md. All facts dated
+2026-06-02.
+
+## Full constraint table
+
+| Property | Value | Notes |
+|---|---|---|
+| Recommended resolution | 1280 x 720 px | Anything smaller upscales soft |
+| Aspect ratio | 16:9 | Fills player, feed, end screens, embeds |
+| Minimum width | 640 px | Below this, upload may be rejected |
+| File size (standard) | under 2 MB | Hard cap |
+| File size (podcast) | under 10 MB | Only the podcast surface allows this |
+| Accepted formats | JPG, PNG, GIF, BMP | Ship JPG or PNG |
+| Feed render scale | ~320 x 180 px | Where most discovery happens |
+| Duration-stamp zone | bottom-right corner | Reserved overlay — keep critical content out |
+
+## The 30% contrast rule (luminance, not hue)
+
+Make the main subject roughly 30% brighter or darker than the background. This is
+about *luminance* separation, not color difference. Quick way to judge it: desaturate
+the image to grayscale — if the subject still clearly separates from the background
+in gray, it will separate in the feed. If the subject and background turn the same
+shade of gray, add an outline, drop shadow, or glow until they don't.
+
+Text/background contrast: aim for about 4.5:1. This is a borrowed usability
+heuristic (the WCAG AA ratio for normal text), not a YouTube-enforced rule — use it
+as a floor, not a target.
+
+## Legibility test protocol (the squint test)
+
+1. Export the candidate at 1280x720.
+2. Scale a copy to 320x180.
+3. Glance for under one second. Can you name the subject and read the text?
+4. If not, the thumbnail fails the feed and no editor-canvas polish saves it.
+
+Equivalent without resizing: step ~2 meters back from the monitor, or view it as a
+phone-sized thumbnail in an actual feed mock.
+
+## Render contexts to check
+
+A thumbnail does not live in one place. Verify it in:
+
+- **Mobile feed (light + dark mode)** — the dominant surface; dark mode changes how
+  a dark background reads against the app chrome.
+- **Desktop sidebar (small)** — even smaller than the mobile feed in some layouts.
+- **Watch-page suggested column** — appears next to a playing video, competing for
+  attention.
+- **Search results grid** — sits among rival thumbnails; relative contrast matters.
+
+## Export workflow (PNG -> JPG under 2MB)
+
+1. Design and master in PNG (lossless) at 1280x720.
+2. Export final as JPG at quality 85-90%. This almost always lands well under 2 MB
+   while keeping text edges crisp.
+3. If a PNG with flat color/text must stay PNG and exceeds 2 MB, reduce the palette
+   or flatten layers before re-exporting.
+4. Re-run `scripts/verify.sh path/to/thumb.jpg` to confirm dimensions, ratio, size,
+   and format before upload.
+
+## Sources
+
+- socialrails.com — 1280x720 specs guide (accessed 2026-06-02)
+- thumbnailtest.com — size/format guide (accessed 2026-06-02)
+- thumbmagic.co / socialrails.com — 320x180 safe-zone guides (accessed 2026-06-02)
+- usevisuals.com, deliveredsocial.com — duration-stamp safe zone (accessed 2026-06-02)
+- nearstream.us, clickyapps.com — face/emotion and custom-vs-auto CTR (accessed 2026-06-02)
+- usevisuals.com, ampifire.com — color count and 30% contrast guidance (accessed 2026-06-02)

package/skills/youtube-thumbnails/references/experiment-log-format.md

@@ -0,0 +1,65 @@
+# Experiment log format
+
+The wiki layout, schema, filled example, and pattern-mining heuristic for the
+feedback loop in SKILL.md. Everything lives under `02-DOCS/wiki/youtube/`.
+
+## Files
+
+- `thumbnail-experiments.md` — append-only log, one row per Test & Compare run.
+- `thumbnail-patterns.md` — derived, human-maintained summary of what wins on this
+  channel. You rewrite the relevant line after each logged test.
+
+## `thumbnail-experiments.md` schema
+
+```text
+| date | video | variants | axis tested | winner | CTR | watch-time share | note |
+```
+
+- **date** — ISO date the test concluded.
+- **video** — title or video ID.
+- **variants** — short labels, e.g. `A: face-shock / B: object`.
+- **axis tested** — the single axis you varied (subject, expression, text, color,
+  layout, zoom).
+- **winner** — which variant YouTube auto-promoted.
+- **CTR** — reported click-through for the winner (context only; not the deciding
+  metric).
+- **watch-time share** — the metric that actually decided the test.
+- **note** — one-line takeaway, especially any over-promise signal.
+
+### Filled example
+
+```text
+| date       | video                | variants                  | axis tested | winner | CTR  | watch-time share | note |
+|------------|----------------------|---------------------------|-------------|--------|------|------------------|------|
+| 2026-05-20 | I built a PC in 24h  | A: face-shock / B: object | subject     | A      | 6.1% | 41%              | face beat the build photo clearly |
+| 2026-05-28 | $200 budget PC       | A: shock / B: confident   | expression  | B      | 5.4% | 39%              | calm-confident edged shock for this niche |
+| 2026-06-01 | Worst PC parts       | A: text / B: no-text      | text        | A      | 5.9% | 38%              | one bold word helped; thin margin, re-test |
+```
+
+## `thumbnail-patterns.md` shape
+
+```text
+# What wins on this channel
+
+| axis | settled winner | evidence | confidence |
+|------|----------------|----------|------------|
+| subject    | human face        | 4/5 tests | high   |
+| expression | confident > shock | 2 tests   | low    |
+| text       | 1 bold word       | 2 tests, thin margins | low |
+```
+
+## Pattern-mining heuristic
+
+1. Group logged rows by `axis tested`.
+2. For each axis, count which level won and by what watch-time margin.
+3. Promote a level to "settled winner" only when it holds across ~3+ tests OR wins
+   by a large, repeated margin. Mark confidence honestly.
+4. The next thumbnail keeps every settled winner and tests the next unsettled axis.
+
+## Minimum-sample caveat
+
+On a small channel, watch-time-share differences inside a single ~2-week test are
+mostly noise. A single result is a hint, not a rule. Resist rewriting your whole
+thumbnail style off one win — wait for the margin to repeat. When content type or
+audience shifts noticeably, re-open settled axes; yesterday's winning pattern was
+fit to yesterday's audience.

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

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# verify.sh — check YouTube thumbnail image files against the hard, objective spec.
+# Read-only. Judges the spec, never taste. Exits 0 on a clean/empty target.
+#
+# Checks per image: 1280x720, 16:9, size < 2 MB, format in {jpg, png}.
+# Tooling preference: sips (macOS) -> ImageMagick identify -> file (+ byte size).
+# If no image tooling is available, prints a clear SKIP and exits 0 (no false fail).
+#
+# Usage:
+#   scripts/verify.sh                 # scan ./ for *.jpg/*.jpeg/*.png
+#   scripts/verify.sh path/to/img.jpg # check one or more files
+#   scripts/verify.sh path/to/dir/    # scan a directory
+
+set -uo pipefail
+
+MAX_BYTES=$((2 * 1024 * 1024)) # 2 MB
+WANT_W=1280
+WANT_H=720
+
+fail=0
+checked=0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Collect target files from args (files or dirs); default to current dir.
+collect() {
+  local args=("$@")
+  [ "${#args[@]}" -eq 0 ] && args=(".")
+  local p
+  for p in "${args[@]}"; do
+    if [ -d "$p" ]; then
+      find "$p" -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \) 2>/dev/null
+    elif [ -f "$p" ]; then
+      printf '%s\n' "$p"
+    else
+      echo "WARN: no such file or directory: $p" >&2
+    fi
+  done
+}
+
+# Echo "WIDTHxHEIGHT" for a file, or empty if undetermined.
+dimensions() {
+  local f="$1" out
+  if have sips; then
+    out=$(sips -g pixelWidth -g pixelHeight "$f" 2>/dev/null)
+    local w h
+    w=$(printf '%s\n' "$out" | awk '/pixelWidth/{print $2}')
+    h=$(printf '%s\n' "$out" | awk '/pixelHeight/{print $2}')
+    [ -n "$w" ] && [ -n "$h" ] && { printf '%sx%s' "$w" "$h"; return; }
+  fi
+  if have identify; then
+    out=$(identify -format '%wx%h' "$f" 2>/dev/null)
+    [ -n "$out" ] && { printf '%s' "$out"; return; }
+  fi
+  printf ''
+}
+
+byte_size() {
+  local f="$1"
+  if stat -f%z "$f" >/dev/null 2>&1; then stat -f%z "$f"; else stat -c%s "$f" 2>/dev/null; fi
+}
+
+ext_ok() {
+  case "${1##*.}" in
+    [jJ][pP][gG]|[jJ][pP][eE][gG]|[pP][nN][gG]) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Tooling gate: if we cannot read dimensions at all, skip cleanly.
+if ! have sips && ! have identify; then
+  echo "SKIP: no image tooling (sips or ImageMagick 'identify') found; cannot verify dimensions."
+  echo "      Install ImageMagick or run on macOS to enable dimension/ratio checks."
+  exit 0
+fi
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  checked=$((checked + 1))
+  errs=()
+
+  ext_ok "$f" || errs+=("format must be jpg/png")
+
+  bytes=$(byte_size "$f")
+  if [ -n "${bytes:-}" ] && [ "$bytes" -ge "$MAX_BYTES" ]; then
+    errs+=("size ${bytes}B >= 2MB")
+  fi
+
+  dim=$(dimensions "$f")
+  if [ -z "$dim" ]; then
+    errs+=("could not read dimensions")
+  else
+    w=${dim%x*}; h=${dim#*x}
+    if [ "$w" != "$WANT_W" ] || [ "$h" != "$WANT_H" ]; then
+      errs+=("dimensions ${dim}, want ${WANT_W}x${WANT_H}")
+    fi
+    # 16:9 check (independent of exact size): w*9 == h*16
+    if [ -n "$w" ] && [ -n "$h" ] && [ $((w * 9)) -ne $((h * 16)) ]; then
+      errs+=("aspect ratio not 16:9 (${dim})")
+    fi
+  fi
+
+  if [ "${#errs[@]}" -eq 0 ]; then
+    echo "PASS  $f  (${dim:-?}, ${bytes:-?}B)"
+  else
+    fail=1
+    echo "FAIL  $f"
+    for e in "${errs[@]}"; do echo "        - $e"; done
+  fi
+done < <(collect "$@")
+
+if [ "$checked" -eq 0 ]; then
+  echo "OK: no thumbnail images found to check."
+  exit 0
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "Some thumbnails failed the hard spec."
+  exit 1
+fi
+
+echo "All $checked thumbnail(s) meet the hard spec."
+exit 0

package/targets/claude.js

@@ -0,0 +1,23 @@
+import { cpSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export function writeSkill(id, fromDir, toPath) {
+  mkdirSync(dirname(toPath), { recursive: true });
+  cpSync(fromDir, toPath, { recursive: true });
+  return [toPath];
+}
+
+export function wireHook(paths) {
+  const file = paths.hookTarget;
+  const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  settings.hooks ||= {};
+  settings.hooks.SessionStart ||= [];
+  const cmd = `cat "${paths.skillDir('suggest')}/SKILL.md"`;
+  const already = JSON.stringify(settings.hooks.SessionStart).includes('skills/rsc/suggest');
+  if (!already) {
+    settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: cmd }] });
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return [file];
+}

package/targets/codex.js

@@ -0,0 +1,29 @@
+import { cpSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const MARK_START = '<!-- rsc-suggest:start -->';
+const MARK_END = '<!-- rsc-suggest:end -->';
+
+export function writeSkill(id, fromDir, toPath) {
+  mkdirSync(dirname(toPath), { recursive: true });
+  cpSync(fromDir, toPath, { recursive: true });
+  return [toPath];
+}
+
+export function wireHook(paths, sourceMd) {
+  const body = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+  const block = `${MARK_START}\n${body}\n${MARK_END}`;
+  let doc = existsSync(paths.hookTarget) ? readFileSync(paths.hookTarget, 'utf8') : '';
+  if (doc.includes(MARK_START)) {
+    doc = doc.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);
+  } else {
+    doc += `\n\n${block}\n`;
+  }
+  mkdirSync(dirname(paths.hookTarget), { recursive: true });
+  writeFileSync(paths.hookTarget, doc);
+  return [paths.hookTarget];
+}
+
+function stripFrontmatter(md) {
+  return md.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}