Communitygithub.com

show-and-tell

Canal de apontamento bidirecional com o usuário em uma página web ao vivo em um navegador compartilhado. Você mostra coisas (destaques, rótulos, ilustrações de gestos como toque/deslizar/arrastar) e o usuário mostra coisas para você (marcações com notas, cliques e gestos gravados, mensagens) em um painel lateral. Além disso: tours guiados com Anterior/Próximo e vídeos de revisão gravados (MP4 com legendas, capítulos, cartões). Use para 'mostre-me', 'onde está…', 'veja o que marquei/enviei/gravei', walkthroughs, demonstrações, demonstração de alterações de código e vídeos de revisão do cliente.

O que é show-and-tell?

O skill show-and-tell cria um canal de comunicação bidirecional entre o agente de IA e o usuário por meio de um navegador Chrome compartilhado. Ele permite que o agente aponte elementos na página com destaque visual, rótulos e gestos animados, enquanto o usuário responde com anotações, gravações de cliques e gestos, ou mensagens de texto por meio de um painel lateral dedicado. Suporta tours guiados com etapas, ações automáticas e gravação de vídeos de revisão em MP4 com legendas e capítulos. É especialmente útil para demonstrações de funcionalidades, revisão de alterações de código e análises colaborativas. O skill funciona em qualquer ambiente com Chrome for Testing e utiliza uma extensão do navegador para comunicação em tempo real, garantindo que apenas hosts permitidos pelo usuário sejam acessados.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que show-and-tell faz?

Uma janela do Chrome for Testing que você e o usuário compartilham. Você aponta para coisas na página; o usuário aponta de volta através do painel lateral show-and-tell (Anotar, Gravar, mensagem). Nenhum tour é necessário para nenhum dos dois. Tours guiados e vídeos são camadas opcionais adicionais. O painel é parte da interface do navegador e nunca aparece em capturas de tela da página.

<skill> abaixo é o diretório deste skill (a pasta com este SKILL.md). Os comandos funcionam em qualquer shell.

Peças

  • Navegador: Chrome for Testing em seu próprio perfil, CDP 127.0.0.1:9334, extensão pré-carregada. start_browser o inicia (idempotente) e abre o painel; ele sobrevive à sessão.
  • 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 um também 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>.
  • Ferramentas browser_* do mesmo MCP (Playwright MCP, anexado a este navegador) dirigem a página quando você precisa de mais do que highlight pode fazer: browser_snapshot, browser_click, browser_type, browser_evaluate, browser_navigate, … Elas iniciam o navegador se necessário e atuam na guia do aplicativo, nunca no painel. Um servidor playwright separado e simples, se o host tiver um, é seu navegador privado que o usuário não vê; use-o apenas para trabalho que o usuário não deve observar.

Trabalhando onde o usuário assiste

O usuário acompanha o navegador compartilhado; o painel mostra cada chamada browser_* ("clicando em …", "solicitando dados através da página"). Mantenha-o acompanhável:

  • Mostrar ou reproduzir algo: use a interface visível (navegue, clique, digite), para que a página mostre.
  • Ler muitos dados (logs, listas, JSON): chamar a própria API do aplicativo com fetch dentro de browser_evaluate é aceitável e usa a sessão do usuário, mas nada muda na tela. Diga isso no chat primeiro ("Estou lendo os logs através da API do Grafana na sua guia").
  • Mantenha tais requisições pequenas (intervalos de tempo curtos, limit): uma chamada que dura mais de cerca de um minuto é interrompida pelo cliente MCP. Divida intervalos longos em vez de repetir a mesma consulta.

Barreira: hosts permitidos

O navegador compartilhado contém os logins do usuário, então toda ferramenta aqui (apontamento, tours, vídeos e browser_*) funciona apenas em hosts permitidos. Esta máquina é sempre permitida: localhost, endereços de loopback e nomes que o arquivo hosts mapeia para loopback. Qualquer outro host, mesmo privado em outra rede, é perguntado no painel lateral quando você o usar pela primeira vez ("Não", "Esta sessão", "Sempre"); a chamada aguarda até 2 minutos pela resposta.

  • Não permitido: o usuário não permitiu …: respeite; não repita nem procure uma maneira de contornar.
  • … não respondeu …: diga ao usuário em uma linha que o painel está perguntando, então repita uma vez.
  • Nunca edite extension/config.json ou config.local.json você mesmo; apenas o usuário concede hosts.

O ouvinte: ouvindo o usuário

O usuário pode enviar a qualquer momento. Você o ouve através de um ouvinte, um trabalho em segundo plano no shell.

  • start_browser, status e toda ferramenta que dirige o navegador retornam watcher. Se running for falso, inicie watcher.command imediatamente como um trabalho em segundo plano (ferramenta de shell, opção background) e não aguarde.
  • Quando ele completa, carrega {"actions": [...]}: lide com eles (próxima seção), então inicie o ouvinte novamente. Uma conclusão com timeout ou cancelled e nenhuma ação: inicie-o novamente e não diga nada.
  • Mantenha-o em execução enquanto você conversa; nunca o cancele para responder a uma mensagem do chat.
  • O painel envia para a sessão que dirigiu o navegador por último e mostra "<sessão> está ouvindo".
  • Sem trabalhos em segundo plano neste ambiente: quando o usuário disser que enviou, marcou ou gravou algo, chame get_queue (recent: true também retorna os itens entregues na última hora).

Mostrar algo ao usuário

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

  • url abre essa página na guia do aplicativo primeiro; nenhum Playwright necessário. Verifique found: false antes de falar.
  • label: uma pequena legenda. style: outline (padrão), spotlight (escurece o resto), none (sem caixa).
  • gesture reproduz uma ilustração no elemento; nunca é executado. Toque: tap, double-tap, long-press, swipe, pinch. Mouse: click, double-click, right-click, hover, drag, scroll. direction: left/right/up/down (swipe, drag, scroll), in/out (pinch). to: CSS de um fim de swipe/drag.
  • keep: true adiciona aos destaques atuais; caso contrário, eles são substituídos. clear_highlights os remove.
  • Prefira seletores estáveis (id, data-testid, aria) mais text. Explique no chat em 1–3 frases.

O que o usuário envia

Cada item em actions tem um type (e step enquanto um tour está em execução):

  • question: uma mensagem (text). Responda no chat.
  • annotation: o usuário marcou a página ("Anotar": um clique marca um elemento, arrastar desenha) e escreveu text. Você recebe uma imagem inline que só você vê: as marcas numeradas e coloridas do usuário e notas mais contornos tracejados rotulados 1a, 1b… ao redor dos elementos a que cada marca se refere. annotations[] é a legenda: n, kind (element/rect/arrow/pen), color, rect, arrow from/to, note, elements[] (label, selectors, tag, text, rect). As coordenadas são coordenadas do documento; imageArea é o que a imagem mostra. Refira-se às marcas pelo número ou cor e texto do elemento, nunca pelos rótulos 1a. imagePath é a própria versão do usuário.
  • recording: o usuário demonstrou algo ("Gravar", ou seu request_demo, então com requestId e prompt). recording.steps segue o formato do Chrome DevTools Recorder (navigate, click com button: "secondary" e modifiers, doubleClick, change, keyDown, scroll) mais longPress, swipe e urlChange; etapas de elemento carregam selectors, tag, text. text é o comentário do usuário. demoDeclined: o usuário descartou sua solicitação.
  • Eventos de tour e vídeo: next/back, agentStep, stepError, tourEnd, videoReady, videoError, videoDiscarded (seções abaixo).

request_demo({ prompt }) pede ao usuário que mostre algo; o painel começa a gravar para ele.

Tour guiado

  1. Planeje as etapas no chat: título e o que cada uma mostra, uma ideia por etapa.
  2. Roteirize { steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:
    • explanation: 2–5 frases, mostradas no painel.
    • url: navegue primeiro. Voltar reproduz a partir da etapa anterior mais próxima com um url, então dê a cada etapa que muda o estado da página uma url acessível.
    • 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(); o primeiro substitui, os restantes são adicionados.
    • agent: true apenas para etapas que você deve fazer manualmente: aja, set_step("n/N – título"), destaque, explique, então goto_step(n+1) quando next chegar. Verifique seletores primeiro (browser_evaluate); um ausente se torna stepError.
  3. Inicie: start_browser (inicie o ouvinte), verifique bridge.panelOpen, então load_tour({ tour }) e diga ao usuário em uma linha que o tour está em execução no painel.
  4. Reaja: stepError → corrija a etapa, load_tour com start: step. tourEnd → end_tour e um breve resumo. Perguntas e marcações durante um tour referem-se à etapa current.

Demonstrando alterações de código

  1. Escopo: alterações não commitadas (git diff HEAD), caso contrário, o branch contra sua base. Se não estiver claro: pergunte.
  2. Mapeie cada arquivo alterado para a tela e elemento onde seu efeito aparece; alterações sem efeito visível vão para uma etapa de resumo final.
  3. Aplicativo: se não estiver acessível, inicie seu servidor de desenvolvimento a partir dos scripts do projeto como um trabalho em segundo plano. Então, uma etapa de tour por alteração visível, na ordem natural do aplicativo.

Vídeo de revisão

record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) reproduz um tour roteirizado por conta própria e grava a guia como MP4 com legendas, rótulos de capítulo, barra de progresso, cartões de introdução/seção/fim, um cursor desenhado ou dedo para cada ação, um arquivo .vtt e uma lista de capítulos. Ele retorna imediatamente; o ouvinte então recebe videoReady { path, vtt, chapters, durationMs, … } ou videoError { step, error }. Leia references/video.md antes de escrever um tour em vídeo.

Capturas de tela de evidência

Chame hide_overlays(true) antes de uma captura de tela que deve mostrar a página limpa, hide_overlays(false) depois.

Solução de problemas

  • extensionConnected: false: start_browser novamente; a extensão reconecta em ~15 s e reproduz o que o usuário enviou enquanto isso.
  • bridge not running: o MCP não está anexado; a CLI (start, wait) funciona por conta própria.
  • Uma chamada browser_* diz que o navegador está fechado: ele reconecta uma vez por conta própria; se ainda falhar, start_browser e repita.
  • Um navegador serve um tour ou vídeo por vez. Se status mostrar uma etapa que você não definiu, outra sessão está usando-o: pergunte ao usuário primeiro.
  • Chrome for Testing ausente: npx playwright install chromium, ou defina DEMO_BROWSER_PATH.

Habilidades Relacionadas