Ads 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

1. Names every file canonically — the name says what the file is without opening it.
2. Pulls a poster — the strongest settled frame (text fully in, nothing mid-transition) → <name>.jpg.
3. Makes a contact sheet — six stills across the video → <name>.sheet.jpg, for QA.
4. Stores the video and poster under <Month> / <LANG 🏳> / <Video type> — in a local folder (default) or on a Google shared drive.
5. Writes the catalogue — catalog.csv, the source of truth, plus a Google Sheet tab if configured.
6. 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-poster replaces 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_at for that item and re-run.

Review loop

1. Publish → open dist/gallery.html (or send it to the reviewer with the dist/ folder).
2. The reviewer approves, rejects and leaves notes, then clicks Copy review and pastes the text into the chat.
3. Update each item's status (approved / rejected) and notes in the manifest, fix the rejected ones, re-run publish.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 it
• references/storage.md — folder layout, what belongs in the library and what doesn't
• references/manifest.md — the manifest contract
• references/setup.md — Google credentials, and what to do when Google stops trusting them
• references/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. id is <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-sweep and the folder fills with older renders, all looking current.
• created is 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.csv for 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 get status = 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 in references/setup.md.

Adapt it

• Add your languages to "langs" in library.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).