promo-script
Skill1 starsChanged 45 days agoMITView on GitHub
Plan and write the script and shot list for a promo or explainer video in a product promo harness run folder (shotlist.json with anchors on beats, words and shot edges, VO in the pack's register, anti-Claudism rules, a claims ledger, app truth). Use when writing or revising a video script, voiceover, storyboard, beat sheet or shot list for `promo`.
In this repository4 other files it gives its agents.
- promo-captionsSkill
- promo-criticSkill
- promo-videoSkill
- promo-voiceSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Write everything into shotlist.json.
- Very specific: line 60
Every number cites a claim in claims ({"id", "text", "source"}).
- Distinctive: line 68
No invented numbers; number density capped by register.
- Distinctive: line 75
Write lines a TTS voice can say and speech recognition can score: no bare interjections ("Psst." cannot be verified.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
promo-script
Order of work: brief → story (logline, the one cause→effect, the proof) → one visual concept and one everyday
analogy → structure from the pack's arc → VO in the pack's register → on-screen text by text mode → the shot list.
Write everything into shotlist.json; promo script renders the readable script.md from it, so text never
exists in two places. Worked example: examples/promo/harness-launch/shotlist.json (music-led: bars, beat-anchored
events, each event naming its sound effect).
Arcs
- Promo (ad packs): hook in 2 s or less (the problem in 5 words or fewer of huge type, or the product doing its job) → the product appears, UI assembles → feature chapters, each with the cursor doing a real action → one sourced proof → recap or dark beat → logo and CTA. A new visual payoff every 2-4 s.
- Explainer (
professorregister): hook, familiar world, disruption, mechanism, discovery, consequence, recap. Every scene adds understanding. One central cause→effect.
Timing modes (timing_mode)
music: chapters havebars; the grid comes frommusic.bpm, then from the measured bed afterpromo musicorpromo beats. Cuts land on beats.voice: the VO leads. Lines follow each other ({"after": id, "gap": s}); shots takesecondsor share what the lines need. No music is required.music.styleoverrides the pack's mood, instrumentation, arrangement and negative lines for this film.- A music prompt carries musical words only: each section's note is its shots'
sound.music_cuevalues (else "continue the groove"), never the chapterpurpose. Write cues as musical moves ("riser into the drop");promo musicstrips AI, agent, model and brand names from them, which Lyria's policy filter can block.
Every shot states
visual (composition, objects, camera, and locked: what must NOT move), motion (entrance, primary,
secondary, exit), reads (what the viewer must understand, from and to anchors; the key beat mid-shot),
events (every visible change, anchored, with sfx where it should sound), sound (music_cue, ambience),
transition_out (kind, the visible carrier object that becomes the next scene, and its meaning), and
handoff_out/handoff_in numbers at seams (element, x, y, scale, opacity, direction, speed).
Anchors, never stopwatch times
- Chapters:
{"bar": n}(music mode) withbars; VO lines{"beat": n}or{"after": id, "gap": s}. - Events and reads:
{"beat": n},{"line": id, "word": "Papers", "offset": -0.03}(the start of the word that names the thing; punctuation and case are ignored,nthpicks a repeat, a part of a hyphenated word works),{"shot": id, "edge": "start", "offset": 0.4}.{"t": s}only when nothing else fits (it warns). - Something must happen at least every
payoff_interval_s(pack), and the hook must land by 2 s after pre-roll.
Registers
ad-sparse(the saas-kinetic default): 1-2 lines a chapter, 12 words a line at most, question→answer allowed, 35-45% VO coverage.ad-dense: second person, conversational, 65-80% coverage, pairs withverbatim-synctext. The shot list does not carry a register yet: lint a dense film withpromo lint-script --register ad-dense.professor: 125-145 wpm, complete sentences explaining cause and effect, concrete words before technical terms, analogies before figures, 60-75% coverage. Do not duplicate narration on screen.
App truth and claims
- Every number cites a claim in
claims({"id", "text", "source"}); the line lists it inclaims. - Copy, counts, scores and identifiers shown on screen are the app's real ones, computed from the app's own code or data. Never invent UI, citations or lookup results. When the story needs a state the app cannot reach, change the story, not the app.
- Competitor names never appear on screen or in VO; frame them out.
Anti-Claudism (enforced by promo lint-script)
No invented numbers; number density capped by register; no "it's not X, it's Y" or "not just X but Y"; no
filler triplets; no em dashes; no stacked fragment runs outside ad headlines; no hype words; no rhetorical
openers ("Imagine…", "Meet the future of…"); vary sentence length. Then run all public copy (VO, headlines, end
card) through the humanizer skill.
Voice-friendly lines
Write lines a TTS voice can say and speech recognition can score: no bare interjections ("Psst." cannot be
verified; the user replaced it with "Hey there, fellow researcher!"). Brand words that are said differently from
their spelling go in pronounce (see promo-voice).
Loop
promo lint-script and promo timing must both be clean (errors block; read every warning). Before any take
exists, promo timing estimates line lengths from the pack's pace. Then promo script and ask the user to
approve script.md before any audio or picture work.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

