YouTube packaging
Turn a finished video's script or transcript into everything the upload needs: titles, description with chapters, pinned comment, subtitles and three thumbnails. Any niche, any length (built for long-form, works for shorter videos too).
The scripts are in the scripts/ folder next to this SKILL.md. Run them with python (3.10 or newer)
using the absolute path of that folder. check_package.py and make_srt.py need nothing else; the
thumbnails (thumbs.py) need Pillow, numpy and Playwright with Chromium
(python -m pip install pillow numpy playwright then python -m playwright install chromium), and
ffmpeg when the frames come from a video file.
1. Gather the inputs
- The words of the video, best first: word timings as JSON (from a transcription tool with word
timestamps), a timestamped transcript (
0:12 textlines, a copied YouTube transcript, an SRT or VTT), or the script alone (then every time is an estimate; say so). - The final length of the video (for the last chapter and the subtitles).
- A resource or link the video promises, if any. Without the real link, write
[LINK]for the user to fill in. - Optional: earlier descriptions of the channel (so the new one does not repeat them), the working title or thumbnail idea, the audience.
2. Read the video first
Read the whole script or transcript and note: the promise made in the first 30 seconds, the main payoff, the sections and where each starts, the concrete numbers the video says, the most surprising moment. Every title, thumbnail text and description line must match what the video really delivers.
3. Chapters
- One chapter per section; its time is the first spoken word of that section. With word timings or a timestamped transcript, find each section's first words. With only a script, estimate (words before the section / words per minute) and mark the times as estimates to fix after the edit.
- YouTube's rules: the list starts at
0:00(the hook belongs to that chapter), holds three or more chapters, none shorter than 10 seconds, in time order, times from one hour on written1:05:00. A chapter under 10 seconds is folded into its neighbour. - A chapter title says what the section covers or asks, not what it concludes ("The watering mistake", not "Stop watering daily"); 2 to 6 words; no em dash.
4. Titles (3 options)
- Each option takes a different angle: the outcome, the problem or mistake, the curiosity gap or contrast. Put the words a viewer would search for early.
- At most 60 characters (YouTube allows 100, but longer titles get cut on phones and in search).
- The first 30 seconds of the video must confirm the title's promise; a title the opening does not back loses viewers in the first seconds.
- Numbers only when the video says them. No hashtags, links, hype words, or more than two words in capitals.
5. Thumbnails (3 finished images)
- The texts: at most 5 words, readable at phone size. The thumbnail adds to the title instead of repeating it: together they tell the story (title: the promise; thumbnail: the stakes, the result, the twist). Numbers only from the video.
- The pictures:
python <skill-folder>/scripts/thumbs.py frames VIDEO_OR_IMAGE_FOLDER work/keeps the sharpest, most different frames aswork/frames/f01.png ...; openwork/frames.jpgand pick the frame that shows the payoff (a face reacting, the result, the before and after). No video? Use the user's own pictures or screenshots in a folder; never a stranger's photo. - Write
work/thumbs.json: three variants that differ in ONE thing (the text, the picture or the layout), so YouTube's Test and compare tells which one works. Six layouts:simple,shock(zoom and ring),big-number,header,comparison(two pictures),blur(a reveal). Format, layouts and options (focus, highlight word, text side, brand colours): references/thumbnails.md. - Render:
python <skill-folder>/scripts/thumbs.py render work/thumbs.json out/ [--brand brand.json]. It writesout/thumb-a.pngand onward andout/thumbs.jpg: each variant big, as a YouTube home tile with the title, and at phone size, with its checks (1280x720 under 2 MB, at most 5 words, letters at least 54 px tall and still readable at phone size, the text inside the frame, contrast 4.5:1 against what is behind it). Openthumbs.jpg, fix every failure (shorter text,"shade": 0.65, another layout or picture) and render again.
6. Description
In this order:
- Opening: 2 lines, each at most 160 characters, shown before "...more". They say the promise again in fresh words for a person still deciding whether to click: not the title a second time, no link.
- Summary: one short paragraph (at most 900 characters) of what the viewer gets. Plain sentences, no list.
- Resource line (only if the video promises one): what it is, then the link or
[LINK]. - Chapters: one per line,
0:00 Title. - Optional: credits or links the creator always adds.
At most 5,000 characters in all. No hashtags by default (topics go in the tags), no hype words, no em dash, and no more than 30 percent of its three-word runs shared with an earlier description.
7. Pinned comment and tags
- Pinned comment: one question tied to the video's core problem or the viewer's next step, easy to answer in a word or a line. At most 200 characters, no link.
- Tags (optional): 3 or more, at most 500 characters in all, no
#and no comma inside a tag.
8. Subtitles
python <skill-folder>/scripts/make_srt.py words.json -o video.srt # word timings
python <skill-folder>/scripts/make_srt.py transcript.txt --end 18:42 -o video.srt # timestamped lines
python <skill-folder>/scripts/make_srt.py --validate video.srt # check an existing file
Cues: up to two lines of 42 characters, on screen for 1 to 7 seconds, cut at sentence ends first, then at commas;
a number stays with its unit and a name is never split; no overlap, at least 80 ms between cues. All
adjustable (--max-chars, --max-lines, --min-dur, --max-dur, --gap-ms). The report goes to
stderr; exit 0 means the file is clean. Timestamped lines without punctuation (raw auto-captions) are
cut by length and pauses only: punctuate the transcript first for better cues.
9. Check the package
Write the package in this Markdown format (JSON with the same keys also works:
titles, description, pinned_comment, thumbnail_texts, tags, duration):
---
duration: 18:42
---
## Titles
1. ...
2. ...
3. ...
## Description
```
Opening line one.
Opening line two.
Summary paragraph.
0:00 First chapter
...
```
## Pinned comment
...?
## Thumbnail text
1. ...
2. ...
3. ...
## Tags
tag one, tag two, tag three
Then run:
python <skill-folder>/scripts/check_package.py package.md --srt video.srt --source transcript.txt
python <skill-folder>/scripts/check_package.py package.md --duration 18:42 --earlier old-desc-1.txt old-desc-2.txt
--duration(orduration:in the file) checks the last chapter; without it the end of the last subtitle is used.--sourcechecks that every number in a title or thumbnail text appears in the video and that the opening shares words with each title.--earlierblocks a repeated description.FAILmust be fixed;WARNfixed or explained. Exit code 0 means nothing failed (--strictalso fails on warnings,--jsonprints machine-readable results).- Limits and the hype word list are in
scripts/package-rules.json; copy it, keep the keys to change, pass--rules my-rules.json(for example"allow_hashtags": true,"title_max": 70).
Fix every failure, run it again, then hand back.
10. Hand back
package.md: the three titles (mark your pick and say why in one line), the description ready to paste, the pinned comment, the three thumbnail texts, the tags.- The
.srtfile and the three thumbnail PNGs (out/thumb-a.png,-b,-c), without/thumbs.jpg. - Upload steps: paste the description (YouTube builds the chapters from its time lines), upload the
SRT as subtitles in the video's language, add the three thumbnails to Test and compare, replace any
[LINK], pin the comment after publishing, keep the last 20 seconds free for the end screen. - The checker's result line, and any accepted warning with its reason.
More detail on every rule, and why it exists: references/packaging-rules.md.
Worked example
examples/transcript.txt is the timestamped transcript of a 10:06 video about growing food on a small
balcony; examples/words.json holds word timings for its first 46 seconds.
python scripts/make_srt.py examples/transcript.txt --end 10:06 -o test-out.srt
python scripts/check_package.py examples/package.md --srt test-out.srt --source examples/transcript.txt
The first prints made 149 cues from 1497 words, 0:00.4 to 10:03.0 and srt: ok; the second ends
with Result: 0 failed, 0 warnings, 11 passed. Its titles take three angles (outcome: "Grow Real
Food on a Tiny Balcony (Even If Plants Hate You)"; method: "The One-Day Sun Test That Decides What
Your Balcony Grows"; problem: "Why Balcony Plants Die, and the Bucket Trick That Fixes It"), and its
thumbnail texts ("6 HOURS OR NOTHING", "IT WATERS ITSELF", "STOP KILLING PLANTS") each add something
the titles do not say. examples/package-weak.json shows the failures: a long title with a hashtag,
chapters starting at 0:05, a 6-second chapter, a pinned comment with a link and no question, an
8-word thumbnail (9 failed).