Ship promo

Ship Promo

Purpose

Produce a short, benefit-first promo video plan from what the project just shipped. The shipping log says what changed; the user guide says how it works; this skill says how to SHOW it in 30–60 seconds. Output is three planning artifacts plus generator-ready prompts — not a rendered video. Rendering is delegated to whatever tool the user already has, through adapters (see references/generator-adapters.md). The skill never assumes a generator exists.

Part of the ship pack

One member of the cross-project "ship" toolkit, all sharing the docs/VERSION anchor:

docs/VERSION              ← single source of truth (semver)
docs/brand.json           ← brand-as-data (colors + fonts) — themes every output
   ├─ ship-changelog / shipping-log → docs/SHIPPING-LOG.md   (WHAT shipped → promo source)
   ├─ ship-guide / user-guide-builder → docs/.../guide        (HOW it works → promo claims)
   ├─ ship-screenshots / screenshot-capture → screenshots/    (real app frames for the storyboard)
   ├─ ship-logos / logo-pack → docs/brand/logos/              (brand mark for the end card)
   └─ ship-promo (this)   → docs/promo/                        (script + shotlist + storyboard)

Source priority: the shipping log is the spine (it is already benefit-first). Pull supporting claims from the guide, and prefer real screenshots over generated frames whenever they exist — they are the most honest, on-brand footage available.

Workflow

1. Discover what already exists. Never act blind. From the repo root:

   node "<skill-dir>/scripts/discover-promo.mjs" --pretty
   

   It reports (as JSON): docs/brand.json (parsed colors + fonts, or a flag if missing), docs/VERSION, the changelog / guide / screenshots / logos it found, any prior docs/promo/* outputs (so you update instead of clobber), and a gaps list of missing inputs. Read it before writing anything.

2. Choose the angle and length. Default is a 45-second "what's new" promo for the current docs/VERSION. Honor the user's ask: a feature spotlight, a 15s social teaser, a 60s investor/launch sizzle, or a "since v0.x" range. Pick one spine message (the single thing a viewer should remember) and 3–5 proof beats that back it. More is worse.

3. Gather evidence. Read the changelog/guide the discovery step found. Every claim in the script must trace to a shipped item — no invented features, no "AI-powered" filler. If the changelog is thin or absent, say so and offer to run /ship-changelog first rather than padding with generic lines.

4. Write the script + shotlist + storyboard. Follow references/promo-format.md exactly (structure, timing math, the beat taxonomy, and a full worked example). Produce three files under docs/promo/ — see Outputs. Keep the voiceover in the brand voice: benefit-first, second person, concrete, no hype words from the ban list.

5. Attach generator prompts. For each shot, write a tool-agnostic image/video prompt into the shotlist, themed by brand.json colors. Then map them to the user's actual tools using references/generator-adapters.md — emit a runnable command block per available adapter (Ad Lab, Directors Palette, local Ideogram/Wan, etc.). Mark adapters you could not confirm as "not detected — install or swap," and never fabricate a command for a tool that isn't there.

6. Render the storyboard page (optional). If the user wants something to look at / share, build a self-contained docs/promo/storyboard.html from references/storyboard-template.md, themed from brand.json. It must be a single file, no build step, :root CSS variables only, never purple by default, and must NOT use backdrop-filter or SVG feTurbulence (both hang renderers). Embed real screenshots where they exist; use prompt text as placeholders where they don't.

7. Report. State the angle, the length, the spine message, the files written, which generator adapters were detected, and the honest gaps (e.g. "no screenshots for the Finance shot — run /ship-screenshots"). If you used a stale changelog, say so.

Outputs

All under the project's docs/promo/ (create it if absent — mkdir -p docs/promo):

File	What it is
docs/promo/voiceover.md	The spoken script: titled beats with timecodes, word counts, and an estimated read time at ~2.6 words/sec. Plain, speakable sentences.
docs/promo/shotlist.md	A timed table — every shot's t_start–t_end, on-screen action, the VO line it carries, on-screen text/lower-third, and a generator prompt. The production spine.
docs/promo/storyboard.md	Beat-by-beat outline: the narrative arc (hook → proof → payoff → CTA), pacing notes, music/energy curve, and which shots are real screenshots vs. generated.
docs/promo/storyboard.html	(optional) A shareable, on-brand visual board of the above.

Use the bundled estimator so timings are consistent, not guessed:

node "<skill-dir>/scripts/estimate-timing.mjs" docs/promo/voiceover.md

It returns per-beat word counts, read times (~2.6 wps), cumulative timecodes, and a total — and warns if the total overshoots the target length so you can trim before storyboarding.

Brand & theming

• Read docs/brand.json for colors and fonts. Use them for any on-screen text spec, lower-thirds, end card, and the HTML board. If brand.json is missing, fall back to the project's landing page / Tailwind config / logo, and say in your report that you inferred it.
• Never default to purple/indigo. If the brand has an explicit "no purple" rule, honor it.
• The end card uses the brand wordmark/logo from docs/brand/logos/ if present, the tagline from brand.json, and the brand accent for the CTA.

Quality bar

A promo plan passes only if every line is true:

• One spine message, 3–5 proof beats. If you can't name the single takeaway in a sentence, the plan fails. Cut everything that doesn't serve it.
• Every claim traces to a shipped item in the changelog or guide. No invented capabilities, no roadmap-as-fact, no implied security/compliance you can't cite.
• Benefit-first, second person, concrete. "Send a change order in two taps" beats "streamline your workflow." Show the noun (the actual feature), not the adjective.
• Banned filler: revolutionary, game-changing, seamless, robust, cutting-edge, unlock, supercharge, leverage, elevate, next-level, "AI-powered" as a standalone selling point. If a line still works with the word deleted, delete it.
• Timing is computed, not vibes. Word counts → read time → timecodes via the estimator; the total fits the target length (with ~10% headroom for breaths and music tails).
• Shotlist is shootable. Each shot says what's on screen, what's said, and how to make the frame (real screenshot path OR a specific, brand-colored generator prompt). No "show the app looking great."
• Honest about gaps. Missing screenshots, thin changelog, undetected generator — named in the report, not papered over.

Honest handling of missing inputs

• No changelog/guide → don't invent. Offer /ship-changelog first; if the user insists, build only from git log + README and label the plan "draft — claims unverified."
• No brand.json → infer from landing page/logo, write a minimal one, note the inference.
• No screenshots → use prompt placeholders in the storyboard and flag the shots that would be stronger with real frames (/ship-screenshots).
• No generator detected → still write the prompts; mark every adapter "not detected" and list what to install. The plan is useful even with zero generators present.

Reusable contents

• scripts/discover-promo.mjs — inventories brand/version/changelog/guide/screenshots/logos/ prior promo outputs and reports gaps. Run first; don't reinvent.
• scripts/estimate-timing.mjs — word-count → read-time → timecode estimator for the script.
• references/promo-format.md — script/shotlist/storyboard structure, timing math, beat taxonomy, voice rules, and a full input→output worked example. Read before writing.
• references/generator-adapters.md — tool-agnostic prompt spec + per-tool command mappings (Ad Lab, Directors Palette, local image/video). Adapters, not assumptions.
• references/storyboard-template.md — the self-contained, themeable storyboard.html template (no backdrop-filter, no feTurbulence, never purple) and how to fill it.