Communitygithub.com

cosmicstack-labs/mercury-agent-skills

Genera un video tour de 15 a 30 segundos con desplazamiento automático de cualquier página de repositorio de GitHub, narración con IA de ElevenLabs y sincronización de subtítulos palabra por palabra.

¿Qué es mercury-agent-skills?

Esta habilidad especializada para agentes de IA (como Claude Code, Cursor o Codex) permite crear videos promocionales estilo Instagram Reels a partir de cualquier página de repositorio de GitHub. Captura una captura de pantalla completa del repositorio en modo oscuro y con viewport móvil, genera un audio narrativo descriptivo usando ElevenLabs, sincroniza los subtítulos palabra por palabra con la narración empleando GSAP para las animaciones, y renderiza el video final en formato MP4 1080x1920 mediante HyperFrames CLI. Es útil para desarrolladores, equipos de producto y creadores de contenido que deseen mostrar rápidamente las características y el valor de un repositorio de código abierto en redes sociales. La habilidad se apoya en el workflow base de `website-to-hyperframes`, pero lo especializa para tours de una sola página con desplazamiento vertical, narración cronometrada y subtítulos visibles tipo karaoke. El resultado final es un video pulido con una llamada a la acción al final, perfecto para compartir en Instagram, TikTok o YouTube Shorts.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills/tree/HEAD/categories/media-download/github-repo-tour

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Vista previa

Del README del skill

mercury-agent-skills preview

Documentación

Tour de Repo en GitHub — Video con Desplazamiento, Narración Sincronizada y Subtítulos

Depende de: website-to-hyperframes — cárgalo antes de empezar. Su flujo de trabajo de 6 pasos y archivos de referencia aplican aquí. Esta habilidad especializa ese flujo para tours de una sola página con desplazamiento, narración y subtítulos visibles.


Qué Produce Esta Habilidad

Un video vertical de 1080x1920 (formato Instagram Reels) que:

  1. Muestra una página de repositorio de GitHub — captura de pantalla móvil de página completa, desplazándose suavemente de arriba a abajo durante 15–30 segundos.
  2. Narra el tour — voz IA de ElevenLabs describiendo lo que se ve en pantalla, sincronizada con la posición de desplazamiento.
  3. Incorpora subtítulos en pantalla — superposición de subtítulos palabra por palabra que resalta cada palabra mientras el narrador la dice. El espectador lee mientras escucha.
  4. Termina con una CTA — "Star en GitHub" o "Sígueme para más" como llamada a la acción.

Decisiones Clave

DecisiónValorPor qué
Dimensiones1080x1920Formato principal de Instagram Reels
Duración15–30 segundosPunto óptimo para engagement en Shorts/Reels
NarraciónMarca el ritmoLa velocidad de desplazamiento, duración de los beats y la sincronización de subtítulos se derivan del audio
SubtítulosResaltado palabra por palabraCada palabra se ilumina cuando el narrador la dice — Subtítulos estilo karaoke
Viewport de teléfonoDesplazamiento a pantalla completa, sin biselLa página de GitHub llena todo el lienzo de 1080x1920
Carpeta de salidagithub-promos/<repo>-tour/Hermana de proyectos github-repo-promo

Estructura de Directorios

github-promos/
  <repo>-tour/
    index.html              ← composición principal de HyperFrames
    package.json            ← de `hyperframes init`
    hyperframes.config.json ← configuración de HyperFrames
    SCRIPT.md               ← guión de narración con marcas de tiempo
    assets/
      repo-page.png         ← Captura de pantalla completa de GitHub (modo oscuro, viewport móvil)
      narration.mp3         ← Locución de ElevenLabs
    renders/                ← MP4 generados

Flujo de Trabajo

Paso 0: Capturar Información del Repo y Captura de Pantalla

Usa web-search o fetch_url para obtener metadatos del repositorio:

  • Estrellas, forks, watchers, issues abiertos
  • Lenguaje principal, descripción, temas
  • Resumen del README (qué hace el proyecto, características clave)

Luego usa la habilidad screenshot para capturar una captura de pantalla de página completa, en modo oscuro y viewport móvil:

use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// Página completa, modo oscuro
// Viewport: 390px de ancho (iPhone 14 móvil) — la captura debe
//   abarcar toda la altura de la página en ancho móvil
// Guardar como: github-promos/<repo>-tour/assets/repo-page.png

Obtén las dimensiones de la captura (necesitas la altura en píxeles para los cálculos de desplazamiento):

sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png

Paso 1: Escribir el Guión de Narración

Escribe un guión de 15–30 segundos que describa lo que el espectador ve a medida que avanza el desplazamiento. El narrador guía al espectador a través de la página:

[0s–4s]  "Este es {repo}. {descripción en una línea}."
[4s–8s]  "Aquí está el README — la instalación es un solo comando."
[8s–13s] "Desplazándonos por la lista de funciones — {menciona 2-3 funciones visibles}."
[13s–18s] "{stars} estrellas, {forks} forks, y una comunidad en crecimiento."
[18s–23s] "Dale estrella en GitHub. Enlace en la biografía."
[23s–25s] "Sígueme para más."

Reglas para el guión:

  • El narrador hace referencia a lo que está actualmente en pantalla en cada posición de desplazamiento.
  • Recuento total de palabras: 50–75 palabras (ritmo cómodo para 15–30 segundos).
  • Sin relleno ("um", "eh", "déjame mostrarte"). Cada palabra gana su lugar.
  • Termina con una CTA clara.

Paso 2: Generar Locución a través de ElevenLabs

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": "GUIÓN_COMPLETO_AQUÍ",
    "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>-tour/assets/narration.mp3

Verifica que el archivo exista y tenga tamaño > 0.

Paso 3: Transcribir y Mapear Tiempos

Después de generar el audio, extrae las marcas de tiempo a nivel de palabra:

Opción A: Marcas de tiempo de ElevenLabs (devueltas con la respuesta de la API si output_format: "mp3" no es la única salida — consulta la documentación de la API para salida aligned).

Opción B: Usa ffmpeg + Whisper (transcripción local con marcas de tiempo por palabra):

# Instala whisper si es necesario
pip install openai-whisper

# Transcribe con marcas de tiempo por palabra
whisper github-promos/<repo>-tour/assets/narration.mp3 \
  --model base \
  --output_format json \
  --output_dir github-promos/<repo>-tour/assets/ \
  --word_timestamps True

La salida te da words[] con marcas de tiempo start y end para cada palabra. Asigna estas marcas de tiempo a las posiciones de desplazamiento.

Paso 4: Construir la Composición HyperFrames

Crea index.html siguiendo la arquitectura de composición HyperFrames:

<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=1080,height=1920"/>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap" rel="stylesheet">
<style>
  /* ── Raíz y Lienzo ── */
  * { margin: 0; padding: 0; box-sizing: border-box; }
  #root {
    position: relative;
    width: 1080px;
    height: 1920px;
    background: #0d1117;
    font-family: 'Inter', sans-serif;
    overflow: hidden;
  }

  /* ── Captura de Pantalla con Desplazamiento ── */
  .scroll-container {
    position: absolute;
    inset: 0;
    width: 1080px;
    height: 1920px;
    overflow: hidden;
  }
  .scroll-content {
    position: absolute;
    top: 0;
    left: 0;
    width: 1080px;
    height: VAR_IMG_H px;   /* altura real de la captura */
  }

  /* ── Superposición de Subtítulos ── */
  .subtitle-bar {
    position: absolute;
    bottom: 180px;
    left: 50%;
    transform: translateX(-50%);
    width: 1000px;
    text-align: center;
    z-index: 100;
  }
  .subtitle-word {
    display: inline-block;
    font-size: 42px;
    font-weight: 700;
    color: rgba(255,255,255,0.35);
    padding: 0 4px;
    transition: color 0.08s, transform 0.08s;
  }
  .subtitle-word.active {
    color: #FFFFFF;
    transform: scale(1.08);
  }
  .subtitle-word.past {
    color: rgba(255,255,255,0.65);
  }

  /* ── Barra de Progreso de Desplazamiento ── */
  .scroll-progress-track {
    position: absolute;
    right: 16px;
    top: 100px;
    width: 5px;
    height: 1720px;
    border-radius: 3px;
    background: rgba(255,255,255,0.1);
    z-index: 50;
  }
  .scroll-progress-thumb {
    position: absolute;
    top: 0;
    left: 0;
    width: 5px;
    height: VAR_THUMB_H px;
    border-radius: 3px;
    background: linear-gradient(180deg, #58a6ff, #3fb950);
    z-index: 51;
  }

  /* ── Superposición de CTA (Beat 6-7) ── */
  .cta-overlay {
    position: absolute;
    inset: 0;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    background: rgba(13,17,23,0.92);
    backdrop-filter: blur(8px);
    z-index: 200;
    opacity: 0;
  }
  .cta-title {
    font-size: 56px;
    font-weight: 800;
    color: #e6edf3;
    text-align: center;
  }
  .cta-subtitle {
    font-size: 32px;
    color: #8b949e;
    margin-top: 16px;
  }
  .cta-button {
    margin-top: 40px;
    padding: 18px 48px;
    background: #238636;
    color: #e6edf3;
    font-size: 28px;
    font-weight: 700;
    border-radius: 999px;
    box-shadow: 0 0 30px rgba(35,134,54,0.5);
  }
  .follow-pill {
    margin-top: 24px;
    padding: 12px 28px;
    background: rgba(22,27,34,0.8);
    border: 1px solid #30363d;
    border-radius: 999px;
    font-size: 22px;
    color: #e6edf3;
    font-weight: 600;
  }
</style>
</head>
<body>
<div id="root"
  data-composition-id="{repo}-tour"
  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>

  <!-- Captura de pantalla con desplazamiento (lienzo completo) -->
  <div class="scroll-container">
    <img class="scroll-content" src="assets/repo-page.png" />
  </div>

  <!-- Barra de progreso de desplazamiento -->
  <div class="scroll-progress-track">
    <div class="scroll-progress-thumb" id="scroll-thumb"></div>
  </div>

  <!-- Superposición de subtítulos -->
  <div class="subtitle-bar" id="subtitle-bar">
    <!-- Palabras inyectadas por JS, un <span class="subtitle-word"> por palabra -->
  </div>

  <!-- Superposición de CTA (últimos 5s) -->
  <div class="cta-overlay" id="cta-overlay">
    <div class="cta-title">Dale estrella en GitHub</div>
    <div class="cta-subtitle">{descripción del repo}</div>
    <div class="cta-button">github.com/{owner}/{repo}</div>
    <div class="follow-pill">@githubprojects</div>
  </div>
</div>

<script>
// ── Cálculos de Desplazamiento ──────────────────────────
var IMG_H = /* altura real de la captura */;
var CANVAS_H = 1920;
var MAX_SCROLL = IMG_H - CANVAS_H;
var THUMB_TRACK = 1720;
var THUMB_H = Math.round(THUMB_TRACK * (CANVAS_H / IMG_H));
var THUMB_TRAVEL = THUMB_TRACK - THUMB_H;

function thumbTop(scrollY) {
  return (Math.abs(scrollY) / MAX_SCROLL) * THUMB_TRAVEL;
}

// ── Marcas de Tiempo de Palabras ────────────────────────
// Pega las marcas de tiempo a nivel de palabra del Paso 3 aquí.
// Formato: [palabra, segundosInicio, segundosFin]
var WORDS = [
  // ["Este", 0.0, 0.3],
  // ["es", 0.3, 0.5],
  // ["mercury-skills", 0.5, 1.0],
  // ...
];

var TOTAL_DURATION = /* segundos totales del audio */;

// ── Construir Spans de Subtítulos ───────────────────────
var subtitleBar = document.getElementById("subtitle-bar");
var wordSpans = [];
WORDS.forEach(function(w, i) {
  var span = document.createElement("span");
  span.className = "subtitle-word";
  span.textContent = w[0];
  subtitleBar.appendChild(span);
  wordSpans.push(span);
});

// ── Línea de Tiempo GSAP ────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});

// Fase 1: Desplazamiento (0s a ~80% de la duración total)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;

// Desplazamiento de arriba a abajo con easing
$.to(".scroll-content", {
  y: -MAX_SCROLL,
  duration: scrollEnd,
  ease: "none",
  onUpdate: function() {
    var progress = this.progress();
    var thumbTop = progress * THUMB_TRAVEL;
    gsap.set("#scroll-thumb", { top: thumbTop });
  }
}, 0);

// Fase 2: Resaltado de subtítulos palabra por palabra
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
  tl.call(function() {
    // Desactivar palabra anterior
    if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
      wordSpans[currentWordIndex].classList.remove("active");
      wordSpans[currentWordIndex].classList.add("past");
    }
    // Activar palabra actual
    wordSpans[i].classList.add("active");
    currentWordIndex = i;
  }, null, w[1]);
});

// Fase 3: La superposición de CTA aparece al 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);

// Fase 4: Atenuar la barra de subtítulos durante la CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);

// Fase 5: La barra de progreso de desplazamiento se desvanece
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);

window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>

Paso 5: Renderizar

cd github-promos/<repo>-tour

# Si no existe configuración del proyecto HyperFrames:
npx hyperframes init --example blank --non-interactive

# Lint
npx hyperframes lint

# Instantánea para verificar visualmente
npx hyperframes snapshot

# Renderizado borrador
npx hyperframes render --quality draft

# Verifica el MP4 de salida en renders/
ls -la renders/

# Si todo se ve bien, renderiza el final
npx hyperframes render --quality standard

Paso 6: Entregar

Envía el MP4 final al usuario. Pregunta si desea:

  • Renderizado de alta calidad (--quality high)
  • Relación de aspecto diferente (horizontal 1920x1080)
  • Revisiones del guión

Sistema de Subtítulos — Cómo Funciona

El sistema de subtítulos es el diferenciador principal de esta habilidad. Así funciona la sincronización palabra por palabra:

Marcas de Tiempo a Nivel de Palabra

El audio de la narración se transcribe con marcas de tiempo a nivel de palabra (de ElevenLabs o Whisper). Cada palabra obtiene una entrada [palabra, segundosInicio, segundosFin] en el array WORDS.

Tres Estados Visuales

Cada palabra en la barra de subtítulos tiene tres estados CSS:

EstadoClaseVisual
Próximo.subtitle-wordBlanco tenue rgba(255,255,255,0.35)
Activo.subtitle-word.activeBlanco brillante #FFFFFF, ligeramente escalado 1.08
Pasado.subtitle-word.pastBlanco medio rgba(255,255,255,0.65)

La línea de tiempo de GSAP llama a una función en el segundosInicio de cada palabra para transicionar palabraActual → activo y palabraAnterior → pasado. Esto crea un resaltado palabra por palabra estilo karaoke perfectamente sincronizado con el audio.

Tipografía

  • Fuente: Inter 700, 42px
  • Posición: Parte inferior 180px, centrada, 1000px de ancho máximo
  • Fondo: Sin caja de fondo — las palabras flotan sobre el contenido de desplazamiento con el degradado tenue/brillante/tenue que las hace legibles sobre cualquier contenido
  • Z-index: 100 (por encima del contenido de desplazamiento en z-index 1, por debajo de la superposición de CTA en z-index 200)

Consideraciones de Diseño

Las palabras se distribuyen con display: inline-block y ajuste de texto natural. Para guiones más largos (más de 20 segundos), considera dividir en 2–3 grupos de líneas que aparecen/desaparecen entre segmentos de desplazamiento:

// Agrupar palabras por segmento de desplazamiento
var SEGMENTS = [
  { start: 0, end: 5, words: [0, 12] },     // Beat 1: Hero
  { start: 5, end: 15, words: [13, 35] },   // Beat 2: Desplazamiento
  { start: 15, end: 20, words: [36, 50] },   // Beat 3: Estadísticas
  { ...

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados