Communitygithub.com

video-script-retention

Write YouTube Shorts (up to 60 seconds) and long-form video scripts that hold attention: an immediate hook, visible proof early, purposeful pacing, retention checkpoints, and honest AI-assisted production. Includes a shot-by-shot timing table, a retention-review checklist, a caption spec for 1080x1920, a full worked Shorts script, and a full worked long-form script. Use when scripting any Short, outlining a long-form video, or reviewing a script for drop-off points.

video-script-retention とは?

video-script-retention is a Claude Code agent skill that write YouTube Shorts (up to 60 seconds) and long-form video scripts that hold attention: an immediate hook, visible proof early, purposeful pacing, retention checkpoints, and honest AI-assisted production. Includes a shot-by-shot timing table, a retention-review checklist, a caption spec for 1080x1920, a full worked Shorts script, and a full worked long-form script. Use when scripting any Short, outlining a long-form video, or reviewing a script for drop-off points.

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JokerHTML/needcraft-skills/tree/HEAD/video-script-retention

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Video Script & Retention

What this skill is

A complete method for writing video scripts that hold attention: hook in the first seconds, visible proof early, one idea per beat, a stated limitation, and one call to action — plus the review step that catches drop-off points before you record.

It covers YouTube Shorts (up to 60 seconds) and long-form video (8–15 minutes). It does not cover filming, editing software, or thumbnail design, except where the script dictates them.

Who it is for: a creator or small team scripting their own videos who wants a repeatable structure instead of writing from a blank page each time.

Prerequisites

  • A single clear promise for the video: what the viewer will be able to do, know, or decide by the end. If you cannot state it in one sentence, the script is not ready.
  • Any factual claim in the script must have a source you have opened. No fabricated statistics, results, or testimonials — ever.
  • A way to count words (any word processor) and a timer for the read-aloud test.

When to use

  • Writing any Shorts script or long-form outline.
  • Reviewing an existing script for retention before recording.
  • Checking disclosure and discovery rules before publishing an AI-assisted video.

Hard rules

  • Hook in the first moments: an immediate problem or benefit, spoken and on screen. Visible proof in the first seconds — never a talking-head-only open with no demonstration.
  • Never promise automatic monetisation, guaranteed views, viral outcomes, or income. Promise only what the video actually delivers.
  • AI disclosure: realistic AI-generated or significantly altered content needs the platform's disclosure — see "Discovery and disclosure rules" below, and check YouTube's current help page before each upload, because the rule changes.
  • Music rights: voiceover only, or voiceover plus royalty-free music. Never use a commercial song or original clip audio at any volume — low volume does not avoid a Content ID claim.
  • One call to action per video. One thing the viewer should do next.
  • The on-screen headline and the opening spoken phrase carry the primary search phrase — the words a viewer would type to find this video.

Three definitions used throughout

Read-aloud test. Read the finished script out loud, at natural speaking pace, with a timer running. The script passes if (a) the read time lands inside the target duration, (b) no sentence makes you stumble or run out of breath, and (c) it sounds like something a person would say, not something written to be read. Any sentence that fails gets rewritten, not performed harder. Run this test before recording — never after.

Save-worthy asset + future-moment anchor. Every script must contain one thing worth saving (a prompt, a checklist, a template, a formula — something the viewer can use later) and one line that names the future moment they will use it ("the next time a leaf turns yellow, open this"). The asset gives the viewer a reason to save; the anchor gives them a reason to remember when. If a script has neither, add one before recording.

Caption adds to the visual, never repeats it. On-screen captions highlight the key word or phrase the viewer should remember; they do not transcribe everything being said. If the caption and the voiceover say the same words at the same time, delete the caption or shorten it to the keyword. See the caption spec below.

Duration math (a rough estimate, not a measurement)

Estimate duration as word count ÷ 150 words per minute. This is a rough estimate only: natural delivery varies roughly 130–170 words per minute depending on speaker, pauses, and emphasis, so a 150-word script reads in about 52–69 seconds. Always confirm with the read-aloud test — the estimate plans the script, the timer decides it.

TargetWord budget at 150 wpm
30-second Short60–80 words
45-second Short100–115 words
60-second Short135–155 words
10-minute long-form1,300–1,500 words

For a Short, hand-count the words. Do not trust any tool's word count without checking it.

Shorts structure (up to 60 seconds)

  1. 0–3s hook: problem or benefit, spoken and on screen (3–8 words on screen).
  2. 3–15s proof: show the result or the tool working — no talking-head-only open.
  3. 15–45s steps: visible steps, one per beat, numbered on screen.
  4. 45–55s caveat: one limitation, honestly stated.
  5. 55–60s call to action: one action (save, try the prompt, comment the tool).

Shot-by-shot timing table (60-second Short)

One shot per information beat; a shot holds as long as the information needs, roughly 3 seconds or more per shot. Cut on every information change — a new step, a new number, a new visual proof — never on a timer alone. Background movement stays slow; rapid cuts and fast pans strain the eye and break the connection with the viewer.

TimeBeatWhat the viewer seesSpoken / on-screen
0:00–0:03HookThe problem, visual first (e.g. an empty inbox, a stalled screen)Hook line + 3–8 word headline
0:03–0:08Proof, part 1The result working on screen"Here is what changed"
0:08–0:15Proof, part 2The result, second angle or closer lookOne-sentence payoff
0:15–0:25Step 1Step 1 demonstrated, numbered on screenStep 1, one sentence
0:25–0:35Step 2Step 2 demonstrated, numbered on screenStep 2, one sentence
0:35–0:45Step 3Step 3 demonstrated, numbered on screenStep 3, one sentence
0:45–0:55CaveatThe limitation, stated plainly on screen"It won't work if…"
0:55–1:00Call to actionThe save-worthy asset on screenOne action, one sentence

For a 30-second Short, compress to hook (0–3s), proof (3–10s), one or two steps (10–22s), caveat (22–27s), call to action (27–30s). Never compress by dropping the caveat.

Worked example: complete 60-second Shorts script

Topic: three mistakes that kill houseplants. Word count: 147 words. Estimated duration at 150 wpm: ~59 seconds. Verify with the read-aloud test.

On-screen headline (0–3s): "Your plant is dying. You did this."

VO: "Your plant was fine when you brought it home. Now the leaves are yellow, and you have no idea why. Step one: stop watering on a schedule — water only when the top two centimetres of soil are dry. A calendar does not know your plant.

Step two: move it out of the dark corner — most houseplants need bright light that never touches the leaves directly. If you cannot read a book there at noon, it is too dark.

Step three: stop repotting a struggling plant — new soil does not fix overwatering. Fix the water first, then wait two weeks.

One honest limit: a plant with rotted roots cannot be saved by any trick. If the roots are black and soft, start again with a cutting.

Save this for the next time a leaf turns yellow — that is the moment you will need it."

Check against the structure: hook 0–3s ("Your plant is dying. You did this."); proof 3–15s (the three mistakes, and the fix for each); steps 15–45s (three numbered steps); caveat 45–55s (rotted roots cannot be saved); call to action 55–60s (save it). Save-worthy asset: the three fixes. Future-moment anchor: "the next time a leaf turns yellow".

Retention-review checklist

Run this on every script before recording. Any "no" is a rewrite, not a note.

  • Hook names a problem or benefit in the first 3 seconds. Not a greeting, not an introduction, not "welcome back".
  • Proof appears by 15 seconds. The viewer has seen the result or the tool working, not just heard about it.
  • One idea per beat. Each section does one thing. If a section needs the word "and also" twice, split it.
  • A re-hook or pattern interrupt every 15–20 seconds. A new visual, a number on screen, a question, a change of shot — something that resets attention.
  • No dead stretch longer than 5 seconds without a new visual, a number, or a spoken turn.
  • Caveat present and honest. One real limitation, stated plainly.
  • One call to action only. Not two, not "like and subscribe and comment and save".
  • Read-aloud test passed (time in range, no stumbles, sounds spoken).
  • Save-worthy asset named on screen and a future-moment anchor spoken.
  • Every factual claim has a source. No claim without one.
  • Captions add, never repeat (see the caption spec).

Worked retention review (applied to the example script above)

CheckVerdictEvidence
Hook in first 3sPass"Your plant is dying. You did this." — problem, 7 words
Proof by 15sPassThe three mistakes named, by ~12s
One idea per beatPassThree steps, one action each
Re-hook every 15–20sPassNumbered steps at ~15s, ~25s, ~35s; the light test at ~30s is a pattern interrupt
No dead stretch over 5sPassEvery beat changes the on-screen text or visual
Caveat presentPass"A plant with rotted roots cannot be saved by any trick"
One call to actionPassSave only
Read-aloud testMust run147 words ≈ 59s at 150 wpm; confirm by timing
Save-worthy asset + anchorPassThe three fixes; "the next time a leaf turns yellow"
Claims sourcedPassNo statistics or factual claims made — advice only
Captions add, never repeatPassOn-screen text is the headline and the step numbers, not a transcript

Drop-off points this review would have caught if the script had them: a greeting before the hook, a step that runs past 12 seconds without a visual change, or a second call to action ("and subscribe") after the save ask.

Caption / subtitle spec (1080×1920)

This is a recommended spec for vertical video, not a platform rule. YouTube does not mandate caption styling; these values keep captions readable on a phone.

  • Canvas: 1080×1920 (9:16).
  • Safe zones: keep all caption text inside the central safe area — at least 120 px from the left and right edges, at least 250 px from the bottom (the bottom is covered by the video title, buttons, and progress bar in the Shorts player), and at least 150 px from the top. Never place captions under the right-hand action buttons (like, comment, share).
  • Font: a bold sans-serif (for example Inter Bold, Arial Bold, or Helvetica Bold). One font for the whole video.
  • Size: 72–96 px cap height at 1080 px width for the main caption line; the hook headline may go larger (110–140 px) if it stays inside the safe zone.
  • Words per caption: 2–4 words per caption event; one line where possible, two lines maximum. Never one word at a time through function words ("the", "a", "and" alone on screen).
  • Style: high-contrast fill (white or near-white) with a thick dark outline or a semi-opaque dark box behind the text. Keyword colour only on the one key word per caption.
  • Timing: captions appear on the spoken word, not before it; each caption lasts as long as the phrase it carries. No caption event overlaps a full-screen graphic or card window.
  • Spelling: caption words are the script words, spelled exactly as in the script. If a voiceover tool mishears a word, the caption keeps the script spelling.
  • Separate file: for long-form, also export a separate SRT caption file (one caption per phrase, same 2–4 word rule where practical).

Long-form structure (8–15 minutes)

  • Title and thumbnail promise must match the video's actual payoff. A mismatch is a retention and trust failure, not a clever hook.
  • Chapters every 2–3 minutes, with spoken keywords and on-screen chapter titles.
  • Retention checkpoints every 60–90 seconds: a re-hook, a result, a question, or a new visual — something that earns the next minute.
  • Captions throughout (see the spec above).
  • Analytics to review after publishing: impressions, click-through rate, chose-to-view, average view duration, percentage viewed, retention curve, returning viewers. See the bands below.

Long-form script template (full worked example)

Topic: "How to brew pour-over coffee at home" — 10-minute tutorial, ~1,450 words. Timestamps are targets; confirm with the read-aloud test.

0:00–0:30 — Hook. On screen: "Bitter coffee? It is not the beans." Spoken: "Your pour-over tastes bitter no matter which beans you buy. The problem is not the bag — it is your grind. In the next ten minutes you will brew a cup that tastes sweet, using three numbers you already own."

0:30–2:00 — Chapter 1: Why coffee tastes bitter. Spoken: the three real reasons a pour-over turns bitter (grind too fine, water too hot, pouring too slowly) and why none of them means bad beans. On screen: the three reasons as a simple list. Re-hook at 1:30: "The mistake is blaming the beans for a grind problem."

2:00–4:30 — Chapter 2: Grind size. Spoken, with each setting shown on screen as it is explained: coarse like sea salt for a slow drawdown, medium like sand for a balanced cup, fine like table salt only for a fast brewer — and how to test yours with one brew. Worked example read aloud in full.

4:30–6:30 — Chapter 3: Water temperature. Spoken: when to use water just off the boil (93°C) and why cooler water under-extracts — and why giving the coffee a number beats guessing. On screen: the temperature, word for word.

6:30–8:30 — Chapter 4: What not to do. Spoken: three mistakes that ruin a cup — the stir that disturbs the bed, the pour that floods the sides, and the extra scoop added out of panic — with one line each on why they backfire. Re-hook at 7:30: "The worst pour-over is the one that adds more coffee before fixing the grind."

8:30–9:30 — Chapter 5: The honest limit. Spoken: technique cannot save beans that were never fresh — stale beans, wrong roast, bad storage. How to tell the difference, and when to buy a new bag.

9:30–10:00 — Close and call to action. Spoken: recap in three lines (grind, temperature, pour), then the save-worthy asset — "The brew ratio card is in the description — copy it, and use it for your next morning cup." One action only: save the card.

Check against the checklist: hook names the problem in 30 seconds; proof (the three numbers) arrives by 2:00; re-hooks at 1:30 and 7:30; one idea per chapter; caveat at 8:30; one call to action; save-worthy asset (the ratio card) with a future-moment anchor ("your next morning cup").

Discovery and disclosure rules (verified 16 November 2026)

Check YouTube's current help pages before every upload — these rules change. What follows was verified on 16 November 2026 against YouTube's own pages and announcements as reported in November 2026 guides.

How Shorts are discovered. YouTube says Shorts are ranked on performance and viewer personalisation. The signals it names, in order: (1) whether viewers choose to watch or swipe away (the "chose to view" rate); (2) whether they stay — average view duration and average percentage viewed; (3) whether they enjoyed it — likes and post-watch survey answers. Personalisation uses each viewer's history: topics watched, channels, and sounds. Topic interest, competition, and seasonality also move a Short's numbers. YouTube says its system has no opinion about what type of Short you make, and there is no minimum posting cadence required to perform well.

How views are counted. Since 24 August 2026, a view counts from the first frame of playback across formats. For Shorts analysis, use engaged views (views where the viewer stayed past the first seconds, not counting loops), average view duration, and average percentage viewed — raw views are now an exposure count, not an attention metric.

AI disclosure. YouTube requires disclosure when a video contains realistic content that was generated or significantly altered with AI and a viewer could mistake it for real: a real person shown saying or doing something they did not, footage of a real event or place altered, a realistic scene that never happened, or AI-generated music carrying the video. You do not need to disclose for: an AI-written script, AI help with a title or thumbnail, filters, colour grading, captions, upscaling, or your own cloned voice used for voiceover. Set it in YouTube Studio at upload, under the "altered or synthetic content" (now labelled "AI use") question. Since 27 May 2026, YouTube may also add the label itself — for content made with YouTube's own AI tools, content carrying C2PA metadata, or content its systems detect as photorealistic AI. The label appears as an overlay on Shorts and below the player on long-form. YouTube says disclosing does not change recommendations or monetisation; failing to disclose realistic content can lead to removal or suspension from the Partner Program.

Sources checked 16 November 2026: YouTube Help, "Disclosing use of altered or synthetic content"; YouTube Help, "Search and discovery tips for Shorts"; YouTube blog, 27 May 2026 (AI labels); YouTube blog, August 2026 (view counting). Secondary reporting consulted: https://www.clyper.io/guides/youtube-shorts-algorithm, https://www.vidpal.ai/blog/how-the-youtube-shorts-algorithm-works-2026, https://stripshot.app/blog/ai-labels-by-platform, https://hypefox.app/blog/ai-label-youtube-instagram-tiktok/

Analytics bands (guidance, not platform fact)

YouTube publishes no "good" thresholds. The bands below are practitioner guidance for diagnosing a video — use them to decide what to fix, not as promises. Shorts and long-form are never compared against each other; compare a video against your own channel's median for the same format.

Metric (Shorts)StrongAverageWeak — fix this
Average percentage viewedOver 80%50–80%Under 50% — tighten the hook and cut dead beats
Chose-to-view ("stayed to watch")Over 70%50–70%Under 50% — the first 2 seconds fail
Average view duration (60s Short)Over 40s25–40sUnder 25s — viewers leave before the steps
Likes per 100 viewsOver 41–4Under 1 — the payoff or the ask is weak
Metric (long-form)StrongAverageWeak — fix this
Click-through rateOver 8%3–8%Under 3% — rework title and thumbnail
Average percentage viewedOver 50%30–50%Under 30% — restructure the opening
Audience retention at 30sOver 70%50–70%Under 50% — the hook does not pay off

Judge by rates, not raw counts. A video with 200 views and 80% average viewed teaches you more than a video with 20,000 views and 25% viewed. Wait for at least 24 hours after publishing before reading retention — YouTube Analytics lags, and early numbers are noisy. Do not explain weak numbers with "shadowban", "probation", or "test pool" theories; the data is the data.

Failure modes

  • Hook is a greeting. Fix: cut everything before the problem sentence.
  • Proof arrives after 15 seconds. Fix: move the demonstration up; cut the setup.
  • Two calls to action. Fix: keep the one that matches the video's promise; cut the other.
  • Script reads fine but sounds written. Fix: run the read-aloud test; rewrite any sentence you stumble on.
  • Captions transcribe everything. Fix: shorten each caption to the keyword; delete captions that duplicate the voiceover word for word.
  • A claim with no source. Fix: find the source or cut the claim. Never ship it on trust.

Known limits

  • Duration estimates are rough (±15% around 150 wpm). The read-aloud test is the measurement.
  • The analytics bands are practitioner guidance, not YouTube-published thresholds. Treat them as diagnostic prompts.
  • Discovery and disclosure rules change. The section above is dated 16 November 2026; re-check YouTube's help pages before relying on it for a new upload.
  • This skill covers scripting and retention. It does not cover filming, editing, thumbnail design, or channel strategy.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

関連スキル