Walkthrough-GIF-Skill

Was macht Walkthrough-GIF-Skill?

Erzeugt ein eigenständiges Node.js-Projekt, das einen Browser-Walkthrough aufzeichnet und als MP4 + GIF exportiert.

Wann dieser Skill vs. claude-in-chrome gif_creator verwendet werden sollte

Für eine schnelle, einmalige Aufnahme in der Live-Browser-Sitzung des Nutzers (Eigenes Profil, offene Tabs, bereits eingeloggt) ist das claude-in-chrome gif_creator-Tool wesentlich einfacher – keine Projektgerüste, keine API-Schlüssel. Greifen Sie zu diesem Skill, wenn der Nutzer etwas benötigt, das gif_creator nicht bietet: ein wiederaufrufbares/versionierbares Skript (Neuaufnahme nach jeder UI-Änderung), MP4-Ausgabe, ein hochwertiges gifski-GIF, eine saubere Profilaufnahme (keine persönlichen Lesezeichen/Erweiterungen im Bild) oder CI-Wiederholbarkeit.

Architektur

Natursprachliche Beschreibung
        ↓
Claude generiert TypeScript-Skript
        ↓
Stagehand v3 (KI-Browsersteuerung) – Playwright per CDP verbunden
        ↓
Playwright-Aufnahmekontext erfasst Video (.webm)
        ↓
ffmpeg konvertiert → .mp4
gifski konvertiert Einzelbilder → .gif
        ↓
Ausgabe: walkthrough.mp4 + walkthrough.gif + walkthrough.md

Arbeitsablauf

Schritt 1: Anforderungen sammeln

Voraussetzung – LLM-API-Schlüssel: Stagehand ruft für jede KI-Aktion ein LLM auf. Der Nutzer benötigt ANTHROPIC_API_KEY (oder den zum konfigurierten Modell passenden Anbieter-Schlüssel, z. B. OPENAI_API_KEY) für .env. Bestätigen Sie dies vorab – ohne ihn kann das generierte Skript nicht ausgeführt werden.

Bevor Sie Code generieren, bestätigen Sie:

1. Ziel-URL – Wo beginnt der Walkthrough? (z. B. https://app.example.com/login)
2. Ablaufbeschreibung – Welche Schritte sollen demonstriert werden? (Natürliche Sprache ist in Ordnung)
3. Authentifizierungssituation – Ist die Seite öffentlich oder erfordert sie eine Anmeldung? Falls Anmeldung: Werden Anmeldedaten in .env fest codiert, eine vorauthentifizierte Sitzung/ein Cookie-Export verwendet oder von einem eingeloggten Zustand ausgegangen?
4. Ausgabeformat – Nur GIF, nur MP4 oder beides? (Standard: beides)
5. Dauer/Tempo – Schnelle Demo oder bewusst Schritt für Schritt? (~1-2 s Pause zwischen den Schritten ist Standard)
6. Viewport – Standard ist 1280×800. Schmaler für mobile Demos.

Wenn der Nutzer eine ausführliche Beschreibung liefert, leiten Sie so viel wie möglich ab und fragen Sie nur nach Lücken.

Schritt 2: Projekt generieren

Geben Sie ein vollständiges, ausführbares Projekt unter ./walkthrough-[name]/ aus:

walkthrough-[name]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   └── walkthrough.ts      ← Hauptskript
└── scripts/
    └── convert.sh          ← ffmpeg + gifski Konvertierung

Lesen Sie references/stagehand-patterns.md für die Stagehand-API und Schritte-Übersetzungsmuster. Lesen Sie references/output-pipeline.md für die ffmpeg/gifski-Konvertierungsbefehle und GIF-Optimierung.

Schritt 3: Schritte übersetzen

Konvertieren Sie die natürliche Sprache des Nutzers in stagehand.act()-Aufrufe (v3: act() lebt auf der Stagehand-Instanz und akzeptiert einen einfachen String mit Optionen wie variables und page). Siehe references/stagehand-patterns.md für Muster und Fallstricke.

Wichtige Übersetzungsregeln:

• Jede logische UI-Aktion = ein stagehand.act("...", { page })-Aufruf mit einer klaren englischen Anweisung
• Texteingaben erfolgen über variables (%name%-Platzhalter) – niemals Geheimnisse inline in den Anweisungsstring
• Fügen Sie zwischen wichtigen Schritten page.waitForTimeout(1500) ein, um das Tempo zu steuern (für den Betrachter sichtbar)
• Fügen Sie nach Navigationen page.waitForLoadState('networkidle') ein
• Codieren Sie niemals Selektoren fest – Stagehand ermittelt diese aus natürlichen Sprachinstruktionen
• Bei Abläufen mit Authentifizierung: Verwenden Sie .env für Anmeldedaten, niemals fest codieren

Schritt 4: Aufnahmestrategie

Verwenden Sie immer die Playwright-Videoaufnahme als primäre Aufnahmemethode:

• Stagehand v3 hat keine integrierte Aufnahme – verbinden Sie Playwright mit Stagehands Browser über chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() }), erstellen Sie einen Kontext mit der recordVideo-Option und steuern Sie die Seite dieses Kontexts (siehe references/stagehand-patterns.md)
• Nehmen Sie die gesamte Sitzung als .webm über diesen Aufnahmekontext auf
• Versuchen Sie NICHT, einzelne Screenshots direkt zu einem GIF zusammenzusetzen – Video → Einzelbilder → GIF ist qualitativ höherwertiger
• Nach Abschluss des Skripts führen Sie convert.sh aus, um MP4 und GIF zu erzeugen

Machen Sie GIF niemals zum primären Artefakt. MP4 wird immer zuerst erstellt. GIF wird daraus abgeleitet. GIFs sind groß und von geringer Qualität für alles über 15 Sekunden – warnen Sie den Nutzer und schlagen Sie vor, Walkthroughs unter 60 s zu halten.

Schritt 5: Klick-/Cursor-Overlays (optional, aber empfohlen)

Fügen Sie vor Beginn des Walkthroughs ein Klick-Highlight-Overlay über page.addInitScript() ein. Siehe references/stagehand-patterns.md → Abschnitt „Click Overlay" für den Codeausschnitt.

Dies fügt eine dezente Wellenanimation an jedem Klickpunkt hinzu – macht Walkthroughs ohne Nachbearbeitung deutlich lesbarer.

Schritt 6: Ausgabe

Nach der Generierung produzieren Sie:

1. Das Projektverzeichnis (alle Dateien)
2. Eine kurze Einrichtungs-Checkliste im Gespräch:

## Einrichtung
npm install
npx playwright install chromium
cp .env.example .env  # ANTHROPIC_API_KEY und ggf. Anmeldedaten eintragen

## Ausführen
npx tsx src/walkthrough.ts

## In GIF + MP4 konvertieren
bash scripts/convert.sh

Sagen Sie dem Nutzer auch, was ihn erwartet: ungefähre Dauer, Viewport-Größe, Ausgabedateinamen.

Bieten Sie an, es auszuführen: Claude Code kann die gesamte Pipeline selbst ausführen – npm install, npx playwright install chromium, das Walkthrough-Skript ausführen, dann bash scripts/convert.sh – wenn der Nutzer zustimmt (er muss noch die .env-Werte bereitstellen). Wenn Sie es selbst ausführen, überprüfen Sie die Ausgabe, bevor Sie Erfolg melden: ffprobe für das MP4 auf eine sinnvolle Dauer und prüfen Sie, ob die GIF-/MP4-Dateigrößen nicht trivial sind (convert.sh gibt diese im abschließenden Verifikationsteil aus).

---

Warnungen / Abbruchbedingungen

Weisen Sie den Nutzer vorab darauf hin, wenn einer dieser Fälle zutrifft:

Bedingung	Hinweis
Seite erfordert Anmeldung mit MFA/SSO	Skript kann dies nicht automatisch handhaben – Nutzer muss Cookies aus einer eingeloggten Browser-Sitzung exportieren
CAPTCHA auf der Zielseite	Playwright bleibt hängen – stattdessen Demo-/Sandbox-Umgebung verwenden
Starke Animationen / unendliche Scrollbereiche	Aufnahme wird diese erfassen, aber GIF-Konvertierung wird groß – Kürzung vorschlagen
Ablauf länger als 90 Sekunden	Nur MP4 empfehlen; GIF wird unbrauchbar groß
Seiteninhalt ist randomisiert/dynamisch	Stagehand bewältigt visuelles Targeting, aber vor unterschiedlichen Aussehen bei Wiederholungen warnen

---

Namenskonvention für Ausgaben

walkthrough-[slug]/
  output/
    walkthrough.webm     ← rohe Playwright-Aufnahme
    walkthrough.mp4      ← konvertiert (H.264, websicher)
    walkthrough.gif      ← gifski-Ausgabe, max. 800px breit
    walkthrough.md       ← Schritt-für-Schritt-Anmerkung (automatisch generiert)

Die .md-Datei listet jeden act()-Aufruf als nummerierten Schritt mit Zeitstempeln auf – nützlich zum Einbetten als Bildunterschrift neben dem GIF.

---

Referenzdateien

• references/stagehand-patterns.md – Stagehand-API, Schritte-Übersetzung, Klick-Overlay-Codeausschnitt, Authentifizierungsmuster
• references/output-pipeline.md – ffmpeg-Befehle, gifski-Flags, GIF-Optimierung, Fehlerbehebung