GitHub Repo Promo Video#

Depends on: website-to-hyperframes — load it before starting. Its 6-step workflow (capture → brand → brief → storyboard → build → validate) and all reference files apply here. This skill specializes that workflow for GitHub repository promos.

Core Decisions#

Directory Structure#

Every promo project lives under a single parent folder:

github-promos/
  <repo-name>/
    index.html              ← main composition (mandatory)
    package.json            ← Node project config (from hyperframes init)
    hyperframes.config.json ← HyperFrames config
    DESIGN.md               ← brand cheat sheet (Step 1 output)
    STORYBOARD.md           ← beat plan (Step 3 output)
    SCRIPT.md               ← narration script (Step 3 output)
    assets/
      repo-page.png         ← Full-page GitHub screenshot (dark mode)
      narration.mp3         ← ElevenLabs voiceover
    renders/                 ← generated videos

Sibling repos coexist under github-promos/:

github-promos/
  mercury-agent-skills/
  nextjs/
  three.js/
  react/

Workflow#

This skill follows the website-to-hyperframes 6-step process, specialized for GitHub repos. Steps marked 💬 require user confirmation before proceeding.

Step 0: Capture Repo Info#

Use web-search or fetch_url to collect from the GitHub API and repo page:

• Stars, forks, watchers, open issues
• Primary language, top languages breakdown
• Description, topics/tags, about section
• Latest release, license, recent activity
• README summary (what the project does, who it's for)

Then use the screenshot skill to capture a full-page screenshot of the repo in dark mode:

use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// Full page, dark mode, viewport 1080x1920
// Save as: github-promos/{repo}/assets/repo-page.png

Get the screenshot dimensions — you need the pixel height for scroll calculations:

sips -g pixelHeight github-promos/{repo}/assets/repo-page.png
sips -g pixelWidth github-promos/{repo}/assets/repo-page.png

Step 1: Brand Identity#

Write DESIGN.md — GitHub dark theme defaults:

Font: Inter (400–900).

Step 2: Strategy & Brief 💬#

Align with the user on:

• Which repo and what aspect to highlight
• Tone (professional, hype, educational)
• Audience (developers, founders, general tech)
• The ONE message this video must communicate

Step 3: Storyboard + Script 💬#

Write STORYBOARD.md and SCRIPT.md together. Critical: narration writes itself around the scroll timing.

7-Beat Structure (MANDATORY)#

The narration script MUST reference the scroll state. Example:

"Mercury Skills — a curated library of 130 agent capabilities." (Beat 1) "Let's scroll through what's inside — here's the full registry, categories from AI to DevOps." (Beat 2 — scroll starts) "Zooming into the README — see how easy it is to search and install." (Beat 2 — scroll at 60%) "The numbers: 20 thousand stars, 3 thousand forks." (Beat 3)

The narrator never says "scrolling through" in a vacuum — they always describe what is currently on screen.

Timing from narration#

1. Write the script first.
2. Generate audio (Step 4).
3. Measure actual audio duration per beat.
4. Set data-start and data-duration on each beat <div> from the measured timings.
5. If Beat 2 audio is 11 seconds, the scroll animation spans those 11 seconds — not a fixed 10.

Step 4: Voiceover Generation 💬#

Ask the user which TTS provider:

Default ElevenLabs config:

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/AZnzlk1XvdvUeBnXmlld" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "SCRIPT_HERE",
    "model_id": "eleven_multilingual_v2",
    "voice_settings": {
      "stability": 0.35,
      "similarity_boost": 0.8,
      "style": 0.25,
      "use_speaker_boost": true
    }
  }' \
  --output github-promos/{repo}/assets/narration.mp3

Verify: ls -la github-promos/{repo}/assets/narration.mp3 — file must exist and be > 0 bytes.

After generating audio, transcribe it with timestamps (ElevenLabs returns these, or use ffmpeg + whisper). Map each timestamp to a beat. Update the storyboard timings from real audio durations.

Step 5: Build Compositions#

Follow the website-to-hyperframes build step, with these repo-specific requirements:

Mandatory architecture#

<div id="root"
  data-composition-id="{repo}-promo"
  data-width="1080"
  data-height="1920"
  data-start="0"
  data-duration="{total_seconds}">

  <audio id="narration-audio"
    src="assets/narration.mp3"
    data-start="0"
    data-duration="{total_seconds}"
    preload="auto"></audio>

  <!-- Background layers -->
  <div id="bg"></div>
  <div id="bg-grid"></div>
  <div class="glow-orb g1"></div>
  <div class="glow-orb g2"></div>
  <div id="scanlines"></div>

  <!-- 7 beats, each .beat.clip with data-start/data-duration -->
  ...
</div>

Fullscreen phone mockup (Beat 2)#

The phone fills the entire 1080x1920 canvas — not a centered phone with dead space.

.phone-frame {
  position: absolute;
  inset: 0;                       /* fills entire canvas */
  width: 1080px;
  height: 1920px;
  border-radius: 0px;             /* no rounded corners on fullscreen */
  overflow: hidden;
  background: #0d1117;
}

.phone-screen {
  position: absolute;
  inset: 0;
  overflow: hidden;
}

.phone-scroll-content {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: {IMG_H}px;             /* actual screenshot height */
}

.phone-scroll-thumb {
  position: absolute;
  right: 8px;
  width: 5px;
  border-radius: 3px;
  background: linear-gradient(180deg, #58a6ff, #3fb950);
  height: {THUMB_H}px;           /* computed: TRACK_H * (1920 / IMG_H) */
  top: 0;
}

Scroll variables:

var IMG_H = /* actual screenshot pixel height */;
var PHONE_H = 1920;
var MAX_SCROLL = IMG_H - PHONE_H;

// Three scroll stops at ~30%, ~60%, ~88%
var SCROLL_1 = -Math.round(MAX_SCROLL * 0.3);
var SCROLL_2 = -Math.round(MAX_SCROLL * 0.6);
var SCROLL_3 = -Math.round(MAX_SCROLL * 0.88);

// Scroll thumb
var TRACK_H = 1920;
var THUMB_H = Math.round(TRACK_H * (PHONE_H / IMG_H));
var THUMB_TRAVEL = TRACK_H - THUMB_H;

function thumbY(scrollPx) {
  return (Math.abs(scrollPx) / MAX_SCROLL) * THUMB_TRAVEL;
}

GSAP timeline#

window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});

// Beat 1: Hero — fade in elements, stagger badges
// Beat 2: Phone scroll — three scroll segments with different easing
//         gsap.to('.phone-scroll-content', { y: SCROLL_1, duration: beat2Duration * 0.33, ease: 'power3.out' })
//         gsap.to('.phone-scroll-content', { y: SCROLL_2, duration: beat2Duration * 0.33, ease: 'power2.out' })
//         gsap.to('.phone-scroll-content', { y: SCROLL_3, duration: beat2Duration * 0.34, ease: 'power1.out' })
//         gsap.to('.phone-scroll-thumb', { top: thumbY(SCROLL_1), ... })
//         ... repeat for SCROLL_2, SCROLL_3
// Beat 3: Stats — stagger-in cards
// Beat 4: Chips — stagger-in feature tags
// Beat 5: Stars — scale-in with elastic rotation
// Beat 6: CTA — fade-in button with glow pulse
// Beat 7: Follow — quick fade-in pill

window.__timelines["{repo}-promo"] = tl;

Important: Scroll durations come from the narration audio. If Beat 2's audio segment is 11 seconds, the scroll animations fill those 11 seconds proportionally — not a fixed speed.

Step 6: Validate & Deliver#

cd github-promos/{repo}
npx hyperframes lint
npx hyperframes validate
npx hyperframes snapshot

Fix all errors. Then render at draft quality first:

npx hyperframes render --quality draft

Verify output in renders/. If clean, render final:

npx hyperframes render --quality standard

Deliver the MP4 to the user. Ask: "Would you like me to post this, or render at high quality first?"

Seven Beats — Detailed Specifications#

Beat 1: Hero (0s → ~4s)#

• Category pill: e.g. FRONTEND or AI / ML — repo's primary category
• Repo name: Large text, gradient blue→green (linear-gradient(135deg, #58a6ff, #3fb950))
• Tagline: One-liner from repo description, #8b949e color
• 3 badges: Stars count, forks count, primary language — pill-shaped, border #30363d, icons from Lucide

Beat 2: Fullscreen Scrollable Phone (~4s → ~15s)#

The phone fills the ENTIRE 1080x1920 canvas. No frame bezels, no rounded corners on the outer viewport. The GitHub screenshot scrolls behind a status bar overlay and a scroll thumb indicator.

• Status bar at top: time, repo name, signal icons (semi-transparent overlay)
• Content: full-page GitHub screenshot scrolls from top to bottom
• Scroll thumb on the right edge: 5px wide, gradient blue→green, tracks scroll position
• Three scroll stops matching the narration's description of what's on screen
• Each scroll segment: different easing (power3.out → power2.out → power1.out)

Beat 3: Stats (~15s → ~19s)#

Title: "By the Numbers" in #e6edf3.

2×2 grid of glass-morphism stat cards:

Each card: rgba(22,27,34,0.8) background, backdrop-filter: blur(12px), border #30363d, value text with gradient matching the icon category.

Beat 4: What You Can Build (~19s → ~23s)#

Title: "What Can You Build?" in #e6edf3.

8–10 chips in a wrapping grid. Each chip:

• Rounded pill, px-3 py-1.5
• Left border color matches category (blue for dev, green for infra, purple for AI, etc.)
• #e6edf3 text on rgba(22,27,34,0.6) background

Beat 5: Stars Highlight (~23s → ~27s)#

• Large star icon (Lucide Star, 120px) with scale: 0 → 1.2 → 1 elastic animation + slight rotation
• Star count in large gradient gold text: linear-gradient(135deg, #f9c513, #f0883e)
• Label underneath: "developers trust this repo" in #8b949e

Beat 6: CTA (~27s → ~31s)#

• Title: "Star on GitHub Today" in #e6edf3
• Subtitle: repo description or tagline in #8b949e
• Green CTA button: #238636 background, #e6edf3 text, border-radius 999px
• Subtle glow pulse animation: box-shadow: 0 0 20px rgba(35,134,54,0.4) pulsing

Beat 7: Follow (~31s → ~33s)#

• Text: "Follow for more trending GitHub repositories" in #e6edf3
• Pill with @githubprojects (or user-specified handle): rounded, border #30363d, background rgba(22,27,34,0.8)
• Quick 0.5s fade-in

Narration-Aware Scroll Sync#

This is the key architectural rule: the narration script is aware of what's on screen during the scroll.

How to write narration-aware scripts#

1. Know the scroll stops. Before writing the script, you know the 3 scroll positions (30%, 60%, 88%) and what content appears at each position (from the screenshot).

2. Call out what you see. The narrator describes the content at each scroll position:

   • Start: "Here's the repo — README front and center."
   • 30% scroll: "Scrolling down through the installation instructions..."
   • 60% scroll: "And here's the full feature list, categories from AI to DevOps."
   • 88% scroll: "Down to the contributor section at the bottom."

3. Time narration to scroll duration. If Beat 2 audio is 11 seconds total, the three scroll segments each get approximately 3.7 seconds. Write ~12 words per segment so the narrator isn't rushing.

4. Never narrate in a vacuum. If the scroll is paused at 60% showing the feature list, the narration should reference specific features visible at that position — not generic filler.

Example: narration-aware script#

[Beat 1 — 4s] "Mercury Skills — 130 curated agent capabilities, one command away."

[Beat 2 — 11s, scroll across full page]
  0s–3.7s  "Let's walk through it. Here's the full registry on GitHub —"
  3.7s–7.3s "scrolling into the installation section — one CLI command and you're in."
  7.3s–11s  "Here's the feature grid — AI, DevOps, mobile, finance, 23 categories deep."

[Beat 3 — 4s] "The numbers: 20 thousand stars, 3 thousand forks, and zero friction to start."

[Beat 4 — 4s] "What can you build? PDF generation, Amazon shopping, screenshots, Twitter automation, and counting."

[Beat 5 — 4s] "And 20,000 developers agree — this is the agent skills library that ships."

[Beat 6 — 4s] "Star it today. github.com/cosmicstack-labs/mercury-agent-skills."

[Beat 7 — 2s] "Follow @githubprojects for more trending repos."

Prerequisites#

• ELEVENLABS_API_KEY environment variable (for ElevenLabs voiceover)
• Node.js >= 22 with HyperFrames installed globally
• ffmpeg available in PATH (for audio duration measurement if not using ElevenLabs timestamps)

Troubleshooting#

Skill Dependency#

Required dependency: website-to-hyperframes

Load it before starting. Its 6-step workflow (capture → brand → brief → storyboard → build → validate) and all reference files (step-0-capture.md through step-6-validate.md, capabilities.md, techniques.md) apply to this skill as the general framework. This skill specializes that workflow for GitHub repository promos with narration-aware scroll sync and the 7-beat structure.