agentleFS
sugatoraysugatoray/aiskills/skills/video-related/dynamic-promo-video/SKILL.md

dynamic-promo-video

Skill4 starsChanged 2 days agoMITView on GitHub

Build a short narrated promo/intro video (HTML scenes, zoom/tilt, voiceover, music) for a library, app or product. Use for explainer or launch videos made from code, real screenshots and TTS.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 2 are distinctive, and 6 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.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No research, storyboard or editing.

    line 45
  2. Distinctive:

    Use the project's real branding (banner, icon, colors, fonts) and real screenshots from its docs where possible.

    line 60
  3. Distinctive:

    Write one narration line per scene (about 2.5-3 words per second).

    line 66
  4. Very specific:

    Do not reuse a class name a script queries with querySelectorAll.

    line 73
  5. Very specific:

    Look at the preview frames before going on.

    line 79
  6. Very specific:

    Add --write-html index.html to write the new const NB = [...] into the page (or paste the printed line).

    line 88
  7. Very specific:

    Use a licensed track instead of music.py when the user supplies one.

    line 96
  8. Very specific:

    Look at frame 0, one frame per scene and the last frame in check/.

    line 103

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Dynamic promo video (HTML scenes + voiceover + music)

Produces a 1280x720, ~25-45s MP4: animated scenes in one HTML page, rendered frame by frame with Playwright, encoded with ffmpeg, narrated with a TTS voice (e.g. ElevenLabs), with ducked background music.

SKILL_DIR below means this skill's folder. Only the template is copied into the work folder; the scripts run from SKILL_DIR/scripts/ (each has --help). Needs Node + Playwright/Chromium (preinstalled in cloud sessions; do not reinstall), ffmpeg/ffprobe, Python 3 with numpy.

StepUse
Scenesassets/template/index.html · details: references/scene-engine.md
Real page screenshotsreferences/screenshots.md
Voiceoverreferences/voiceover.md · scripts/tts_elevenlabs.py, scripts/timing.py
Render + encodescripts/render.js
Music, mixscripts/music.py, scripts/mix.py · references/music-and-mix.md
Checkscripts/verify.py

Inputs

FlagMeaning
--demo, --demo=defaultBuild the default demo instead of a real project: a placeholder video, then how to make one with this skill; see Demo below.
--demo=selfBuild the self demo: the skill explaining itself (what it is, how it works, install, use).
--voiceNarrate with the default ElevenLabs voice TABZn6CDfjMNGrsnGzzD.
--voice-elevenlabs=<voice-id>Narrate with that ElevenLabs voice. A bare --voice-elevenlabs = --voice.
  • Narration uses ElevenLabs only if one route is available, checked in this order:
    1. the ElevenLabs MCP connector (its creative_generate_speech tool can be loaded with ToolSearch), or
    2. an API key: ELEVENLABS_API_KEY is set, or the session's network secrets hold one for api.elevenlabs.io (then run scripts/tts_elevenlabs.py).
  • Real project, no voice flag: narrate with the default voice if a route exists, else music only.
  • --demo (any variant) without a voice flag: music only. With --voice (or the default voice id), use the variant's bundled clips: no ElevenLabs route is needed and no credits are spent.
  • A voice flag was given but no route exists: say so, offer to connect the connector, add a key or attach clips; do not silently drop the voice. Never invent a voice id and never fake narration.
  • A voice the user names in words is looked up with the connector's voice list; otherwise use the id as given.

Demo (--demo[=default|self])

No research, storyboard or editing. Each variant lives in assets/demo/<variant>/: index.html, narration.txt (one line per scene, - = none) and clips.json, which maps each scene to its approved recording in the shared assets/demo/clips/ (default voice).

  • default (48s): scenes 1-6 are the generic template, a placeholder for the viewer's own video; scenes 7-9 show how to make one: a bridge ("that was a placeholder"), the three install routes from sugatoray/aiskills, get started (music only). The cover is tagged "Demo of Skill /dynamic-promo-video · sugatoray/aiskills".
  • self (32s): the skill explaining itself: cover, the problem, the scene engine's code, the three install routes, usage, get started. | Request | Run | | --- | --- | | --demo / --demo=default | python3 SKILL_DIR/scripts/demo.py (music only) | | --demo=self | python3 SKILL_DIR/scripts/demo.py --variant self | | add --voice (or the default voice id) | add --voice: the bundled clips, no ElevenLabs route needed, no credits | | add --voice-elevenlabs=<other id>, API key | add --voice-id <id> (generates the clips) | | add --voice-elevenlabs=<other id>, MCP connector | generate one clip per non-- line of the variant's narration.txt (see references/voiceover.md), save as clips/vo<scene>.mp3, add --clips-dir clips/ |

With --voice the result is identical every run (same frames, same audio). Output: promo-demo/demo_final.mp4 and thumbnail.png, checked; deliver as in step 5. The skill icons are simplified drawings.

0. Before building

  • Research the subject first: README, package page, marketplace listing, install commands. Use real names, commands and versions. Do not invent features.
  • Use the project's real branding (banner, icon, colors, fonts) and real screenshots from its docs where possible. Check the repo for docs images before drawing anything.
  • Sandbox network is allowlisted: npm registry, marketplace and github.com web pages are usually blocked from the shell. Git clone of a public repo often works (use the add_repo tool, then clone). If the repo's own CLAUDE.md says to read docs first and the task is not editing the repo, say you are skipping them.
  • Make a task list. Last task: check frames and audio, then deliver.

1. Storyboard (write the narration first)

Typical 6 scenes: (1) cover/title, (2) the problem, (3) the product in action, (4) install commands, (5) editor/extension usage, (6) end card with commands and links. The template has exactly these. Write one narration line per scene (about 2.5-3 words per second). Scene length is set by the narration, not the other way round.

2. Build the scenes

Copy SKILL_DIR/assets/template/index.html into the work folder and edit it: brand CSS variables, scene text, real screenshots, camera keyframes. Rules that matter most:

  • Everything is a function of t through window.setT(t); no CSS animation, no timers.
  • Frame 0 is a finished cover (social platforms use it as the preview). Scene 1 only fades out.
  • Icons are simplified drawings, not official logos; say so unless official files are supplied.
  • Do not reuse a class name a script queries with querySelectorAll.

3. Preview, then voice, then retime

node SKILL_DIR/scripts/render.js index.html --preview 0,6,12,17,23,29 --thumbnail thumbnail.png

Look at the preview frames before going on. Then produce the voice clips with the voice from Inputs (details in references/voiceover.md; one generation per scene, never re-run a paid generation). With an API key:

python3 SKILL_DIR/scripts/tts_elevenlabs.py --script narration.txt --voice <voice-id> --dry-run   # check the plan first
python3 SKILL_DIR/scripts/tts_elevenlabs.py --script narration.txt --voice <voice-id>

With the MCP connector, call creative_generate_speech once per scene with that voice_id. A scene with no narration gets the line - (no clip; pass - to timing.py). If the voice says a name wrong, write it the way it sounds, test the name alone (about 15 credits) and splice the approved sample into the clip instead of regenerating the line (references/voiceover.md). Then retime:

python3 SKILL_DIR/scripts/timing.py --authored 0,4,9,15,21,26,31 --clips vo0.mp3 vo1.mp3 vo2.mp3 vo3.mp3 vo4.mp3 vo5.mp3

Add --write-html index.html to write the new const NB = [...] into the page (or paste the printed line). Scenes stretch to fit; the voice is never sped up.

4. Render, music, mix

node SKILL_DIR/scripts/render.js index.html --encode promo_silent.mp4
python3 SKILL_DIR/scripts/music.py --style energetic --duration <total> --out music.wav
python3 SKILL_DIR/scripts/mix.py --video promo_silent.mp4 --music music.wav --voice 0.3:vo0.mp3 ... --out promo_final.mp4

Use a licensed track instead of music.py when the user supplies one; if synthesized, say it is simple and synthesized. Copy the --voice arguments from timing.py's output. If only visuals change later, re-render and run mix.py --audio-from <previous final>.

5. Verify and deliver

python3 SKILL_DIR/scripts/verify.py promo_final.mp4 --frames <one time per scene>
  • It must report both streams with near-equal durations; read the per-second dB line (voice present, music dipping under it).
  • Look at frame 0, one frame per scene and the last frame in check/. Confirm no overlaps or clipped text.
  • Say clearly which file has sound: keep the _silent / _final names.
  • Send with SendUserFile (display render), plus thumbnail.png. Summarize in a few lines: what each scene shows, what is real vs. drawn, and what you could not verify (you have not listened to the audio).
  • Offer a LinkedIn/social post note only if asked; keep claims to what the README documents (for example "early development").

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.