Communitygithub.com

show-and-tell

Canal de pointage bidirectionnel avec l'utilisateur sur une page web en direct dans un navigateur partagé. Vous montrez des choses (surlignages, étiquettes, illustrations de gestes comme tap/swipe/drag) et l'utilisateur vous montre des choses (marques avec notes, clics et gestes enregistrés, messages) depuis un panneau latéral. En plus : visites guidées avec Suivant/Retour et vidéos de révision enregistrées (MP4 avec sous-titres, chapitres, cartes). Utilisez pour « montre-moi », « où est… », « regarde ce que j’ai marqué/envoyé/enregistré », démonstrations, démonstrations de modifications de code et vidéos de révision client.

Qu'est-ce que show-and-tell ?

La compétence **show-and-tell** établit un canal de communication bidirectionnel entre un agent IA et un utilisateur sur une page web partagée via une fenêtre Chrome for Testing. L'agent peut pointer des éléments avec des surlignages, étiquettes et gestes illustrés, tandis que l'utilisateur peut répondre via un panneau latéral en annotant, enregistrant des démonstrations ou envoyant des messages. Cette compétence est particulièrement utile pour les démos, les revues de code, les visites guidées et les demandes de type « montre-moi où se trouve… ». Elle repose sur trois composants : un navigateur partagé (Chrome for Testing avec extension préchargée et CDP), un ensemble d'outils MCP/CLI pour le pointage et les interactions, et un « watcher » qui écoute les actions de l'utilisateur en arrière-plan. Les outils incluent `highlight`, `clear_highlights`, `get_queue`, ainsi que des fonctions de tour guidé (`load_tour`, `goto_step`, `end_tour`) et d’enregistrement vidéo (`record_tour`). Les fonctionnalités avancées comprennent les visites guidées pas à pas (avec script JSON, relecture et gestion des erreurs), l’enregistrement de démonstrations utilisateur via une interface d’enregistrement, et la production de vidéos MP4 autonomes avec sous-titres et chapitres. Un mécanisme de garde-fou limite le navigateur aux hôtes autorisés par l’utilisateur (hôtes locaux ou explicitement approuvés). L’agent doit toujours maintenir le watcher actif, réagir aux actions utilisateur (questions, annotations, enregistrements, événements de tour), et utiliser les outils `browser_*` (Playwright) pour les interactions avancées dans la page, tout en gardant l’utilisateur informé des actions invisibles à l’écran.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait show-and-tell ?

Une fenêtre Chrome for Testing que vous et l'utilisateur partagez. Vous pointez vers des éléments dans la page ; l'utilisateur pointe en retour via le panneau latéral show-and-tell (Annoter, Enregistrer, Message). Aucune visite guidée n'est nécessaire pour l'un ou l'autre. Les visites guidées et les vidéos sont des couches optionnelles supplémentaires. Le panneau fait partie de l'interface du navigateur et n'apparaît jamais dans les captures d'écran de la page.

<skill> ci-dessous est le répertoire de cette compétence (le dossier contenant ce SKILL.md). Les commandes fonctionnent dans n'importe quel shell.

Composants

  • Navigateur : Chrome for Testing avec son propre profil, CDP 127.0.0.1:9334, extension préchargée. start_browser le lance (idempotent) et ouvre le panneau ; il survit à la session.
  • 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. Chacun existe aussi en 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>.
  • Outils browser_* du même MCP (Playwright MCP, attaché à ce navigateur) pilotent la page lorsque vous avez besoin de plus que ce que highlight peut faire : browser_snapshot, browser_click, browser_type, browser_evaluate, browser_navigate, … Ils démarrent le navigateur si nécessaire et agissent dans l'onglet de l'application, jamais dans le panneau. Un serveur playwright distinct, si l'hôte en possède un, est votre navigateur privé que l'utilisateur ne voit pas ; utilisez-le uniquement pour un travail que l'utilisateur ne doit pas regarder.

Travailler là où l'utilisateur regarde

L'utilisateur suit le navigateur partagé ; le panneau montre chaque appel browser_* (« clic sur … », « demande de données via la page »). Maintenez-le compréhensible :

  • Pour montrer ou reproduire quelque chose : utilisez l'interface visible (naviguer, cliquer, taper) afin que la page l'affiche.
  • Pour lire beaucoup de données (journaux, listes, JSON) : appeler l'API propre de l'application avec fetch dans browser_evaluate est acceptable et utilise la session de l'utilisateur, mais rien ne change à l'écran. Dites-le d'abord dans le chat (« Je lis les journaux via l'API Grafana dans votre onglet »).
  • Gardez ces requêtes petites (plages de temps courtes, limit) : un appel qui dure plus d'une minute environ est interrompu par le client MCP. Divisez les longues plages plutôt que de réessayer la même requête.

Garde-fou : hôtes autorisés

Le navigateur partagé contient les connexions de l'utilisateur, donc chaque outil ici (pointage, visites guidées, vidéos et browser_*) ne fonctionne que sur les hôtes autorisés. Cette machine est toujours autorisée : localhost, les adresses de boucle locale et les noms que le fichier hosts associe à la boucle locale. Tout autre hôte, même privé sur un autre réseau, est demandé dans le panneau latéral lors de la première utilisation (« Non », « Cette session », « Toujours ») ; l'appel attend jusqu'à 2 minutes la réponse.

  • Non autorisé : l'utilisateur n'a pas autorisé … : respectez-le ; ne réessayez pas et ne cherchez pas de contournement.
  • … n'a pas répondu … : dites à l'utilisateur en une ligne que le panneau demande, puis réessayez une fois.
  • Ne modifiez jamais extension/config.json ou config.local.json vous-même ; seuls les utilisateurs accordent l'accès aux hôtes.

Le watcher : écouter l'utilisateur

L'utilisateur peut envoyer à tout moment. Vous l'entendez via un watcher, un job shell en arrière-plan.

  • start_browser, status et chaque outil qui pilote le navigateur renvoient watcher. Si running est faux, démarrez watcher.command immédiatement en tant que job d'arrière-plan (outil shell, option background) et n'attendez pas.
  • Lorsqu'il se termine, il contient {"actions": [...]} : gérez-les (section suivante), puis redémarrez le watcher. Une fin avec timeout ou cancelled sans actions : redémarrez-le et ne dites rien.
  • Gardez-le actif pendant que vous discutez ; ne l'annulez jamais pour répondre à un message du chat.
  • Le panneau envoie à la session qui a piloté le navigateur en dernier et affiche « écoute ».
  • Pas de jobs d'arrière-plan dans ce contexte : lorsque l'utilisateur dit avoir envoyé, marqué ou enregistré quelque chose, appelez get_queue (recent: true renvoie également les éléments livrés de la dernière heure).

Montrer quelque chose à l'utilisateur

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

  • url ouvre cette page dans l'onglet de l'application d'abord ; pas besoin de Playwright. Vérifiez found: false avant de parler.
  • label : une courte annotation. style : outline (par défaut), spotlight (assombrit le reste), none (pas de boîte).
  • gesture boucle une illustration sur l'élément ; elle n'est jamais exécutée. Tactile : tap, double-tap, long-press, swipe, pinch. Souris : click, double-click, right-click, hover, drag, scroll. direction : left/right/up/down (swipe, drag, scroll), in/out (pinch). to : CSS d'une fin de swipe/drag.
  • keep: true ajoute aux surlignages actuels ; sinon ils sont remplacés. clear_highlights les supprime.
  • Préférez les sélecteurs stables (id, data-testid, aria) plus text. Expliquez dans le chat en 1 à 3 phrases.

Ce que l'utilisateur envoie

Chaque élément dans actions a un type (et step pendant une visite guidée) :

  • question : un message (text). Répondez-y dans le chat.
  • annotation : l'utilisateur a marqué la page (« Annoter » : un clic marque un élément, un glissement dessine) et a écrit text. Vous recevez une image en ligne que vous seul voyez : les marques numérotées et colorées de l'utilisateur, les notes, ainsi que des contours en pointillés étiquetés 1a, 1b… autour des éléments auxquels chaque marque se réfère. annotations[] est la légende : n, kind (element/rect/arrow/pen), color, rect, arrow from/to, note, elements[] (label, selectors, tag, text, rect). Les coordonnées sont des coordonnées du document ; imageArea est ce que l'image montre. Référez-vous aux marques par numéro ou couleur et texte de l'élément, jamais par les étiquettes 1a. imagePath est la version de l'utilisateur.
  • recording : l'utilisateur a démontré quelque chose (« Enregistrer », ou votre request_demo, puis avec requestId et prompt). recording.steps suit le format de Chrome DevTools Recorder (navigate, click avec button: "secondary" et modifiers, doubleClick, change, keyDown, scroll) plus longPress, swipe et urlChange ; les étapes d'élément portent selectors, tag, text. text est le commentaire de l'utilisateur. demoDeclined : l'utilisateur a rejeté votre demande.
  • Événements de visite et vidéo : next/back, agentStep, stepError, tourEnd, videoReady, videoError, videoDiscarded (sections ci-dessous).

request_demo({ prompt }) demande à l'utilisateur de vous montrer quelque chose ; le panneau commence l'enregistrement pour lui.

Visite guidée

  1. Planifiez les étapes dans le chat : titre et ce que chacune montre, une idée par étape.
  2. Scénarisez { steps: [{ title, explanation, url?, actions?, highlights?, agent? }] } :
    • explanation : 2 à 5 phrases, affichées dans le panneau.
    • url : naviguer d'abord. Le retour reprend depuis l'étape antérieure la plus proche avec une url, donc donnez à chaque étape qui change l'état de la page une url accessible.
    • 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 : comme highlight() ; la première remplace, les suivantes s'ajoutent.
    • agent: true uniquement pour les étapes que vous devez faire à la main : agissez, set_step("n/N – title"), mettez en surbrillance, expliquez, puis goto_step(n+1) lorsque next arrive. Vérifiez d'abord les sélecteurs (browser_evaluate) ; un sélecteur manquant devient stepError.
  3. Démarrez : start_browser (démarrez le watcher), vérifiez bridge.panelOpen, puis load_tour({ tour }) et dites à l'utilisateur en une ligne que la visite guidée s'exécute dans le panneau.
  4. Réagissez : stepError → corrigez l'étape, load_tour avec start: step. tourEnd → end_tour et un court résumé. Les questions et les marques pendant une visite se réfèrent à l'étape step en cours.

Démontrer des modifications de code

  1. Périmètre : modifications non validées (git diff HEAD), sinon la branche par rapport à sa base. Si ce n'est pas clair, demandez.
  2. Mappez chaque fichier modifié à l'écran et à l'élément où son effet apparaît ; les modifications sans effet visible vont dans une étape récapitulative de clôture.
  3. Application : si elle n'est pas accessible, démarrez son serveur de développement à partir des scripts du projet en tant que job d'arrière-plan. Ensuite, une étape de visite par changement visible, dans l'ordre naturel de l'application.

Vidéo de révision

record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) joue une visite scénarisée toute seule et enregistre l'onglet en MP4 avec sous-titres, étiquettes de chapitre, barre de progression, cartes d'intro/section/outro, un curseur dessiné ou un doigt pour chaque action, un fichier .vtt et une liste de chapitres. Elle retourne immédiatement ; le watcher reçoit ensuite videoReady { path, vtt, chapters, durationMs, … } ou videoError { step, error }. Lisez references/video.md avant d'écrire une visite vidéo.

Captures d'écran de preuve

Appelez hide_overlays(true) avant une capture d'écran qui doit montrer la page brute, hide_overlays(false) après.

Dépannage

  • extensionConnected: false : relancez start_browser ; l'extension se reconnecte dans environ 15 s et rejoue ce que l'utilisateur a envoyé entre-temps.
  • bridge not running : le MCP n'est pas attaché ; la CLI (start, wait) fonctionne seule.
  • Un appel browser_* indique que le navigateur est fermé : il se reconnecte une fois tout seul ; si cela échoue encore, start_browser et réessayez.
  • Un navigateur sert une visite ou une vidéo à la fois. Si status montre une étape que vous n'avez pas définie, une autre session l'utilise : demandez d'abord à l'utilisateur.
  • Chrome for Testing manquant : npx playwright install chromium, ou définissez DEMO_BROWSER_PATH.

Skills associés