rsc-universal 0.1.1

package/skills/video-shorts/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: video-shorts
+description: "Use when scripting or directing the edit of a single vertical short for Reels/Shorts/TikTok that has to hold attention from the first frame — turning a topic, a clip, or a long video into a shot-by-shot script and an edit decision sheet. Use for writing a 15–60s short, fixing a hook that dies in second three, generating hook variants to A/B test, planning cuts and burned-in captions, or extracting shorts from a long video. Triggers: 'write me a 30-second Reel/TikTok/Short', 'my Reels die in the first 3 seconds', 'give me 5 hook variants to A/B test', 'turn this podcast clip into a vertical short', 'plan the cuts and on-screen text for this faceless voiceover Reel', 'escríbeme un guion para un Reel de 30 segundos', 'convierte este vídeo largo en un Short', 'el gancho de mis Reels no engancha'. NOT scheduling or cross-platform cadence (that is social-publisher), NOT running the editorial calendar/pipeline (that is content-engine), NOT defining the durable brand tone (that is brand-voice)."
+tags: [short-form-video, reels, shorts, tiktok, video-script, hook, retention, captions, vertical-video, editing]
+recommends: [social-publisher, content-engine, brand-voice, podcast, ads]
+origin: risco
+---
+
+# Video Shorts — The Script and the Cut for One Vertical Video
+
+*You are the scriptwriter and edit director for a single 9:16 short.* You hold attention for 15–60 seconds and then hand off. You do not pick the posting time, you do not run the calendar, you do not invent the brand voice, and you do not render pixels. You produce two coupled documents and the rigor lives in their structure, not in encoding.
+
+## What you produce
+
+Two artifacts, every time, in one `.md`:
+
+1. **A timecoded script** — a beat sheet (hook → body → payoff → loop/CTA) where every beat carries the spoken/VO line *and* the burned-in on-screen text *and* the visual.
+2. **An edit decision sheet (EDS)** — cut rhythm, B-roll/visual-change markers, caption styling, safe-zone layout, the chosen hook frame, and the loop seam, so an editor (a human or a CapCut/OpusClip-style tool) assembles it without guessing.
+
+**The one governing rule: write for the sound-off viewer.** Most social video is watched muted — the primary Verizon Media / Publicis Media study (online survey, 5,616 U.S. adults 18–54, April 2019) found 69% watch video with the sound off in public and that 80% are more likely to finish a video when captions are present. The on-screen text is not a subtitle of the audio — it is a first-class narrative layer that must carry the video alone. If your short only works with sound on, it is broken. *Why: a muted viewer who reads nothing scrolls in under a second.*
+
+You output a script + EDS the user hands to a creator or pastes into an editor. The deliverable is the plan, not the rendered file.
+
+## Decide first
+
+Pick a length from the *content type*, not from how much you have to say. The retention sweet spot is **15–30s, where shorts often clear high completion**; past ~45s drop-off is steep (vendor-reported industry figures, e.g. OpusClip ideal-length data, 2026 — directional, not peer-reviewed).
+
+| Content type | Target length | Why |
+|---|---|---|
+| Tip / hack / single insight | 15–20s | One idea, one payoff; longer dilutes it |
+| Tutorial / how-to | 25–40s | Needs steps, still must escalate |
+| Story / before-after | 30–45s | Tension needs room, but cap the burn |
+| Anything > 45s | must justify itself | Every extra second has to earn its retention |
+
+YouTube Shorts allows up to 3 min (180s, since 15 Oct 2024) and Reels/TikTok go longer still, but length-allowed is not length-wanted — the algorithm rewards completion, and completion lives in the short band.
+
+**Route out before you start writing:**
+
+- Posting cadence, best-time slots, cross-platform limits → `../social-publisher/SKILL.md`.
+- Which short to commission, the editorial calendar → `../content-engine/SKILL.md`.
+- The durable brand tone you should write *in* → `../brand-voice/SKILL.md`.
+- Paid creative variants / ROAS / ad-account structure → `../ads/SKILL.md`.
+- A talking audio-first episode (not a vertical clip) → `../podcast/SKILL.md`.
+
+## The structure
+
+Four blocks, with a timecode budget. Worked for a **30-second** short:
+
+| Block | Window (30s) | Job |
+|---|---|---|
+| **Hook** | 0:00–0:03 | Survive second 3. Promise, don't describe. |
+| **Body / escalation** | 0:03–0:24 | Deliver, escalating; visual change every 3–5s |
+| **Payoff** | 0:24–0:28 | The resolution the hook promised (last 15–25%) |
+| **Loop / CTA** | 0:28–0:30 | Seam back to frame 1, or one-action CTA |
+
+**Visual change every 3–5s after the hook.** A new shot, B-roll, text card, zoom, or reframe — anything that resets the eye. *Why: a static frame past ~4s reads as "this is over" and the viewer leaves; a visual change signals "there's more."*
+
+**Open the loop early, close it late.** State a question or stake in the hook ("the third one is the mistake everyone makes") and withhold the resolution until the payoff. Numbered points ("3 things…") work because each number is a built-in progress bar that pulls the viewer to the next.
+
+## The hook
+
+As vendor-reported industry figures (OpusClip / housesparrowfilms, 2026; directional, not from a primary study), roughly half of the viewers who drop do so in the first 3 seconds, intro retention past 3s should land around 70%+, and shorts holding above ~65% at 3s see several times more impressions. Treat the exact percentages as orders of magnitude, not precise data — but the direction is unambiguous: the hook is the whole game.
+
+**Six hook patterns** — pick by intent:
+
+| Pattern | When to use |
+|---|---|
+| Promise / result | You have a concrete outcome ("how I cut my edit time in half") |
+| Question | The viewer has felt the pain ("why do your Reels die at second 3?") |
+| Pattern interrupt | You need to break the scroll ("stop posting at 9am") |
+| Contrarian claim | You can defend a take against consensus ("captions are not optional") |
+| In medias res | You can open mid-action / mid-result ("…and that's the cut that doubled it") |
+| Stakes / tension | There's a cost to not knowing ("this mistake tanks your reach") |
+
+**On-screen hook text: 4–7 words, high contrast, inside the safe zone.** It must be readable muted in under a second. Longer than 7 words and the muted viewer can't finish it before deciding to leave.
+
+**Bad → Good rewrites:**
+
+| Bad | Why it dies | Good |
+|---|---|---|
+| "Hey guys, today I want to talk about editing." | Describes, no promise, burns 3s on throat-clearing | "Your edit is losing viewers at second 3." |
+| "Let me tell you a story about my first Reel." | Slow-burn intro, payoff invisible | "My first Reel got 11 views. Here's the fix." |
+| "In this video we'll cover five tips." | Generic, no stake, no curiosity gap | "Tip 3 is the one nobody does." |
+| "So basically captions are kind of important." | Hedged, mute-unreadable, no contrast | "Most people watch on mute. No captions, no views." |
+
+**Reflex: cut your first five seconds.** First drafts almost always bury the hook behind a greeting. Delete the setup and start on the strongest line. When asked for variants, give 5 hooks across *different* patterns — not five rewrites of one.
+
+For the full hook library by content type and a worked long-video → short extraction, see `references/hook-and-script-patterns.md`.
+
+## The script artifact
+
+A timecoded table. Every row has on-screen text — no exceptions (sound-off rule).
+
+```markdown
+## Script — "Stop posting at 9am" (28s, 9:16)
+
+| Time | VO / spoken | On-screen text | Visual / B-roll |
+|------|-------------|----------------|-----------------|
+| 0:00–0:03 | "Stop posting at 9am." | STOP POSTING AT 9AM | Hard cut to face, fast zoom-in |
+| 0:03–0:09 | "Your audience isn't awake — they're commuting at 8." | 9am = your worst slot | Phone clock 9:00 → swipe to 8:00 |
+| 0:09–0:16 | "The data says evenings beat mornings for this niche." | Evenings win | B-roll: graph line rising |
+| 0:16–0:23 | "Test 6pm for a week and watch the reach." | Try 6pm for 7 days | Screen-record of scheduler set to 18:00 |
+| 0:23–0:26 | "Then come back and tell me I was wrong." | I'll wait. | Back to face, raised eyebrow |
+| 0:26–0:28 | "Stop posting at 9am." | STOP POSTING AT 9AM | Match-cut to opening frame (loop seam) |
+```
+
+Note the last row repeats the hook line and frame: that is the loop, not an outro. Keep VO lines short and spoken-natural; the on-screen text is tighter (4–7 words) and never a verbatim dump of the VO.
+
+## The edit decision sheet
+
+The EDS turns the script into cut instructions. Tie each marker to a script row.
+
+- **Cut cadence: one cut every 2–4 seconds.** High-performing shorts average that; put **micro-cuts (0.4–1.2s)** in the first 2–3 shots to "wake" the scroller. Keep dead-air pauses **under ~250ms** — silence past a quarter-second reads as buffering and viewers leave (vendor-reported editing guidance, OpusClip / driveeditor, 2026).
+- **Visual-change markers** — annotate each script row with its change (cut / B-roll / text card / zoom / reframe) so no row sits static past 5s.
+- **Hook frame** — name the exact opening frame (the most arresting still). It is the thumbnail-in-motion; if it's boring, nothing after it matters.
+- **Loop seam** — specify how the last frame blends into the first (match cut, same framing, same audio bar). **The loop is the CTA**: even a ~10% replay rate is weighted heavily by the algorithm, and a clean seam manufactures replays. No traditional "thanks for watching" outro.
+- **Caption track** — styling lives in the next section; the EDS just flags "captions: burned-in, style X, on for the whole runtime."
+
+```markdown
+## EDS — "Stop posting at 9am"
+- Hook frame: face mid-sentence, eyes to lens, 0:00 (most arresting still)
+- Cuts: micro-cuts 0:00–0:03 (3 cuts), then 1 cut / ~3s thereafter
+- Dead air: trim every gap > 250ms
+- B-roll: clock (0:03), rising graph (0:09), scheduler screen-rec (0:16)
+- Captions: burned-in, all 28s, style below, safe-zone bottom margin respected
+- Loop seam: 0:26 match-cut to 0:00 frame; same VO line bridges the seam
+- CTA: implicit (the loop). No outro card.
+```
+
+## Captions & safe zones
+
+Captioned videos retain better — the primary Verizon Media / Publicis Media study (n=5,616, April 2019) found 80% of viewers more likely to finish a video with captions; vendors report an additional ~15–25% retention lift (OpusClip / Verbit, 2026, vendor figures). Treat captions as design, not an afterthought.
+
+- **Large, high-contrast, with a solid stroke or box** — readable on a bright phone outdoors.
+- **4–7 words per line, ≥2s on screen.** Faster than that and the muted viewer can't read it.
+- **On for the entire runtime.** No "captions only on the hook."
+- **Inside safe zones.** Keep all text and the CTA out of the platform UI margins (top, bottom, and right rail eat your text). Exact pixel margins per platform are in `references/specs-and-safe-zones.md`.
+- **Don't bury the hook under a trend audio's caption.** If you ride a trending sound, your own on-screen hook still owns the top third in second one.
+
+## Repurpose one master
+
+All three platforms share **9:16 @ 1080×1920, MP4 (H.264 video + AAC audio), 30 or 60 fps** (vidIQ / Sprout Social specs, 2026). One master export repurposes across Reels, Shorts, and TikTok — to surface on the Shorts shelf, just keep it vertical/square and under the 3-min ceiling.
+
+Handing off to a tool (CapCut's 2026 AI Suite for one-click auto-edit + hundreds of TTS voices + multilingual captions + AI avatars, OpusClip/Reap/Vizard for long-video clipping, Submagic for caption styling): **paste the script + EDS as the brief.** The tool executes cuts and captions fast, but it does not invent your hook or your loop seam — those are yours. Algorithms now demote obvious low-effort AI clips, so the structure you bring is exactly what separates the short from filler. Per-platform specs, the export checklist, and current tool capabilities live in `references/specs-and-safe-zones.md`.
+
+## Anti-patterns
+
+| Bad | Why it kills retention | Good |
+|---|---|---|
+| Slow-burn intro / greeting before the point | ~half of droppers leave in the first 3s; you spent them on "hey guys" | Open on the strongest line; cut the first 5s |
+| No burned-in captions | most viewers watch muted; a silent screen has no narrative | Captions all runtime, 4–7 words/line, high contrast |
+| Traditional "thanks for watching" outro | Ends the video instead of replaying it | Loop seam: last frame match-cuts to the first |
+| One static talking-head shot for 30s | No visual change reads as "it's over" past ~4s | A cut / B-roll / text card every 3–5s |
+| Hook that *describes* the topic | Description has no promise or stake, so no reason to stay | Promise an outcome or open a curiosity gap |
+| >45s with no escalation | Flat energy collapses completion past the sweet spot | Cut to 15–30s, or escalate every beat |
+| TTS narrating a wall of on-screen text | Mismatched layers, nothing to read fast, AI-clip smell | Tight VO + separate 4–7-word caption layer |
+| Trend audio buries your own hook | The borrowed caption owns second one, not your promise | Your hook owns the top third in the first frame |
+
+## Verify & references
+
+- Lint a produced script with `bash scripts/verify.sh path/to/script.md` — it checks a 0:00 hook beat exists, every beat has on-screen text (sound-off), the runtime sits in a sane short band, and a loop/CTA beat closes it. It is read-only and exits 0 on a clean script.
+- `references/specs-and-safe-zones.md` — per-platform spec table, safe-zone pixel margins, export/repurposing checklist, dated tool snapshot.
+- `references/hook-and-script-patterns.md` — full hook library by content type, beat-sheet + EDS templates, worked long-video → short extraction.

package/skills/video-shorts/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — video-shorts
+
+These cases are routing + capability checks for a human or an LLM judge; there is
+no automated runner beyond `scripts/verify.sh` (which lints an emitted script file,
+not these prompts). To run them: read `cases.yaml` and confirm the skill's
+`description` would fire on every `should_trigger` prompt — including the
+non-obvious "my Reels lose everyone in the first 3 seconds" symptom and the Spanish
+"convierte este vídeo largo en un Short" phrasing — and that each `should_not_trigger`
+prompt routes to the named sibling instead (`social-publisher`, `content-engine`,
+`brand-voice`, `ads`, `podcast`) rather than here. For the `capability` scenario,
+generate the script + EDS and grade it line by line against the `must_include`
+rubric: a 0:00–0:03 hook with 4–7-word on-screen text, a timecoded beat sheet that
+sums to a 15–30s runtime, on-screen text on every beat, a cut-cadence note, a loop
+seam or single CTA (no outro), and the 9:16/1080×1920/burned-in-caption export note.
+To lint an actual produced script, point `scripts/verify.sh` at the `.md` it emitted.

package/skills/video-shorts/evals/cases.yaml

@@ -0,0 +1,56 @@
+skill: video-shorts
+
+# Prompts that MUST load `video-shorts`. The skill owns the CRAFT of one short:
+# the timecoded script (hook → body → payoff → loop) written for sound-off, and
+# the edit decision sheet (cut cadence, B-roll, captions, safe zones, loop seam).
+# It does NOT schedule (social-publisher), commission/calendar (content-engine),
+# define brand voice (brand-voice), buy reach (ads), or make audio episodes (podcast).
+should_trigger:
+  - prompt: "Write me a 30-second TikTok script about cold brew coffee."
+    why: "Core ask — a single vertical short script is exactly the deliverable."
+
+  - prompt: "My Reels lose everyone in the first 3 seconds, fix the hook."
+    why: "Non-obvious — the user names a retention symptom, not the skill; fixing the hook is the skill's signature move."
+
+  - prompt: "Turn this 40-minute podcast into 3 vertical Shorts."
+    why: "Long-video → short extraction; each short needs its own hook and loop, which this skill owns."
+
+  - prompt: "Give me 5 hook variants to A/B test for this clip."
+    why: "Hook-only craft ask — the skill's hook library produces patterned variants, not five rewrites of one."
+
+  - prompt: "Convierte este vídeo largo en un Short de 30 segundos con captions."
+    why: "Spanish for 'turn this long video into a 30s Short with captions' — long→short extraction plus the sound-off caption layer."
+
+  - prompt: "Plan the cuts and on-screen text for this faceless voiceover Reel."
+    why: "Edit-direction ask — cut cadence + burned-in captions are the EDS half of the skill."
+
+should_not_trigger:
+  - prompt: "When should I post my Reels and how often across platforms?"
+    route_to: social-publisher
+    why: "Cadence, best-time slots and cross-platform scheduling are distribution mechanics, not the craft of the clip."
+
+  - prompt: "Build our monthly content calendar and brief the team."
+    route_to: content-engine
+    why: "Commissioning shorts and running the editorial pipeline is the factory; this skill is one station."
+
+  - prompt: "Define our brand's tone of voice we reuse everywhere."
+    route_to: brand-voice
+    why: "The durable voice system is consumed by this skill, not authored by it."
+
+  - prompt: "Set up a Meta Advantage+ campaign with 5 paid creative variants and budgets."
+    route_to: ads
+    why: "Paid acquisition, ad-account structure and ROAS math live in ads; organic short craft lives here."
+
+  - prompt: "Edit and publish a full talking podcast episode."
+    route_to: podcast
+    why: "An audio-first episode is a different format; this skill makes vertical clips, not podcasts."
+
+capability:
+  - scenario: "Produce a 30s vertical Short script + edit decision sheet from a given topic (e.g. 'why morning posting is a myth')."
+    must_include:
+      - "A hook beat covering 0:00–0:03 with 4–7-word on-screen text that promises/opens a loop rather than describing"
+      - "A timecoded beat sheet whose rows sum to the declared runtime, inside the 15–30s sweet spot"
+      - "On-screen text present for EVERY beat (the sound-off rule), distinct from the VO line"
+      - "An EDS cut-cadence note: ~1 cut / 2–4s, micro-cuts in the first 2–3 shots, dead air trimmed under ~250ms"
+      - "A loop seam (last frame match-cuts to the first) or a single one-action CTA — never a traditional outro"
+      - "An export note: 9:16 @ 1080×1920, MP4 H.264+AAC, captions burned-in inside safe zones"

package/skills/video-shorts/references/hook-and-script-patterns.md

@@ -0,0 +1,95 @@
+# Hook library, templates & long-video extraction
+
+## Hook library by content type
+
+Pick the pattern that fits the *intent*; vary patterns when generating A/B
+variants instead of rewording one. Hook text stays 4–7 words, high contrast,
+inside the safe zone, readable muted in under a second.
+
+### Tip / hack
+- Promise: "Do this and your edit time halves."
+- Contrarian: "Stop using transitions. Here's why."
+- Stakes: "This one setting tanks your reach."
+
+### Tutorial / how-to
+- Promise + number: "3 cuts that fix any boring clip."
+- Question: "Why do your tutorials lose people at step 2?"
+- In medias res: "…and that's the move that finished it. From the top:"
+
+### Story / before-after
+- Stakes: "My first Reel got 11 views."
+- In medias res: "…so I deleted the whole thing and started over."
+- Contrarian: "Going viral made it worse. Here's what happened."
+
+### Faceless / voiceover
+- Question over B-roll: "Ever wonder why some Shorts never stop replaying?"
+- Pattern interrupt: "Everyone gets this backwards."
+- Open loop: "There are 4 reasons. The last one is the real one."
+
+## Six patterns, defined
+
+| Pattern | Definition | One-line test |
+|---|---|---|
+| Promise / result | Names a concrete outcome the viewer wants | "Would they screenshot this payoff?" |
+| Question | Asks something the viewer has felt | "Do they already have this pain?" |
+| Pattern interrupt | Breaks the expected scroll rhythm | "Is it the opposite of what they expect?" |
+| Contrarian claim | Defensible take against consensus | "Can you back it in the body?" |
+| In medias res | Opens mid-action / mid-result | "Does it start at the climax?" |
+| Stakes / tension | A cost to not knowing | "What do they lose by scrolling on?" |
+
+## Beat-sheet template
+
+```markdown
+## Script — "<title>" (<runtime>s, 9:16)
+
+| Time | VO / spoken | On-screen text | Visual / B-roll |
+|------|-------------|----------------|-----------------|
+| 0:00–0:03 | <hook line> | <4–7 word hook> | <hook frame + micro-cuts> |
+| 0:03–0:?? | <body beat 1> | <4–7 words> | <visual change> |
+| 0:??–0:?? | <body beat 2 (escalate)> | <4–7 words> | <visual change> |
+| 0:??–0:?? | <payoff> | <4–7 words> | <visual> |
+| 0:??–<end> | <loop line = hook> | <hook text> | <match-cut to frame 1> |
+```
+
+## EDS template
+
+```markdown
+## EDS — "<title>"
+- Hook frame: <exact opening still + timecode>
+- Cuts: micro-cuts <range> (count), then 1 cut / ~3s
+- Dead air: trim every gap > 250ms
+- B-roll: <marker @ timecode>, <marker @ timecode>
+- Captions: burned-in, full runtime, <style>, safe-zone respected
+- Loop seam: <last timecode> match-cut to <0:00 frame>; <bridge>
+- CTA: <single action / one benefit / 3–5 words> OR implicit (the loop)
+```
+
+## Worked example: long video → short
+
+**Source:** a 40-minute podcast on creator burnout.
+
+1. **Find the spike.** Skim the transcript/waveform for the one self-contained
+   claim that lands without context — here, the guest's line "I posted every day
+   for a year and it nearly broke me." That's your payoff seed.
+2. **Build the hook from the spike, not the start.** Don't open with the
+   episode's intro. Open with the tension: "I posted every day for a year." (hook,
+   stakes pattern).
+3. **Cut to a 28s beat sheet:**
+
+```markdown
+## Script — "Posting daily nearly broke me" (28s, 9:16)
+
+| Time | VO / spoken | On-screen text | Visual / B-roll |
+|------|-------------|----------------|-----------------|
+| 0:00–0:03 | "I posted every day for a year." | EVERY DAY FOR A YEAR | Guest mid-sentence, fast zoom |
+| 0:03–0:10 | "365 videos. My engagement went up. I went down." | 365 videos. I broke. | Calendar flipping, B-roll |
+| 0:10–0:18 | "The mistake wasn't the schedule — it was no system." | The schedule wasn't the problem | Cut to other speaker reacting |
+| 0:18–0:24 | "Batch a week in a day. Protect the other six." | Batch 7. Rest 6. | Text card, then back to face |
+| 0:24–0:28 | "I posted every day for a year — so you don't have to." | …so you don't have to | Match-cut to 0:00 frame (loop) |
+```
+
+4. **EDS:** captions burned-in full runtime; micro-cuts 0:00–0:03; B-roll on the
+   "365 videos" beat; loop seam 0:24 → 0:00 on the repeated line.
+5. **One source → multiple shorts:** the same episode yields a second short from a
+   different spike (e.g. the "batch 7, rest 6" tactic as a standalone tip). Each
+   short gets its own hook and its own loop — never one clip chopped in two.

package/skills/video-shorts/references/specs-and-safe-zones.md

@@ -0,0 +1,74 @@
+# Specs, safe zones & tooling
+
+All facts dated 2026-06-02 (vidIQ Shorts specs; Sprout Social social-video specs;
+YouTube Help three-minute Shorts; OpusClip ideal-length data — vendor-reported,
+directional; Reap state-of-clipping-tools 2026). CapCut capability numbers are
+sourced to CapCut's own product pages (capcut.com/tools/text-to-speech,
+accessed 2026-06-02), not to secondary marketing blogs.
+
+## Per-platform spec table
+
+One master export covers all three. Differences are length ceilings and the
+Shorts-shelf rule, not the container.
+
+| Spec | Reels | Shorts | TikTok |
+|---|---|---|---|
+| Aspect ratio | 9:16 | 9:16 | 9:16 |
+| Resolution | 1080×1920 | 1080×1920 | 1080×1920 |
+| Container | MP4 | MP4 | MP4 |
+| Codec | H.264 + AAC | H.264 + AAC | H.264 + AAC |
+| Frame rate | 30 or 60 fps | 30 or 60 fps | 30 or 60 fps |
+| Max length | up to 3 min | 3 min (180s, since 15 Oct 2024) | up to 10 min |
+| Surfacing rule | — | must stay vertical/square to hit the Shorts shelf | — |
+
+**Length-allowed ≠ length-wanted.** The retention sweet spot is 15–30s (vendors
+report high completion in this band); past ~45s drop-off is steep regardless of
+the ceiling. Use the ceiling only when the content genuinely needs it and
+escalates the whole way.
+
+## Safe zones
+
+Platform UI overlays (caption rail, profile, like/share/comment column, progress
+bar) sit on top of your frame. Keep all on-screen text and the CTA inside the
+safe zone or the UI eats them.
+
+Working margins on a 1080×1920 frame (treat as a conservative default; platforms
+shift their chrome, so verify on a real device before final export):
+
+| Edge | Keep text out of | Why |
+|---|---|---|
+| Bottom | ~250–320 px | Caption/handle bar + progress bar live here |
+| Right | ~140–180 px | Like / comment / share / sound column |
+| Top | ~120–160 px | Search / status / sometimes account chrome |
+| Left | ~50–80 px | Minor; safest gutter |
+
+Practical rule: **compose the hook text and CTA in the centre-upper third.** It
+clears every platform's chrome and is where the eye lands first.
+
+## Export / repurposing checklist
+
+- [ ] 9:16, 1080×1920, MP4, H.264 + AAC, 30 or 60 fps (one master).
+- [ ] Captions burned in (not a sidecar `.srt`) — survives muted autoplay and
+      re-uploads.
+- [ ] All text/CTA inside the safe zones above.
+- [ ] Runtime in the 15–30s sweet spot unless content justifies more.
+- [ ] Loop seam intact: last frame match-cuts to the first.
+- [ ] Hook frame is the most arresting still (it's the thumbnail-in-motion).
+- [ ] No platform watermark baked in (a TikTok watermark gets demoted on
+      Reels/Shorts) — export clean, add per-platform branding if needed.
+
+## Tool capability snapshot (2026)
+
+The tool executes; your script + EDS is the brief. None of these invent your
+hook or loop seam.
+
+| Tool | What it does well | Hand it |
+|---|---|---|
+| CapCut 2026 AI Suite | one-click auto-edit, multilingual captions, hundreds of TTS voices (CapCut's own TTS page lists 200+ AI voices, accessed 2026-06-02), AI avatars (faceless) | script + EDS as the cut/caption brief |
+| OpusClip / Reap / Vizard | long video → clip candidates with auto-captions | the source long video + your extraction picks |
+| Submagic | caption styling / animated captions | a cut video + the caption style spec |
+
+**Watch-out:** algorithms now demote obvious low-effort AI clips (raw auto-cut +
+generic TTS + stock B-roll with no structure). The script structure — a hook that
+survives second 3, a loop that earns a replay — is what separates a clip from
+filler. Let the tool do the labour, not the thinking.

package/skills/video-shorts/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# verify.sh — lint a produced video-shorts script (.md) for the structure rules.
+#
+# Usage:
+#   bash scripts/verify.sh path/to/script.md     # lint one emitted script
+#   bash scripts/verify.sh                        # no target -> nothing to check, exit 0
+#
+# What it checks against a timecoded beat-sheet table (the script artifact):
+#   1. A hook beat exists covering 0:00 (the first timecode row starts at zero).
+#   2. Every beat row carries non-empty on-screen text (the sound-off rule).
+#   3. The derived runtime sits in a sane short band (warn >180s, nudge to 15-30s).
+#   4. A loop or CTA beat closes the script (last beat mentions loop / CTA / match-cut).
+#
+# Read-only: it never writes, installs, or touches the network. Pure text parsing.
+# Exits 0 on a clean script AND on an empty/clean target (no false failure):
+#   - no argument given                -> "nothing to check", exit 0
+#   - argument is a directory with no   -> scans *.md; if none found, exit 0
+#     matching script files
+# Exits non-zero only when a real, parseable script breaks a rule.
+#
+# Portability: stock macOS bash 3.2. No mapfile, no associative arrays, set -u on,
+# set -e intentionally off (each check owns its exit handling).
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+warn() { printf '%s\n' "${YELLOW}WARN: $1${RESET}"; }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- collect targets -------------------------------------------------------
+targets=""
+if [ "$#" -eq 0 ]; then
+  printf '%s\n' "${YELLOW}Nothing to check (no script path given). Pass a script .md to lint.${RESET}"
+  exit 0
+fi
+
+for arg in "$@"; do
+  if [ -d "$arg" ]; then
+    for f in "$arg"/*.md; do
+      [ -e "$f" ] && targets="${targets}${targets:+
+}$f"
+    done
+  elif [ -f "$arg" ]; then
+    targets="${targets}${targets:+
+}$arg"
+  else
+    printf '%s\n' "${YELLOW}Skipping '$arg' (not a file or directory).${RESET}"
+  fi
+done
+
+if [ -z "$targets" ]; then
+  printf '%s\n' "${YELLOW}No .md script files found in the target(s). Nothing to check.${RESET}"
+  exit 0
+fi
+
+# --- parse one timecode "M:SS" or "MM:SS" into total seconds ----------------
+to_seconds() {
+  # echoes seconds, or empty if it does not match
+  case "$1" in
+    [0-9]*:[0-9][0-9])
+      m="${1%%:*}"; s="${1##*:}"
+      printf '%s' "$(( m * 60 + 10#$s ))"
+      ;;
+    *) printf '' ;;
+  esac
+}
+
+# first_tc <cell>  -> the START timecode (M:SS) of a "0:00-0:03"-style cell.
+first_tc_of() { printf '%s' "$1" | grep -oE '[0-9]+:[0-9][0-9]' | head -1; }
+# last_tc <cell>   -> the END timecode (the last M:SS token in the cell).
+last_tc_of()  { printf '%s' "$1" | grep -oE '[0-9]+:[0-9][0-9]' | tail -1; }
+
+failures=0
+clean_targets=0
+
+for file in $targets; do
+  # A "beat row" is a markdown table row whose first cell starts with a timecode
+  # like 0:00 or 0:00-0:03. Grab those rows only.
+  rows="$(grep -nE '^\|[[:space:]]*[0-9]+:[0-9][0-9]' "$file" 2>/dev/null || true)"
+
+  if [ -z "$rows" ]; then
+    warn "$file: no timecoded beat rows found (expected a '| Time | ... |' table) — not a script artifact, skipping."
+    continue
+  fi
+
+  clean_targets=$((clean_targets + 1))
+  file_fail_start=$failures
+  printf '\n%s\n' "Checking: $file"
+
+  # ---- rule 1: a hook beat at 0:00 ----------------------------------------
+  first_row_body="$(printf '%s\n' "$rows" | head -1)"
+  first_row_body="${first_row_body#*:}"
+  first_cell="$(printf '%s' "$first_row_body" | awk -F'|' '{print $2}')"
+  first_start="$(first_tc_of "$first_cell")"
+  if [ "$(to_seconds "$first_start")" = "0" ]; then
+    ok "hook beat starts at 0:00"
+  else
+    fail "first beat starts at '$first_start', not 0:00 — the hook must own the first frame."
+  fi
+
+  # ---- rule 2 + 3: every beat has on-screen text; track max end time ------
+  max_end=0
+  missing_text=0
+  beat_count=0
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    beat_count=$((beat_count + 1))
+    # strip the "lineno:" prefix grep -n added
+    body="${line#*:}"
+    # split the table row into cells: | Time | VO | On-screen text | Visual |
+    tc="$(printf '%s' "$body" | awk -F'|' '{print $2}' | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
+    onscreen="$(printf '%s' "$body" | awk -F'|' '{print $4}' | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
+    if [ -z "$onscreen" ]; then
+      missing_text=$((missing_text + 1))
+      warn "beat at '$tc' has no on-screen text (sound-off rule: every beat needs burned-in text)."
+    fi
+    # end time = the last M:SS token in the cell (or the start if there is only one)
+    endpart="$(last_tc_of "$tc")"
+    esec="$(to_seconds "$endpart")"
+    [ -n "$esec" ] && [ "$esec" -gt "$max_end" ] && max_end="$esec"
+  done <<EOF
+$rows
+EOF
+
+  if [ "$missing_text" -eq 0 ]; then
+    ok "all $beat_count beats carry on-screen text"
+  else
+    fail "$missing_text of $beat_count beats lack on-screen text — fails the sound-off rule."
+  fi
+
+  # ---- rule 3: runtime band -----------------------------------------------
+  if [ "$max_end" -gt 0 ]; then
+    if [ "$max_end" -gt 180 ]; then
+      warn "runtime ~${max_end}s exceeds the 180s ceiling — this is not a short."
+    elif [ "$max_end" -gt 45 ]; then
+      warn "runtime ~${max_end}s is past the 15-30s sweet spot — make sure every second escalates."
+    else
+      ok "runtime ~${max_end}s is within the short band"
+    fi
+  fi
+
+  # ---- rule 4: a loop / CTA closes it -------------------------------------
+  last_row="$(printf '%s\n' "$rows" | tail -1)"
+  if printf '%s' "$last_row" | grep -qiE 'loop|cta|match[ -]?cut|replay|seam'; then
+    ok "closing beat signals a loop / CTA"
+  else
+    fail "last beat does not signal a loop or CTA (loop|cta|match-cut|seam) — a short should replay, not end on an outro."
+  fi
+
+  if [ "$failures" -eq "$file_fail_start" ]; then
+    ok "$file passed"
+  fi
+done
+
+if [ "$clean_targets" -eq 0 ]; then
+  printf '\n%s\n' "${YELLOW}No parseable script artifacts among the target(s). Nothing to verify.${RESET}"
+  exit 0
+fi
+
+printf '\n'
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}$failures check(s) failed.${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}All checks passed.${RESET}"
+exit 0