CommunityWriting & Editinggithub.com

youtube-packaging

Turn a finished YouTube video, script or transcript into the upload package, every part checked by code. 3 title options, a description with chapters YouTube accepts (starting at 0:00, three or more, none shorter than 10 seconds), a pinned comment that asks a question, an SRT subtitle file with clean line lengths, and 3 finished thumbnails (1280x720 PNGs from the video's own frames, six layouts, checked for contrast and phone-size readability, made for YouTube's Test and compare). Use when the user says "write my title and description", "YouTube description with chapters", "make chapters", "timestamps for my video", "make an SRT", "subtitles from this transcript", "pinned comment", "make my thumbnail", "thumbnail for this video", "thumbnail text", "package this video", "get this ready to upload", or has a finished video, long-form script, transcript or word timings to publish.

What is youtube-packaging?

youtube-packaging is a Claude Code agent skill that turn a finished YouTube video, script or transcript into the upload package, every part checked by code. 3 title options, a description with chapters YouTube accepts (starting at 0:00, three or more, none shorter than 10 seconds), a pinned comment that asks a question, an SRT subtitle file with clean line lengths, and 3 finished thumbnails (1280x720 PNGs from the video's own frames, six layouts, checked for contrast and phone-size readability, made for YouTube's Test and compare). Use when the user says "write my title and description", "YouTube description with chapters", "make chapters", "timestamps for my video", "make an SRT", "subtitles from this transcript", "pinned comment", "make my thumbnail", "thumbnail for this video", "thumbnail text", "package this video", "get this ready to upload", or has a finished video, long-form script, transcript or word timings to publish.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrielebolognese/youtube-packaging/tree/HEAD/skills/youtube-packaging

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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 text lines, 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 written 1: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 as work/frames/f01.png ...; open work/frames.jpg and 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 writes out/thumb-a.png and onward and out/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). Open thumbs.jpg, fix every failure (shorter text, "shade": 0.65, another layout or picture) and render again.

6. Description

In this order:

  1. 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.
  2. Summary: one short paragraph (at most 900 characters) of what the viewer gets. Plain sentences, no list.
  3. Resource line (only if the video promises one): what it is, then the link or [LINK].
  4. Chapters: one per line, 0:00 Title.
  5. 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 (or duration: in the file) checks the last chapter; without it the end of the last subtitle is used. --source checks that every number in a title or thumbnail text appears in the video and that the opening shares words with each title. --earlier blocks a repeated description.
  • FAIL must be fixed; WARN fixed or explained. Exit code 0 means nothing failed (--strict also fails on warnings, --json prints 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

  1. 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.
  2. The .srt file and the three thumbnail PNGs (out/thumb-a.png, -b, -c), with out/thumbs.jpg.
  3. 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.
  4. 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).

Related Skills