tutorial-video

Tutorial Video

Transforma "enséñale a la gente a usar esto" en una carpeta de MP4 listos. Claude es director, guionista, operador y editor. El usuario solo aprueba el plan, aprueba el guion y mira el resultado.

Cómo funciona (y por qué así)

entender la herramienta → entrevista → guion (aprobación) → ensayo sin grabar
   → calibrar la pantalla → grabar cada video → tut prepare → tut plan/stills → tut render → entrega/

Tres problemas definen la arquitectura. Entiéndelos, porque explican casi todas las reglas de abajo:

1. Los clics de la extensión no mueven el mouse del sistema. La grabación de pantalla sale sin cursor. Por eso un recorder.js inyectado en la página registra dónde y cuándo ocurrió cada clic, tecla y navegación, y el cursor, la onda del clic, el zoom y los callouts se dibujan después, en la edición. Como la edición conoce el futuro, el cursor se desliza hasta el botón antes del clic, y la cámara hace zoom antes de la acción.
2. Sincronizar video y eventos. Al inicio y al final de cada toma, __tut.flash() pinta la página de magenta por medio segundo. El editor encuentra ese flash en el video y con él descubre el tiempo exacto (reloj de la página → tiempo del video) y el rectángulo exacto de la página en la pantalla, sin calcular coordenadas Retina ni de múltiples monitores.
3. Claude es lento entre una acción y otra. El video bruto tiene largos tramos de inactividad. El editor corta esos tramos (fotogramas idénticos, así que el corte no se nota), acelera esperas con movimiento y congela el resultado final el tiempo necesario para leer el subtítulo. Así que no tengas prisa durante la grabación. La prisa solo genera errores.

Rutas usadas más abajo:

• SKILL_DIR: la carpeta de esta habilidad (donde está este archivo).
• TUT="$SKILL_DIR/scripts/tut", REC="$SKILL_DIR/scripts/rec.sh", WIN="$SKILL_DIR/scripts/chrome-window.sh".
• SERIE: la carpeta de la serie, por defecto ./tutoriais/<slug-de-la-serie>/ en el directorio actual (pregunta si el usuario prefiere otro lugar).

Todo comando tut imprime una línea RESULT {json} al final. Lee esa línea para decidir el siguiente paso.

Fase 0: Prerrequisitos (una vez por sesión)

1. Ejecuta $TUT doctor. La primera vez instala el motor (Remotion) y, en el primer render, descarga un Chrome headless (~140 MB).
2. Carga las herramientas de Claude in Chrome en una sola llamada de ToolSearch: select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__javascript_tool,mcp__claude-in-chrome__find,mcp__claude-in-chrome__read_page. Si la extensión no está conectada, pide al usuario que ejecute /chrome. Sin ella no hay grabación.
3. Avisa al usuario, una vez, de lo que va a ocurrir en su máquina: macOS pedirá permiso de Grabación de Pantalla para la app del terminal y de Automatización de Chrome (para posicionar la ventana). Durante las grabaciones debe activar No Molestar y no tocar el mouse ni las ventanas.

Fase 1: Entender la herramienta

Antes de preguntar cualquier cosa, estudia lo que se va a enseñar. Las buenas preguntas dependen de esto.

• Si hay un proyecto local (repositorio): lee el README y la documentación, las rutas y páginas, el menú de navegación, los formularios y el onboarding. Enumera las funcionalidades desde el punto de vista del usuario final ("crear oferta", "invitar colega"), no del código.
• Si es una URL: navega con Claude in Chrome, usa read_page con filter: "interactive" en las pantallas principales y abre los menús.

Resultado: un mapa corto de tareas que el público puede realizar, con la pantalla de inicio de cada una. Detalles en references/roteiro.md.

Fase 2: Entrevista y plan de la serie

Usa AskUserQuestion. Cada pregunta debe traer opciones concretas extraídas del mapa de la Fase 1 y una recomendación. El usuario no debe tener que inventar la respuesta. Decide junto con él:

• Público y nivel (quién mira, qué sabe ya).
• Objetivo de la serie (onboarding, reducir soporte, demo de ventas, formación interna).
• Qué enseñar: multiselect con las tareas del mapa.
• Cuántos videos. Propón tú: un video = un resultado ("Cómo publicar una oferta"), de 30 s a 3 min, de 3 a 8 pasos.
• Visual: preset aurora (oscuro), grafite o claro, color de marca y logo.
• Entorno de grabación: URL, cuenta de demostración ya logueada en Chrome, datos ficticios, qué nunca puede aparecer.

Después muestra el plan de la serie (tabla: nº, título, resultado, duración estimada) y espera el OK.

Fase 3: Guion (puerta de aprobación)

Escribe SERIE/serie.json y un SERIE/videos/<NN-slug>/guion.json por video, siguiendo los esquemas y las reglas de texto de references/roteiro.md. Los puntos más importantes:

• Cada paso tiene un titulo imperativo y corto (lo que aparece grande en pantalla), un texto opcional (dónde o por qué), las acciones (para que tú las ejecutes) y un resultado_esperado.
• Escribe los nombres de la interfaz exactamente como aparecen en pantalla. Quien mira busca ese texto.

Ejecuta $TUT validate SERIE y muéstrale al usuario una tabla legible de cada guion. No grabes nada antes del OK. Regrabar cuesta mucho más que reescribir.

Fase 4: Ensayo (sin grabar)

Para cada video, ejecuta los pasos en Chrome sin grabar. Así descubres los selectores y las referencias que funcionan, popups inesperados, cargas lentas y lo que debe estar listo antes (datos, inicio de sesión). Después:

• Vuelve el sistema al estado inicial (borra lo que creaste en el ensayo, si el usuario está de acuerdo).
• Si el inicio de sesión es necesario, pide al usuario que entre manualmente. Nunca escribas contraseñas ni grabes pantallas de inicio de sesión.
• Ajusta el guion si algo no coincide (y avisa al usuario de lo que cambió).

Fase 5: Preparar la ventana y calibrar (por serie, o si la ventana cambia)

Sigue references/gravacao.md, sección "Ventana y calibración". En resumen:

1. Inyecta el recorder.js.
2. Ejecuta __tut.windowPlan(1280, 720). Con el marker y los bounds que devuelva, ejecuta $WIN <marker> <bounds...>.
3. Graba algunos segundos en pantalla completa con un flash: $REC start SERIE/.tut/calibracion --full → __tut.flash() → $REC stop ....
4. Ejecuta $TUT calibrate SERIE y mira el viewport.png generado.

Debe mostrar solo la página, sin barra del navegador, sin otras ventanas y sin bordes ni avisos de la extensión. Si aparece borde, configura insets en captura.json.

Fase 6: Grabar cada video

Protocolo completo en references/gravacao.md. El esqueleto de una toma:

$REC start SERIE/videos/<id>/toma-1          # graba solo el área de la página (recorte de la calibración)
javascript_tool: __tut.flash()                # flash inicial (sincronía)
para cada paso:
  javascript_tool: __tut.mark('start:<paso>')
  ejecuta las acciones (computer: left_click / hover / key; escritura con __tut.type)
  resalta lo importante: __tut.callout('texto o selector', 'etiqueta corta')
  espera a que el resultado aparezca en pantalla
  javascript_tool: __tut.mark('end:<paso>')
javascript_tool: __tut.flash()                # flash final (corrige deriva del reloj)
javascript_tool: __tut.dump()  →  $TUT save-events SERIE/videos/<id>/toma-1   (JSON por stdin)
$REC stop SERIE/videos/<id>/toma-1
$TUT prepare SERIE/videos/<id>/toma-1

Reglas que evitan regrabaciones:

• Después de cualquier carga completa de página, reinyecta el recorder. Los eventos anteriores quedan guardados en la sesión de la pestaña. Antes de salir a otro dominio, haz dump y save-events.
• Si un paso sale mal en medio, usa __tut.mark('abort:<paso>'), vuelve al estado anterior y reinicia con start:<paso>. Vale el último intento completo. No detengas la grabación por esto.
• Para escribir, prefiere __tut.type('texto') después de hacer clic en el campo (el texto aparece letra por letra). computer type hace que el texto aparezca de golpe.
• Para desplazarte, prefiere __tut.scrollTo('texto o selector') (desplazamiento suave). Las pausas son gratis, porque el editor las corta. No tengas prisa.
• No dispares alert / confirm: bloquean la extensión. Si un paso requiere "Eliminar", avisa al usuario antes.

Fase 7: Editar y revisar

$TUT prepare SERIE/videos/<id>/toma-N    # recorta, sincroniza, mide movimiento → toma.json
$TUT stills  SERIE <id>                  # plano + cuadrícula de stills en videos/<id>/qc/stills.jpg

Mira la cuadrícula de stills (Lee la imagen) antes de renderizar. Verifica:

• el cursor y las ondas de clic caen sobre el elemento correcto;
• los callouts envuelven el elemento;
• el subtítulo coincide con lo que está en pantalla;
• el zoom no está en un área vacía;
• no aparece dato sensible.

Corrige el guion (texto) o regraba solo el paso problemático en una toma-2. El plan usa la toma más nueva que tiene el paso completo. Entonces:

$TUT render SERIE <id>                   # → SERIE/entrega/<id>.mp4 + capítulos + hoja de contactos

Abre la hoja de contactos (entrega/<id>.sheet.jpg) para una última revisión. Ajustes visuales (tema, zoom, música, intro y outro) están en references/edicao.md.

Fase 8: Entrega

1. Ejecuta $TUT deliver SERIE. Genera entrega/LEAME.md con títulos, duraciones y capítulos listos para pegar en YouTube.
2. Muéstrale al usuario la carpeta entrega/ y un resumen (videos, duraciones, lo cubierto).
3. Si puedes enviar archivos, manda el primer MP4.
4. Pregunta antes de ejecutar $TUT clean SERIE, que borra las grabaciones brutas raw.mkv y libera espacio.

Principios

• El guion manda; la grabación obedece. Si la interfaz real difiere del guion, para y ajusta el guion con el usuario. No improvises en la grabación.
• Un paso = una idea en pantalla. Si el subtítulo necesita dos frases, probablemente son dos pasos.
• Muestra, no cuentes. Usa el callout para señalar el elemento. El subtítulo solo nombra la acción.
• Privacidad por defecto. Graba solo el área de la página, usa una cuenta de demostración con datos ficticios y no muestres query strings en la barra. Antes de grabar, cierra lo que no debe aparecer.
• Verifica el resultado con los ojos. Los stills y la hoja de contactos existen para que los mires. No digas al usuario que el video está bien sin haberlo mirado.

Referencias

• references/roteiro.md: descubrimiento de la herramienta, diseño de la serie, preguntas de la entrevista, esquemas de serie.json y guion.json, reglas de texto, ejemplos.
• references/gravacao.md: ventana, calibración, toma paso a paso, API de __tut, recuperación de errores y trampas de Claude in Chrome y macOS.
• references/edicao.md: cómo el editor decide cortes, zoom y cursor, opciones de tema y audio, checklist de QC y solución de problemas.