clickreel

Was macht clickreel?

Du erstellst eine interaktive Demo der echten App des Benutzers. Ein Besucher öffnet sie auf einer Landing Page oder über einen Link, klickt auf die hervorgehobene Stelle, und der nächste echte Bildschirm der App erscheint. Er entscheidet in unter einer Minute, ob die App einen Versuch wert ist. Ein gutes Ergebnis führt in 6 bis 12 Klicks durch eine Sache, die die App gut kann.

Du schreibst das Storyboard und beurteilst das Ergebnis. Clickreel erledigt den Rest: Es öffnet die App in einem Headless-Browser, führt jeden Schritt real aus, fotografiert die Seite vorher und nachher und verpackt die Bildschirme und einen Player in eine HTML-Datei.

Der Befehl

Alles läuft über ein Skript. Es benötigt nur Node und einen bereits auf dem Rechner installierten Chromium-basierten Browser.

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <Befehl>

Wenn ${CLAUDE_SKILL_DIR} oben als wörtlicher Text erscheint, hat dein Agent ihn nicht ausgefüllt: Verwende den Ordner, der diese SKILL.md enthält.

Befehl	Was er tut
build <Storyboard>	Führt die Schritte aus und schreibt <Name>.html (die Demo) und <Name>.stops.png (das Kontaktblatt) neben das Storyboard. Dauert 10 bis 30 Sekunden.
check <Storyboard>	Führt die Schritte aus und schreibt nur das Kontaktblatt, in einen temporären Ordner. Verwende es, um ein Storyboard auszuprobieren, ohne das Projekt zu berühren.
doctor	Überprüft, ob dieser Rechner eine Demo erstellen kann. Führe es zuerst aus, wenn etwas beim Start fehlschlägt.
init [Datei]	Schreibt ein Start-Storyboard.

Nützliche Flags: --out <Verzeichnis>, --json, --headed (Browser bei der Arbeit beobachten), --force.

Wie man arbeitet

1. Entscheide, was die Demo zeigt

Eine Demo, ein Ablauf. Frage dich, was das überzeugendste Feature dieser App ist, und baue die Demo darum herum. Wenn der Benutzer ein Feature oder einen Ablauf genannt hat, ist das das Thema. Wenn er nur "mach eine Demo" gesagt hat, wähle selbst den Kernablauf (das, was der erste Satz der README verspricht) und sage, welchen du gewählt hast. Frage den Benutzer nicht, sich zu entscheiden, es sei denn, die App hat mehrere unabhängige Produkte.

2. Bringe die App zum Laufen und lerne ihre echten Bezeichnungen kennen

Finde heraus, wie die App startet (package.json-Skripte, eine README, ein dist/-Ordner). Wähle dann eine Option:

• Läuft bereits oder du kannst sie selbst starten: Setze "url".
• Eine statische Seite oder ein gebauter Ordner: Setze "serve": "./dist" und Clickreel serviert sie.
• Du möchtest, dass der Build später wiederholbar ist: Setze "start": "npm run dev" mit "url", und Clickreel startet sie und wartet.

Schritte zielen auf Elemente anhand der Wörter, die ein Mensch sieht: Schaltflächentext, das Label oder der Platzhalter eines Feldes, ein aria-label. Lese die Komponenten für den von dir gewählten Ablauf und kopiere die Labels genau. Raten kostet eine Runde.

Die Demo sollte auf einem Zustand öffnen, der einen Blick wert ist. Ein leerer Erste-Schritte-Bildschirm oder eine Anmelde-Wand ist ein schwacher Einstieg. Wenn die App Daten oder eine angemeldete Sitzung benötigt, richte diese vor dem ersten Stopp ein: Verwende das Seed-Skript der App oder einen eval-Schritt, der in localStorage schreibt, oder melde dich zu Beginn mit einem Testkonto an. Setze Passwörter und Tokens in Umgebungsvariablen und beziehe dich darauf als ${env:NAME}; schreibe niemals ein echtes Geheimnis in das Storyboard.

3. Schreibe das Storyboard

Speichere es als demo.click.json im Projektstamm, es sei denn, der Benutzer möchte es woanders haben. Wenn das Projekt bereits ein Demoreel-Storyboard (*.reel.json) hat, kannst du direkt aus dieser Datei bauen.

{
  "url": "http://localhost:5173",
  "displayUrl": "acme.app",
  "demo": {
    "title": "Acme",
    "intro": "Erlebe, wie ein Projekt von der Idee bis zur Fertigstellung geht.",
    "cta": { "label": "Kostenlos testen", "url": "https://acme.app/signup" }
  },
  "steps": [
    { "say": "Starte ein Projekt in Sekunden" },
    { "click": "Neues Projekt" },
    { "type": "Website Launch", "into": "Projektname" },
    { "click": "Projekt erstellen" },
    { "say": "Füge Aufgaben so schnell hinzu, wie du tippen kannst" },
    { "type": "Den Ankündigungsbeitrag schreiben", "into": "Aufgabe hinzufügen" },
    { "press": "Enter" }
  ]
}

Jeder Schritt wird zu einem Stopp (etwas, das der Besucher tut) oder zu nichts:

Schritt	In der Demo
{ "click": "Neues Projekt" }	Ein Hotspot auf dem Element. Der Besucher klickt darauf und sieht das echte Ergebnis.
{ "type": "hallo", "into": "E-Mail" }	Ein Hotspot auf dem Feld. Ein Klick darauf spielt das Tippen des Textes ab. Lasse into weg, um im fokussierten Feld weiterzutippen.
{ "press": "Enter" }	Tastenkappen zum Klicken, oder der Besucher drückt die echte Taste. "Mod+K" ist Cmd auf macOS und Strg woanders.
{ "hover": "Diagramm" }	Ein Hotspot, der auf Berühren reagiert, oder auf einen Tipp auf einem Telefon.
{ "select": "Pro", "in": "Tarif" }	Ein Hotspot auf einem nativen Dropdown.
{ "say": "Ein kurzer Satz" }	Die Beschriftung, die während der darauf folgenden Stopps angezeigt wird. Sie bleibt bis zum nächsten say. Ein say ohne nachfolgenden Stopp wird zu einer Karte mit einem Weiter-Button.
{ "zoom": "Gesamt" }	Ein Hinweis: Das Element wird beleuchtet, der Rest der Seite wird abgedunkelt, und eine Karte zeigt die Beschriftung mit einem Weiter-Button.
{ "scroll": 600 }, { "goto": "/einstellungen" }, { "wait": 800 }, { "waitFor": "Bericht bereit" }, { "eval": "..." }	Kein Stopp. Die Demo durchläuft sie von selbst. Verwende sie für die Einrichtung und um an die richtige Stelle zu gelangen.

Die Wörter neben jedem Hotspot werden für dich geschrieben: Klicke „Neues Projekt“, Tippe „Website Launch“, Drücke mit den Tastenkappen. Füge "hint": "Öffne die Einstellungen" zu einem Schritt hinzu, um es auf deine eigene Weise zu sagen. Tu dies, wenn ein Schritt einen Selektor verwendet, der keinen lesbaren Namen hat (die Voreinstellung ist dann "Hier klicken").

Ziele werden anhand von sichtbaren Namen abgeglichen, zuerst exakte Übereinstimmung. Wenn ein Name mehrdeutig ist, füge "nth": 2 hinzu oder verwende einen Selektor: "css=.sidebar button", "#save", "testid=submit". Füge "optional": true zu einem Schritt hinzu, der möglicherweise nichts zum Handeln hat, z. B. das Schließen eines Cookie-Banners.

Die vollständige Liste der Schritte, Optionen, Stile und Rahmen befindet sich in references/storyboard.md. Lese sie, bevor du etwas verwendest, das hier nicht gezeigt wird.

4. Bauen

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json

Ein Schritt, der nicht ausgeführt werden kann, stoppt den Build und sagt dir genau, was falsch ist:

Schritt 4 (klicke "Projekt erstellen") fehlgeschlagen: Konnte "Projekt erstellen" nicht zum Klicken finden.
  Meintest du: "Projekt erstellen"?
  Aktuell auf dem Bildschirm: "Abbrechen", "Projekt erstellen", "Projektname"
  Screenshot der Seite zu diesem Zeitpunkt: /tmp/clickreel/demo-123/step-04-failed.jpg

Korrigiere den Schritt und baue erneut. Wenn das Projekt bereits eine <Name>.html hat, die Clickreel nicht geschrieben hat, weigert sich der Build, sie zu ersetzen: Setze "name" im Storyboard oder übergib --out <Verzeichnis>.

Ein erfolgreicher Build kann trotzdem Hinweise ausgeben. Lese sie. Hinweis: Schritt 4 (...) hat nichts Sichtbares auf der Seite verändert bedeutet, dass der Schritt etwas zum Handeln gefunden hat, die Seite aber danach gleich aussah: Er hat fast immer das falsche Element gefunden, und sein Stopp in der Demo tut nichts. Korrigiere das Ziel (einen genaueren Namen, nth oder einen Selektor) und baue erneut.

5. Betrachte das Ergebnis, bevor du es meldest

build schreibt ein Kontaktblatt, <Name>.stops.png: ein Bild pro Stopp, mit dem eingezeichneten Hotspot und dem Schritt und der Beschriftung darunter, dann der letzte Bildschirm. Öffne es und betrachte jedes Bild. So überprüfst du deine eigene Demo.

Überprüfe jedes Bild auf:

• Den Hotspot. Befindet sich das Kästchen auf dem Element, das du meintest, und ist dieses Element sichtbar? Ein Kästchen auf dem falschen Element bedeutet, dass der Name mit etwas anderem übereingestimmt hat: Verwende nth oder einen Selektor.
• Wahrheit. Zeigt das Bild die funktionierende App? Achte auf Fehlermeldungen, leere Zustände, Spinner, die nie fertig wurden, Platzhaltertexte. Jedes Bild zeigt, was der Besucher sieht, bevor er klickt, also zeigt das Bild danach, was sein Klick bewirkt hat.
• Beschriftungen. Beschreibt die Beschriftung unter dem Bild, was darin passiert?
• Das letzte Bild. Es liegt hinter der Endkarte. Es sollte der am besten aussehende Zustand der App sein.

Korrigiere das Storyboard und baue erneut. Zwei oder drei Runden sind normal. Höre auf, wenn das Blatt richtig aussieht.

6. Übergib es

Sage dem Benutzer, wo die Datei ist, ihre Größe, wie viele Stopps sie hat und welchen Ablauf sie zeigt. Gib ihm die Einbettungszeile, die build ausgegeben hat:

<iframe src="demo.html" title="Acme: interaktive Demo" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>

Sage klar, was die Datei ist: eine HTML-Datei mit Bildern seiner App darin, die von der Festplatte und von jedem Webhost funktioniert und nichts aus dem Netzwerk lädt. Melde alle Hinweise, die Clickreel ausgegeben hat (Seitenfehler, verdeckte Elemente, eine große Datei). Wenn du einen Schritt nicht zum Laufen bringen konntest und entfernt hast, sage es.

Eine GitHub-README kann keine HTML-Datei ausführen. Verlinke für eine README auf die Demo, wo sie gehostet wird (GitHub Pages serviert docs/ gut), oder verwende ein GIF von Demoreel.

Eine gute Demo schreiben, kurz gefasst

• Sechs bis zwölf Stopps. Jeder Stopp ist ein Klick, den der Besucher machen muss. Schneide die Einrichtung weg oder erledige sie mit eval vor dem ersten Stopp.
• Beschriftungen sind Überschriften. Sieben Wörter oder weniger, über den Nutzen („Erledige Dinge, während du gehst"), nicht über die Aktion („Klicke jetzt auf die Checkbox"). Der Hinweis sagt bereits, worauf geklickt werden soll. Drei bis fünf Beschriftungen in einer Demo.
• Gib echte Dinge ein. "Website Launch", nicht "test" oder "asdf". Der eingegebene Text ist Teil des Pitch.
• Öffne und schließe gut. Setze demo.title und einen einzeiligen demo.intro für die Startkarte. Beende mit dem besten Zustand der App und setze demo.cta auf das, was der Besucher als Nächstes tun soll.
• Wähle die Größe für den Ort, an dem sie sitzen wird. Der Standard-Viewport desktop passt zu einer Landing Page. Für eine mobile Web-App verwende "viewport": "phone". Ein kleinerer Viewport lässt die App in einem kleinen Embed größer erscheinen.

Mehr zu Struktur, Hinweisen, Autoplay und dem Hören auf die Ereignisse der Demo: references/writing.md.

Datenschutz und Ehrlichkeit

• Alles läuft auf diesem Rechner. Clickreel öffnet keine eigene Netzwerkverbindung; der Browser lädt nur die App, auf die du ihn verweist. Die fertige Datei stellt keine Anfragen und verfolgt nichts.
• Die Demo besteht aus Bildern von dem, was auf der Seite war, und ist zur Veröffentlichung bestimmt. Verwende Testkonten und erfundene Daten. Erfasse keine echten Kundendaten, echten E-Mail-Adressen oder internen URLs ohne die Zustimmung des Benutzers.
• Zeige die App so, wie sie ist. Verwende eval nicht, um ein Feature vorzutäuschen, einen echten Fehler zu verstecken oder etwas schneller erscheinen zu lassen, als es ist. Das Vorbereiten von Daten und das Ausblenden von Entwickler-Overlays ist in Ordnung; das Erfinden von Verhalten nicht.

Was es nicht kann

Nur Web-Apps. Die Bildschirme sind Bilder, daher kann ein Besucher innerhalb eines Stopps nicht scrollen, Text auswählen oder den von dir gewählten Pfad verlassen. Ein drag-Schritt wird abgespielt, wenn auf seinen Hotspot geklickt wird. Es folgt keinen Links, die einen neuen Tab öffnen, kann nicht in iframes eindringen und kann keine Dateien hochladen. Native alert()- und confirm()-Fenster werden automatisch akzeptiert und erscheinen nicht. Wenn der Ablauf von einem dieser Dinge abhängt, sage es und baue den Teil, der funktioniert.

Wenn etwas auf eine Weise fehlschlägt, die die Fehlermeldung nicht erklärt, siehe references/troubleshooting.md.