ads-video-library
Name, store and catalogue finished ad videos — canonical file names, a poster frame for every video (optionally baked in as frame 0 so feeds and chats show it as the thumbnail), contact sheets for QA,
SKILL.mdskills/ads-video-library/SKILL.md
GitHubAds video library
Where finished ad creatives live, what they are called, and how a team reviews and finds them again. Rendering is someone else's job; this skill starts the moment an mp4 exists.
One command does everything:
python3 ${CLAUDE_SKILL_DIR}/scripts/publish.py manifest.json --catalog catalog.csv
- Names every file canonically — the name says what the file is without opening it.
- Pulls a poster — the strongest settled frame (text fully in, nothing mid-transition) →
<name>.jpg. - Makes a contact sheet — six stills across the video →
<name>.sheet.jpg, for QA. - Stores the video and poster under
<Month> / <LANG 🏳> / <Video type>— in a local folder (default) or on a Google shared drive. - Writes the catalogue —
catalog.csv, the source of truth, plus a Google Sheet tab if configured. - Writes
dist/gallery.html— a review page: every video with its poster, fields and contact sheet, and approve / reject / note buttons. "Copy review" puts the verdicts on the clipboard to paste back here.
Run --dry-run first on any batch you haven't published before: it prints the names, the folders and the chosen poster times, and touches nothing.
Needs FFmpeg (ffmpeg, ffprobe) on PATH. Google Drive mode also needs pip install google-auth requests.
The manifest
The generating agent writes it; it is the only file that knows anything about the batch:
{
"type": "motion",
"label": "Motion Cards",
"lang": "en",
"extras": ["headline", "cta", "caption"],
"items": [
{"topic": "hr-interviews", "src": "renders/hr.mp4", "voice": "female",
"headline": "An AI scheduler for recruiters", "cta": "Try for free",
"caption": "Candidates pick an interview slot in their own time zone. No back-and-forth emails."}
]
}
type goes into the file name, label is the folder and the Sheet tab, extras are the columns this type carries beyond the core set. Per item topic, src and voice are required; poster_at (seconds) overrides the automatic poster pick. Full contract: references/manifest.md.
Configuration
library.json in the working folder (or ~/.config/marketing-agent-kit/video-library.json):
{"storage": "local", "local_root": "~/Ads Video Library"}
For Google Drive: {"storage": "gdrive", "drive_id": "<shared drive id>", "sheet_id": "<optional sheet id>"} — setup in references/setup.md. Without a config file the skill uses local storage in ~/Ads Video Library.
Posters and frame 0
Read references/posters.md. In short:
- Almost every player and feed shows frame 0 as the idle thumbnail, and frame 0 of an ad is usually a fade or a half-drawn title.
--bake-posterreplaces only frame 0's pixels with the poster: same duration, same frame count, audio untouched, invisible on playback — but every thumbnail grabber now shows a real frame. - Platforms that accept a custom thumbnail upload (Meta, TikTok, YouTube, the LinkedIn post editor) get the
.jpg. - Look at the posters and contact sheets before reporting. Automatic picking is a good default, not a guarantee. If a poster lands on the wrong moment, set
poster_atfor that item and re-run.
Review loop
- Publish → open
dist/gallery.html(or send it to the reviewer with thedist/folder). - The reviewer approves, rejects and leaves notes, then clicks Copy review and pastes the text into the chat.
- Update each item's
status(approved/rejected) andnotesin the manifest, fix the rejected ones, re-runpublish.py. The catalogue and the gallery update; links stay valid.
Read before publishing a new video type
references/naming.md— the name, field by field, and why the catalogue never joins on itreferences/storage.md— folder layout, what belongs in the library and what doesn'treferences/manifest.md— the manifest contractreferences/setup.md— Google credentials, and what to do when Google stops trusting themreferences/posters.md— posters, frame 0, contact sheets, captions
What this skill won't decide for you
- The type slug and label. A new format is a new folder beside the existing ones. Keep the slug short, lowercase, no underscores — underscores separate fields in the name.
- What belongs in
extras. A column is worth adding when someone choosing a creative to run would sort or filter on it: the headline, the CTA, the hook, the caption. Not the render settings.
Things that cost time to learn
- The catalogue joins on
id, never on the file name.idis<type>_<topic>_<lang>_<aspect>_<voice>and survives re-renders, new dates, new lengths and new versions; an EN and an ES cut, or a 16x9 and a 9x16 cut, are separate ids. Ad performance joined on a file name splits one creative's history in two. - Length and date are in the name, so a re-render renames the file. The publisher retires what is in the type's folder and not in the batch — locally into
_retired/, on Drive into the trash. Skip it with--no-sweepand the folder fills with older renders, all looking current. createdis remembered for an id already in the catalogue. Always pass--catalog: without it the publisher has no memory and every run stamps today.- Two items with the same id or the same name is a refusal, not a warning. Two render projects producing the same basename once shipped the wrong screen inside a card for a week.
- One
catalog.csvfor the whole library. A batch replaces its own rows and leaves other types and languages alone; columns you added (spend, CTR) are kept. Rows whose files the sweep just retired getstatus=retired. - A Sheet tab is overwritten wholesale. The CSV is the source of truth; anything typed into the tab by hand is gone on the next run.
- Drive: a service account can only write to a shared drive (it has no storage of its own), and every call against a shared drive needs
supportsAllDrives. Details inreferences/setup.md.
Adapt it
- Add your languages to
"langs"inlibrary.json({"sv": "SV 🇸🇪"}). - Write a small manifest generator in your render project: it is the only project-specific part. Everything after it is this skill.
Poster selection and the frame-0 technique are adapted from /brag (MIT).