Communitygithub.com

show-and-tell

Zwei-Wege-Zeigekanal mit dem Benutzer auf einer Live-Webseite in einem gemeinsamen Browser. Sie zeigen Dinge (Hervorhebungen, Beschriftungen, Gestenillustrationen wie Tippen/Wischen/Ziehen) und der Benutzer zeigt Ihnen Dinge (Markierungen mit Notizen, aufgezeichnete Klicks und Gesten, Nachrichten) aus einem Seitenpanel. Zusätzlich: geführte Touren mit Vor/Zurück und aufgezeichnete Review-Videos (MP4 mit Untertiteln, Kapiteln, Karten). Verwenden Sie es für „Zeig mir“, „Wo ist …“, „Schau dir an, was ich markiert/gesendet/aufgezeichnet habe“, Walkthroughs, Demos, Demonstrieren von Code-Änderungen und Kunden-Review-Videos.

Was ist show-and-tell?

Diese Fähigkeit richtet einen gemeinsam genutzten Browser ein, in dem sowohl der KI-Agent als auch der Benutzer interagieren können, um eine kollaborative Web-Erfahrung zu schaffen. Der Agent kann Elemente auf der Seite visuell hervorheben, beschriften und Gesten animieren, während der Benutzer über ein Seitenpanel Markierungen, Notizen, aufgezeichnete Aktionen und Nachrichten senden kann. Darüber hinaus können geführte Touren (mit mehreren Schritten, Navigation und automatischen Aktionen) erstellt und als MP4-Videos mit Untertiteln und Kapiteln aufgezeichnet werden. Dies ist besonders nützlich für „Zeig mir“-Szenarien, Fehlersuche mit visuellem Feedback, Walkthroughs, Demoaufnahmen und das Demonstrieren von Code-Änderungen.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht show-and-tell?

Ein Chrome for Testing-Fenster, das Sie und der Benutzer teilen. Sie zeigen auf Dinge auf der Seite; der Benutzer zeigt durch das show-and-tell-Seitenpanel (Annotieren, Aufnehmen, Nachricht) zurück. Für keinen von beiden ist eine Einführung erforderlich. Geführte Touren und Videos sind optionale zusätzliche Ebenen. Das Panel ist ein Browser-UI und erscheint nie in Seiten-Screenshots.

<skill> unten ist das Verzeichnis dieser Fähigkeit (der Ordner mit dieser SKILL.md). Befehle funktionieren in jeder Shell.

Bestandteile

  • Browser: Chrome for Testing mit eigenem Profil, CDP 127.0.0.1:9334, Erweiterung vorinstalliert. start_browser startet ihn (idempotent) und öffnet das Panel; er überlebt die Sitzung.
  • show-and-tell MCP: 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. Jedes existiert auch als 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>.
  • browser_*-Werkzeuge desselben MCP (Playwright MCP, an diesen Browser gebunden) steuern die Seite, wenn Sie mehr benötigen, als highlight leisten kann: browser_snapshot, browser_click, browser_type, browser_evaluate, browser_navigate, … Sie starten den Browser bei Bedarf und agieren im App-Tab, niemals im Panel. Ein separater einfacher playwright-Server (falls der Host einen hat) ist Ihr privater Browser, den der Benutzer nicht sieht; verwenden Sie ihn nur für Arbeiten, die der Benutzer nicht sehen soll.

Arbeiten, während der Benutzer zuschaut

Der Benutzer folgt dem gemeinsam genutzten Browser; das Panel zeigt jeden browser_*-Aufruf an („klicke …“, „fordere Daten über die Seite an“). Halten Sie es nachvollziehbar:

  • Beim Zeigen oder Nachstellen: Verwenden Sie das sichtbare UI (navigieren, klicken, tippen), damit die Seite es zeigt.
  • Beim Lesen großer Datenmengen (Logs, Listen, JSON): Das Aufrufen der eigenen API der App mit fetch innerhalb von browser_evaluate ist in Ordnung und verwendet die Sitzung des Benutzers, aber es ändert sich nichts auf dem Bildschirm. Sagen Sie das vorher im Chat („Ich lese die Logs über die Grafana-API in Ihrem Tab“).
  • Halten Sie solche Anfragen klein (kurze Zeiträume, limit): Ein Aufruf, der länger als etwa eine Minute läuft, wird vom MCP-Client abgeschnitten. Teilen Sie lange Zeiträume auf, anstatt dieselbe Abfrage zu wiederholen.

Schutzregel: Erlaubte Hosts

Der gemeinsam genutzte Browser enthält die Anmeldungen des Benutzers, daher funktioniert jedes Werkzeug hier (Zeigen, Touren, Videos und browser_*) nur auf erlaubten Hosts. Diese Maschine ist immer erlaubt: localhost, Loopback-Adressen und Namen, die die Hosts-Datei auf Loopback abbildet. Jeder andere Host, selbst ein privater in einem anderen Netzwerk, wird im Seitenpanel nachgefragt, wenn Sie ihn zum ersten Mal verwenden („Nein“, „Diese Sitzung“, „Immer“); der Aufruf wartet bis zu 2 Minuten auf die Antwort.

  • Nicht erlaubt: Der Benutzer hat … nicht erlaubt: Respektieren Sie es; wiederholen Sie es nicht und suchen Sie keinen Weg darum herum.
  • … hat nicht geantwortet …: Teilen Sie dem Benutzer in einer Zeile mit, dass das Panel fragt, und wiederholen Sie es einmal.
  • Bearbeiten Sie niemals extension/config.json oder config.local.json selbst; nur der Benutzer gewährt Hosts.

Der Wächter: Den Benutzer hören

Der Benutzer kann jederzeit senden. Sie hören es über einen Wächter, einen Hintergrund-Shell-Job.

  • start_browser, status und jedes Werkzeug, das den Browser steuert, geben watcher zurück. Wenn running falsch ist, starten Sie watcher.command sofort als Hintergrundjob (Shell-Werkzeug, Hintergrundoption) und warten Sie nicht darauf.
  • Wenn er abgeschlossen ist, enthält er {"actions": [...]}: bearbeiten Sie diese (nächster Abschnitt), starten Sie dann den Wächter erneut. Ein Abschluss mit timeout oder cancelled und keinen Aktionen: Starten Sie ihn erneut und sagen Sie nichts.
  • Lassen Sie ihn laufen, während Sie chatten; brechen Sie ihn niemals ab, um eine Chat-Nachricht zu beantworten.
  • Das Panel sendet an die Sitzung, die den Browser zuletzt gesteuert hat, und zeigt „ hört zu“. Keine Hintergrundjobs in dieser Umgebung: Wenn der Benutzer sagt, dass er etwas gesendet, markiert oder aufgezeichnet hat, rufen Sie get_queue (recent: true gibt auch die letzten ausgelieferten Elemente der letzten Stunde zurück) auf.

Dem Benutzer etwas zeigen

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

  • url öffnet diese Seite zuerst im App-Tab; kein Playwright erforderlich. Überprüfen Sie found: false, bevor Sie sprechen.
  • label: ein kurzer Hinweis. style: outline (Standard), spotlight (verdunkelt den Rest), none (kein Kästchen).
  • gesture zeigt eine Schleifenanimation auf dem Element; sie wird nie ausgeführt. Touch: tap, double-tap, long-press, swipe, pinch. Maus: click, double-click, right-click, hover, drag, scroll. direction: links/rechts/oben/unten (swipe, drag, scroll), rein/raus (pinch). to: CSS eines Swipe/Drag-Endes.
  • keep: true fügt zu den aktuellen Hervorhebungen hinzu; andernfalls werden sie ersetzt. clear_highlights entfernt sie.
  • Bevorzugen Sie stabile Selektoren (id, data-testid, aria) plus text. Erklären Sie im Chat in 1–3 Sätzen.

Was der Benutzer sendet

Jedes Element in actions hat einen type (und step, während eine Tour läuft):

  • question: eine Nachricht (text). Antworten Sie darauf im Chat.
  • annotation: Der Benutzer hat die Seite markiert („Annotieren“: ein Klick markiert ein Element, Ziehen zeichnet) und text geschrieben. Sie erhalten ein Inline-Bild, das nur Sie sehen: die nummerierten, farbigen Markierungen und Notizen des Benutzers plus gestrichelte Umrisse, die mit 1a, 1b … um die Elemente herum beschriftet sind, auf die sich jede Markierung bezieht. annotations[] ist die Legende: n, kind (element/rect/arrow/pen), color, rect, Pfeil from/to, note, elements[] (label, selectors, tag, text, rect). Koordinaten sind Dokumentkoordinaten; imageArea zeigt, was das Bild zeigt. Beziehen Sie sich auf Markierungen anhand der Nummer oder Farbe und des Elementtextes, niemals anhand der 1a-Beschriftungen. imagePath ist die eigene Version des Benutzers.
  • recording: Der Benutzer hat etwas demonstriert („Aufnehmen“ oder Ihre request_demo, dann mit requestId und prompt). recording.steps folgt dem Format von Chrome DevTools Recorder (navigate, click mit button: "secondary" und modifiers, doubleClick, change, keyDown, scroll) plus longPress, swipe und urlChange; Element-Schritte enthalten selectors, tag, text. text ist der Kommentar des Benutzers. demoDeclined: Der Benutzer hat Ihre Anfrage verworfen.
  • Tour- und Video-Ereignisse: next/back, agentStep, stepError, tourEnd, videoReady, videoError, videoDiscarded (Abschnitte unten).

request_demo({ prompt }) bittet den Benutzer, Ihnen etwas zu zeigen; das Panel beginnt für ihn mit der Aufnahme.

Geführte Tour

  1. Planen Sie die Schritte im Chat: Titel und was jeder zeigt, eine Idee pro Schritt.
  2. Skript { steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:
    • explanation: 2–5 Sätze, die im Panel angezeigt werden.
    • url: zuerst navigieren. Zurück wird vom nächstgelegenen vorherigen Schritt mit einer url abgespielt, also geben Sie jedem Schritt, der den Seitenstatus ändert, eine erreichbare url.
    • 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: wie highlight(); der erste ersetzt, die restlichen werden hinzugefügt.
    • agent: true nur für Schritte, die Sie manuell ausführen müssen: handeln, set_step("n/N – titel"), hervorheben, erklären, dann goto_step(n+1) wenn next eintrifft. Überprüfen Sie zuerst die Selektoren (browser_evaluate); ein fehlender wird zu stepError.
  3. Starten: start_browser (Wächter starten), bridge.panelOpen prüfen, dann load_tour({ tour }) und dem Benutzer in einer Zeile mitteilen, dass die Tour im Panel läuft.
  4. Reagieren: stepError → Schritt korrigieren, load_tour mit start: step. tourEnd → end_tour und eine kurze Zusammenfassung. Fragen und Markierungen während einer Tour beziehen sich auf den aktuellen step.

Code-Änderungen demonstrieren

  1. Umfang: nicht committete Änderungen (git diff HEAD), sonst der Branch gegen seine Basis. Unklar: Nachfragen.
  2. Kartieren Sie jede geänderte Datei auf den Bildschirm und das Element, wo ihre Auswirkung sichtbar wird; Änderungen ohne sichtbare Wirkung kommen in einen abschließenden Zusammenfassungsschritt.
  3. App: Wenn sie nicht erreichbar ist, starten Sie ihren Dev-Server aus den Projekt-Skripts als Hintergrundjob. Dann ein Tour-Schritt pro sichtbarer Änderung, in der natürlichen Reihenfolge der App.

Review-Video

record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) spielt eine selbstständig skriptierte Tour ab und zeichnet den Tab als MP4 mit Untertiteln, Kapitelbeschriftungen, Fortschrittsbalken, Intro-/Abschnitts-/Outro-Karten, einem gezeichneten Cursor oder Finger für jede Aktion, einer .vtt und einer Kapitelliste auf. Es kehrt sofort zurück; der Wächter erhält dann videoReady { path, vtt, chapters, durationMs, … } oder videoError { step, error }. Lesen Sie references/video.md, bevor Sie ein Video-Tour schreiben.

Beweis-Screenshots

Rufen Sie hide_overlays(true) vor einem Screenshot auf, der die einfache Seite zeigen soll, hide_overlays(false) danach.

Fehlerbehebung

  • extensionConnected: false: start_browser erneut ausführen; die Erweiterung verbindet sich innerhalb von ~15 s wieder und wiederholt, was der Benutzer in der Zwischenzeit gesendet hat.
  • bridge not running: Das MCP ist nicht verbunden; die CLI (start, wait) funktioniert eigenständig.
  • Ein browser_*-Aufruf sagt, der Browser sei geschlossen: Er verbindet sich einmal von selbst wieder; falls es immer noch fehlschlägt, start_browser und wiederholen.
  • Ein Browser bedient immer nur eine Tour oder ein Video gleichzeitig. Wenn status einen Schritt anzeigt, den Sie nicht gesetzt haben, verwendet ihn eine andere Sitzung: Fragen Sie zuerst den Benutzer.
  • Chrome for Testing fehlt: npx playwright install chromium, oder setzen Sie DEMO_BROWSER_PATH.

Verwandte Skills