¿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_browserlo 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 quehighlightpuede 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 servidorplaywrightseparado, 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
fetchdentro debrowser_evaluateestá 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.jsonoconfig.local.jsontú 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,statusy cada herramienta que conduce el navegador devuelvenwatcher. Sirunninges falso, iniciawatcher.commandinmediatamente 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 contimeoutocancelledy 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: truetambién devuelve los elementos entregados de la última hora).
Mostrarle algo al usuario
highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):
urlabre esa página en la pestaña de la aplicación primero; no se necesita Playwright. Verificafound: falseantes de hablar.label: una breve nota explicativa.style:outline(predeterminado),spotlight(difumina el resto),none(sin cuadro).gesturereproduce 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: trueagrega a los resaltados actuales; de lo contrario, se reemplazan.clear_highlightslos elimina.- Prefiere selectores estables (id,
data-testid, aria) mástext. 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 etiquetados1a,1b… alrededor de los elementos a los que se refiere cada marca.annotations[]es la leyenda:n,kind(element/rect/arrow/pen),color,rect, flechafrom/to,note,elements[](label,selectors,tag,text,rect). Las coordenadas son coordenadas del documento;imageAreaes lo que muestra la imagen. Refiérete a las marcas por número o color y texto del elemento, nunca por las etiquetas 1a.imagePathes la versión propia del usuario.recording: el usuario demostró algo ("Grabar", o turequest_demo, luego conrequestIdyprompt).recording.stepssigue el formato de Chrome DevTools Recorder (navigate,clickconbutton: "secondary"ymodifiers,doubleClick,change,keyDown,scroll) máslongPress,swipeyurlChange; los pasos de elemento llevanselectors,tag,text.textes 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
- Planifica los pasos en el chat: título y qué muestra cada uno, una idea por paso.
- 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 unaurl, así que proporciona a cada paso que cambie el estado de la página unaurlaccesible.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: comohighlight(); el primero reemplaza, el resto se agregan.agent: truesolo para pasos que debes hacer manualmente: actuar,set_step("n/N – título"), resaltar, explicar, luegogoto_step(n+1)cuando lleguenext. Verifica los selectores primero (browser_evaluate); uno faltante se convierte enstepError.
- Inicia:
start_browser(inicia el vigilante), verificabridge.panelOpen, luegoload_tour({ tour })y dile al usuario en una línea que la visita guiada se ejecuta en el panel. - Reacciona:
stepError→ arregla el paso,load_tourconstart: step.tourEnd→end_toury un breve resumen. Las preguntas y marcas durante una visita guiada se refieren alstepactual.
Demostrando cambios de código
- Alcance: cambios no confirmados (
git diff HEAD), de lo contrario la rama contra su base. Si no está claro: pregunta. - 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.
- 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_browserde 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_browsery reintenta. - Un navegador sirve una visita guiada o un video a la vez. Si
statusmuestra 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 estableceDEMO_BROWSER_PATH.