Communitygithub.com

show-and-tell

Canal bidireccional de señalización con el usuario en una página web en vivo dentro de un navegador compartido. Tú muestras cosas (resaltados, etiquetas, ilustraciones de gestos como tocar/deslizar/arrastrar) y el usuario te muestra cosas (marcas con notas, clics y gestos grabados, mensajes) desde un panel lateral. Incluye visitas guiadas con Siguiente/Anterior y videos de revisión grabados (MP4 con subtítulos, capítulos, tarjetas). Útil para 'muéstrame', 'dónde está…', 'mira lo que marqué/envié/grabé', recorridos, demostraciones, demostración de cambios de código y videos de revisión de clientes.

¿Qué es show-and-tell?

El skill show-and-tell establece un canal de comunicación bidireccional entre el agente de IA y el usuario a través de un navegador Chrome for Testing compartido. El agente puede señalar elementos en la página web usando resaltados, etiquetas e ilustraciones de gestos (como tocar, deslizar, arrastrar), mientras que el usuario puede responder marcando elementos, escribiendo notas, grabando demostraciones de gestos y clics, o enviando mensajes desde un panel lateral. Además de la interacción básica, ofrece funcionalidades opcionales como visitas guiadas paso a paso con botones Siguiente/Anterior y la capacidad de grabar videos de revisión en MP4 con subtítulos, capítulos y tarjetas. Es compatible con herramientas MCP y CLI, y se integra con Playwright MCP para acciones más complejas. El skill está diseñado para trabajar en hosts permitidos (configurados por el usuario por seguridad) y utiliza un 'watcher' en segundo plano para escuchar las acciones del usuario. Es ideal para demostraciones de código, recorridos guiados, revisiones de clientes y cualquier situación donde se necesite una comunicación visual y bidireccional en tiempo real.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Knyrps/agent-skills/tree/main/skills/show-and-tell

Preguntar en tu IA favorita

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

Documentación

¿Qué hace show-and-tell?

Una ventana de Chrome for Testing que tú y el usuario comparten. Tú señalas cosas en la página; el usuario señala de vuelta a través del panel lateral show-and-tell (Anotar, Grabar, mensaje). No se necesita ningún recorrido para ninguno de los dos. Las visitas guiadas y los videos son capas opcionales adicionales. El panel es parte de la interfaz del navegador y nunca aparece en las capturas de pantalla de la página.

<skill> a continuación es el directorio de este skill (la carpeta con este SKILL.md). Los comandos funcionan en cualquier terminal.

Componentes

  • Navegador: Chrome for Testing con su propio perfil, CDP 127.0.0.1:9334, extensión precargada. start_browser lo inicia (idempotente) y abre el panel; sobrevive a la sesión.
  • MCP show-and-tell: start_browser, status, highlight, clear_highlights, hide_overlays, get_queue, wait_for_action, request_demo, set_step, load_tour, goto_step, end_tour, record_tour, stop_recording. Cada uno también existe como CLI: node "<skill>/bridge" <start|status|highlight <css> [--label t] [--gesture g] [--direction d] [--to css] [--url u] [--style s] [--keep]|clear|hide|show|queue [--recent]|wait|cancel|request <prompt>| step <label>|tour <file>|goto <n>|end|record <file> [--name n] [--size s]|record-stop|record-cancel>.
  • Herramientas browser_* del mismo MCP (Playwright MCP, adjunto a este navegador) que conducen la página cuando necesitas más de lo que highlight puede hacer: browser_snapshot, browser_click, browser_type, browser_evaluate, browser_navigate, … Inician el navegador si es necesario y actúan en la pestaña de la aplicación, nunca en el panel. Un servidor playwright separado, si el anfitrión tiene uno, es tu navegador privado que el usuario no ve; úsalo solo para trabajo que el usuario no deba observar.

Trabajando donde el usuario observa

El usuario sigue el navegador compartido; el panel muestra cada llamada browser_* ("haciendo clic en …", "solicitando datos a través de la página"). Mantenlo comprensible:

  • Mostrando o reproduciendo algo: usa la interfaz visible (navegar, hacer clic, escribir), para que la página lo muestre.
  • Leyendo muchos datos (registros, listas, JSON): llamar a la API propia de la aplicación con fetch dentro de browser_evaluate está bien y usa la sesión del usuario, pero nada cambia en la pantalla. Dilo primero en el chat ("Estoy leyendo los registros a través de la API de Grafana en tu pestaña").
  • Mantén estas solicitudes pequeñas (rangos de tiempo cortos, limit): una llamada que se ejecute más de aproximadamente un minuto es cortada por el cliente MCP. Divide rangos largos en lugar de reintentar la misma consulta.

Restricción: hosts permitidos

El navegador compartido contiene los inicios de sesión del usuario, por lo que cada herramienta aquí (señalización, visitas guiadas, videos y browser_*) solo funciona en hosts permitidos. Esta máquina siempre está permitida: localhost, direcciones de bucle local y nombres que el archivo hosts asigna a bucle local. Cualquier otro host, incluso uno privado en otra red, se pregunta en el panel lateral cuando lo usas por primera vez ("No", "Esta sesión", "Siempre"); la llamada espera hasta 2 minutos por la respuesta.

  • No permitido: el usuario no permitió …: respétalo; no reintentes ni busques una forma de evitarlo.
  • … no respondió …: dile al usuario en una línea que el panel está preguntando, luego reintenta una vez.
  • Nunca edites extension/config.json o config.local.json tú mismo; solo el usuario concede hosts.

El vigilante: escuchando al usuario

El usuario puede enviar en cualquier momento. Lo escuchas a través de un vigilante, un trabajo de shell en segundo plano.

  • start_browser, status y cada herramienta que conduce el navegador devuelven watcher. Si running es falso, inicia watcher.command inmediatamente como un trabajo en segundo plano (herramienta de shell, opción background) y no esperes a que termine.
  • Cuando se completa, lleva {"actions": […]}: manéjalos (siguiente sección), luego inicia el vigilante nuevamente. Una finalización con timeout o cancelled y sin acciones: inícialo de nuevo y no digas nada.
  • Mantenlo ejecutándose mientras chateas; nunca lo canceles para responder un mensaje del chat.
  • El panel envía a la sesión que condujo el navegador por última vez y muestra "<sesión> está escuchando".
  • No hay trabajos en segundo plano en este marco: cuando el usuario dice que envió, marcó o grabó algo, llama a get_queue (recent: true también devuelve los elementos entregados de la última hora).

Mostrarle algo al usuario

highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):

  • url abre esa página en la pestaña de la aplicación primero; no se necesita Playwright. Verifica found: false antes de hablar.
  • label: una breve nota explicativa. style: outline (predeterminado), spotlight (difumina el resto), none (sin cuadro).
  • gesture reproduce una ilustración en el elemento; nunca se ejecuta. Táctil: tap, double-tap, long-press, swipe, pinch. Ratón: click, double-click, right-click, hover, drag, scroll. direction: left/right/up/down (swipe, drag, scroll), in/out (pinch). to: CSS de un final de swipe/drag.
  • keep: true agrega a los resaltados actuales; de lo contrario, se reemplazan. clear_highlights los elimina.
  • Prefiere selectores estables (id, data-testid, aria) más text. Explica en el chat en 1–3 oraciones.

Lo que el usuario envía

Cada elemento en actions tiene un type (y step mientras se ejecuta una visita guiada):

  • question: un mensaje (text). Responde en el chat.
  • annotation: el usuario marcó la página ("Anotar": un clic marca un elemento, arrastrar dibuja) y escribió text. Obtienes una imagen en línea que solo tú ves: las marcas numeradas y de colores del usuario con notas, más contornos discontinuos etiquetados 1a, 1b… alrededor de los elementos a los que se refiere cada marca. annotations[] es la leyenda: n, kind (element/rect/arrow/pen), color, rect, flecha from/to, note, elements[] (label, selectors, tag, text, rect). Las coordenadas son coordenadas del documento; imageArea es lo que muestra la imagen. Refiérete a las marcas por número o color y texto del elemento, nunca por las etiquetas 1a. imagePath es la versión propia del usuario.
  • recording: el usuario demostró algo ("Grabar", o tu request_demo, luego con requestId y prompt). recording.steps sigue el formato de Chrome DevTools Recorder (navigate, click con button: "secondary" y modifiers, doubleClick, change, keyDown, scroll) más longPress, swipe y urlChange; los pasos de elemento llevan selectors, tag, text. text es el comentario del usuario. demoDeclined: el usuario descartó tu solicitud.
  • Eventos de visita guiada y video: next/back, agentStep, stepError, tourEnd, videoReady, videoError, videoDiscarded (secciones a continuación).

request_demo({ prompt }) le pide al usuario que te muestre algo; el panel comienza a grabar para ellos.

Visita guiada

  1. Planifica los pasos en el chat: título y qué muestra cada uno, una idea por paso.
  2. Escribe el guión { steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:
    • explanation: 2–5 oraciones, mostradas en el panel.
    • url: navega primero. Atrás reproduce desde el paso anterior más cercano con una url, así que proporciona a cada paso que cambie el estado de la página una url accesible.
    • actions: {click|fill|waitFor|hover|doubleClick|rightClick|longPress|swipe|drag|scroll: css, text?, value?, to?, direction?, ms?}, {scrollBy: px, in?: css}, {press: key, on?: css}, {wait: ms}.
    • highlights: como highlight(); el primero reemplaza, el resto se agregan.
    • agent: true solo para pasos que debes hacer manualmente: actuar, set_step("n/N – título"), resaltar, explicar, luego goto_step(n+1) cuando llegue next. Verifica los selectores primero (browser_evaluate); uno faltante se convierte en stepError.
  3. Inicia: start_browser (inicia el vigilante), verifica bridge.panelOpen, luego load_tour({ tour }) y dile al usuario en una línea que la visita guiada se ejecuta en el panel.
  4. Reacciona: stepError → arregla el paso, load_tour con start: step. tourEnd → end_tour y un breve resumen. Las preguntas y marcas durante una visita guiada se refieren al step actual.

Demostrando cambios de código

  1. Alcance: cambios no confirmados (git diff HEAD), de lo contrario la rama contra su base. Si no está claro: pregunta.
  2. Mapea cada archivo cambiado a la pantalla y elemento donde se muestra su efecto; los cambios sin un efecto visible van en un paso de resumen final.
  3. Aplicación: si no es accesible, inicia su servidor de desarrollo desde los scripts del proyecto como un trabajo en segundo plano. Luego un paso de visita guiada por cambio visible, en el orden natural de la aplicación.

Video de revisión

record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) reproduce una visita guiada con guión por sí misma y graba la pestaña como MP4 con subtítulos, etiquetas de capítulo, barra de progreso, tarjetas de introducción/sección/final, un cursor dibujado o dedo para cada acción, un archivo .vtt y una lista de capítulos. Devuelve inmediatamente; el vigilante luego recibe videoReady { path, vtt, chapters, durationMs, … } o videoError { step, error }. Lee references/video.md antes de escribir un video de visita guiada.

Capturas de pantalla como evidencia

Llama a hide_overlays(true) antes de una captura de pantalla que deba mostrar la página sin adornos, hide_overlays(false) después.

Solución de problemas

  • extensionConnected: false: start_browser de nuevo; la extensión se reconecta en aprox. 15 s y reproduce lo que el usuario envió mientras tanto.
  • bridge not running: el MCP no está adjunto; la CLI (start, wait) funciona por sí sola.
  • Una llamada browser_* dice que el navegador está cerrado: se reconecta una vez por sí solo; si aún falla, start_browser y reintenta.
  • Un navegador sirve una visita guiada o un video a la vez. Si status muestra un paso que no estableciste, otra sesión lo está usando: pregúntale al usuario primero.
  • Chrome for Testing faltante: npx playwright install chromium, o establece DEMO_BROWSER_PATH.

Skills relacionados