Theycallmeholla/skills

Skill de GIF de Recorrido

Genera un proyecto Node.js autónomo que graba un recorrido por el navegador y exporta MP4 + GIF.

Cuándo usar esta skill vs. gif_creator de claude-in-chrome

Para una captura rápida y única dentro de la sesión activa del navegador del usuario (su perfil, sus pestañas abiertas, ya inició sesión), la herramienta gif_creator de claude-in-chrome es mucho más simple — sin andamiaje de proyecto, sin claves API. Recurre a esta skill cuando el usuario necesite algo que gif_creator no puede proporcionar: un script re-ejecutable/versionable (volver a grabar después de cada cambio en la interfaz), salida MP4, un GIF gifski de alta calidad, una grabación con perfil limpio (sin marcadores personales ni extensiones en el cuadro), o capacidad de repetición en CI.

Arquitectura

Descripción en lenguaje natural
        ↓
Claude genera script TypeScript
        ↓
Stagehand v3 (control del navegador con IA) — Playwright conectado vía CDP
        ↓
Contexto de grabación de Playwright captura vídeo (.webm)
        ↓
ffmpeg convierte → .mp4
gifski convierte fotogramas → .gif
        ↓
Salida: walkthrough.mp4 + walkthrough.gif + walkthrough.md

Flujo de trabajo

Paso 1: Recopilar requisitos

Requisito previo — Clave API de LLM: Stagehand llama a un LLM para cada acción de IA. El usuario necesita tener ANTHROPIC_API_KEY (o la clave del proveedor que coincida con el modelo configurado, por ejemplo OPENAI_API_KEY) disponible para .env. Confirma esto de antemano — sin ella el script generado no puede ejecutarse.

Antes de generar cualquier código, confirma:

1. URL de destino — ¿Dónde comienza el recorrido? (por ejemplo, https://app.ejemplo.com/iniciar-sesion)
2. Descripción del flujo — ¿Qué pasos se deben demostrar? (el lenguaje natural está bien)
3. Situación de autenticación — ¿La página es pública o necesita inicio de sesión? Si necesita inicio de sesión: ¿codificará las credenciales en .env, usará una sesión/exportación de cookies preautenticada o comenzará desde un estado ya iniciado?
4. Formato de salida — ¿Solo GIF, solo MP4 o ambos? (por defecto: ambos)
5. Duración / ritmo — ¿Demostración rápida o deliberada paso a paso? (por defecto ~1-2s de pausa entre pasos)
6. Ventana gráfica — El valor predeterminado es 1280×800. Más estrecha para demostraciones tipo móvil.

Si el usuario proporciona una descripción detallada desde el principio, infiere lo que puedas y pregunta solo sobre las lagunas.

Paso 2: Generar el proyecto

Genera un proyecto completo y ejecutable en ./walkthrough-[nombre]/:

walkthrough-[nombre]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   └── walkthrough.ts      ← script principal
└── scripts/
    └── convert.sh          ← conversión ffmpeg + gifski

Lee references/stagehand-patterns.md para la API de Stagehand y los patrones de traducción de pasos. Lee references/output-pipeline.md para los comandos de conversión ffmpeg/gifski y el ajuste de GIF.

Paso 3: Traducir pasos

Convierte la descripción en lenguaje natural del usuario en llamadas a stagehand.act() (v3: act() vive en la instancia de stagehand y toma una cadena de texto simple, con opciones como variables y page). Consulta references/stagehand-patterns.md para patrones y errores comunes.

Reglas clave de traducción:

• Cada acción lógica de la interfaz = una llamada stagehand.act("...", { page }) con una instrucción clara en inglés
• La entrada escrita se pasa a través de variables (marcadores de posición %name%) — nunca incluyas secretos en línea en la cadena de instrucción
• Añade page.waitForTimeout(1500) entre pasos importantes para el ritmo (visible para el espectador)
• Añade page.waitForLoadState('networkidle') después de las navegaciones
• Nunca codifiques selectores — Stagehand los deduce de instrucciones en lenguaje natural
• Para flujos que requieren autenticación: usa .env para las credenciales, nunca las codifiques

Paso 4: Estrategia de grabación

Utiliza siempre la grabación de vídeo de Playwright como método de captura principal:

• Stagehand v3 no tiene grabación incorporada — conecta Playwright al navegador de Stagehand a través de chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() }), crea un contexto con la opción recordVideo, y maneja la página de ese contexto (consulta references/stagehand-patterns.md)
• Graba la sesión completa como .webm a través de ese contexto de grabación
• NO intentes unir capturas de pantalla individuales directamente en un GIF — vídeo → fotogramas → GIF es de mayor calidad
• Después de que el script se complete, ejecuta convert.sh para producir MP4 y GIF

Nunca hagas del GIF el artefacto principal. El MP4 siempre se produce primero. El GIF se deriva de él. Los GIF son grandes y de baja calidad para cualquier cosa de más de 15 segundos — advierte al usuario y sugiere mantener los recorridos por debajo de 60 segundos.

Paso 5: Superposiciones de clic/cursor (Opcional pero recomendado)

Inyecta una superposición de resaltado de clic a través de page.addInitScript() antes de que comience el recorrido. Consulta references/stagehand-patterns.md → sección "Superposición de clic" para el fragmento de código.

Esto añade una sutil animación de onda en cada punto de clic — hace que los recorridos sean mucho más legibles sin necesidad de posprocesamiento.

Paso 6: Salida

Después de la generación, produce:

1. El directorio del proyecto (todos los archivos)
2. Una breve lista de verificación de configuración en la conversación:

## Configuración
npm install
npx playwright install chromium
cp .env.example .env  # completa ANTHROPIC_API_KEY + cualquier credencial

## Ejecutar
npx tsx src/walkthrough.ts

## Convertir a GIF + MP4
bash scripts/convert.sh

También informa al usuario qué esperar: duración aproximada, tamaño de la ventana gráfica, nombres de archivos de salida.

Ofrécete a ejecutarlo: Claude Code puede ejecutar todo el pipeline por sí mismo — npm install, npx playwright install chromium, ejecutar el script del recorrido, luego bash scripts/convert.sh — si el usuario está de acuerdo (aún necesita proporcionar los valores de .env). Cuando lo ejecutes tú mismo, verifica la salida antes de declarar éxito: usa ffprobe en el MP4 para una duración razonable y comprueba que los tamaños de los archivos GIF/MP4 no sean triviales (convert.sh imprime esto en su cola de verificación).

---

Advertencias / Condiciones de cancelación

Informa al usuario de antemano si se aplica alguna de estas:

Condición	Orientación
La página requiere inicio de sesión con MFA/SSO	El script no puede manejar esto automáticamente — el usuario debe exportar cookies desde una sesión de navegador ya iniciada
CAPTCHA en la página de destino	Playwright se detendrá — usa un entorno de demostración/sandbox en su lugar
Animaciones pesadas / desplazadores infinitos	La grabación los capturará, pero la conversión a GIF será grande — sugiere recortar
El flujo tiene más de 90 segundos	Recomienda solo MP4; el GIF será inmanejablemente grande
El contenido de la página es aleatorio/dinámico	Stagehand maneja el direccionamiento visual, pero advierte que las re-ejecuciones pueden verse diferentes

---

Convención de nomenclatura de salida

walkthrough-[slug]/
  output/
    walkthrough.webm     ← grabación sin procesar de Playwright
    walkthrough.mp4      ← convertido (H.264, seguro para web)
    walkthrough.gif      ← salida gifski, máximo 800px de ancho
    walkthrough.md       ← anotación paso a paso (generada automáticamente)

El archivo .md enumera cada llamada act() como un paso numerado con marcas de tiempo — útil para incrustar como título junto al GIF.

---

Archivos de referencia

• references/stagehand-patterns.md — API de Stagehand, traducción de pasos, fragmento de superposición de clic, patrones de autenticación
• references/output-pipeline.md — comandos ffmpeg, banderas gifski, optimización de GIF, solución de problemas