Vorschau: HTML-Seite mit auswählbaren Kommentaren
Verwandle jeden Plan, Vorschlag, Entwurf oder jede Endfassung in ein HTML-Dokument, in dem man „Text auswählen → Kommentar hinterlassen“ kann, und öffne es auf dem Computer des Nutzers (oder seines Kunden) zur Überprüfung. Nach dem Ansehen kann der Nutzer auf „Alle kopieren“ klicken – Kommentare und Ankreuzungen werden als Markdown ausgegeben, das zurück in den Chat eingefügt werden kann, um die Änderungen nachzuvollziehen.
Wo befindet sich dieses Skill
Das Verzeichnis, in dem diese Datei liegt, ist das Skill-Verzeichnis (im Folgenden als $SKILL_DIR bezeichnet). Setze es vor jeder Ausführung:
SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/preview}"
[ -f "$SKILL_DIR/scripts/md-to-preview.py" ] || SKILL_DIR="$(cd "$(dirname "$(find "$HOME/.claude/skills" .claude/skills -path '*/preview/scripts/md-to-preview.py' 2>/dev/null | head -1)")/.." && pwd)"
echo "$SKILL_DIR"
- Es wird nur Python 3.9 oder höher benötigt – ausschließlich die Standardbibliothek, keine Installation über pip nötig.
- Auf macOS wird
python3verwendet; falls unter Windows der Befehlpython3nicht existiert, nutzepythonoderpy. - Falls das Skill-Verzeichnis nicht gefunden wird, stoppe und teile dem Nutzer mit, dass der
preview-Ordner unter~/.claude/skills/abgelegt sein muss. Erstelle keine eigene Kommentarfunktion.
| Datei | Zweck |
|---|---|
scripts/md-to-preview.py | Haupt-Generator: wandelt Markdown in eine Vorschauseite um |
scripts/convert/inject.py | Fügt einem bereits formatierten HTML die Kommentarfunktion hinzu |
scripts/convert/visuals.py, flow.py, tables.py | Visuelle Komponenten, Flussdiagramme und Tabellenkonvertierung (werden vom Generator automatisch aufgerufen) |
assets/preview-comment-overlay.html | Overlay für auswählbare Kommentare |
assets/preview-tokens.css | Farben, Schriftarten, Abstände; zum Anpassen des Aussehens hier ändern |
assets/fonts/ | Mitgelieferte Schriftarten: Noto Sans TC, Geist, Geist Mono (SIL OFL-Lizenz) |
assets/example.md | Vollständiges Beispiel: ein fiktiver Angebotsvorschlag, der alle Komponenten zeigt |
Regel 1: Kommentare sind immer „auswählbar“
Wenn der Nutzer sagt „Kommentar hinzufügen“ oder „Version mit Kommentaren“, ist damit immer gemeint: Text auswählen → Kommentar hinterlassen – wie in Google Docs. Es geht nicht um ein Eingabefeld neben jedem Absatz. Die Kommentaroberfläche dieses Skills ist genau diese Auswähl-Funktion – verwende sie direkt, baue nichts Eigenes.
Regel 2: Erst umschreiben, dann generieren
Seitenart bestimmen
| Art | Beispiele | Vorgehen |
|---|---|---|
| Erklärend | Pläne, Vorschläge, Berichte, Vergleiche, Entscheidungsseiten | Nach der untenstehenden Schreibweise umschreiben und dann generieren – nicht den Arbeitsentwurf direkt in den Generator geben |
| Original-Review | Verträge, endgültige Texte, Transkripte, Kundentexte | Am Inhalt kein Wort ändern, mit --no-lint generieren; höchstens ein > [!Fazit] am Anfang einfügen, das erklärt, worum es auf dieser Seite geht |
Schreibweise für erklärende Texte
- Auf der ersten Seite alles Wesentliche: Ganz oben mit
> [!Fazit]einen Satz zum Ergebnis, dann> [!Deine Entscheidung]mit den Aufgaben für den Leser. Hintergrundinformationen kommen später – der Leser kann entscheiden, ohne zu scrollen. - Jede Information nur einmal: Was im Fazit-Kasten steht, wird im Fließtext nicht wiederholt. Was in einer Grafik oder Tabelle gezeigt wird, wird nicht zusätzlich als Absatz beschrieben. Kein „Zusammenfassung“-Abschnitt.
- Einfache Sprache: Verwende die alltäglichen Wörter des Lesers. Fachbegriffe beim ersten Mal mit einem Vergleich erklären oder mit
> [!Einfach gesagt]eine Erläuterung einfügen. - Zeichnen statt schreiben: Frage zuerst „Welche Beziehung beschreibt dieser Abschnitt?“, dann wähle die Komponente aus der Tabelle. Reiner Text maximal drei Zeilen pro Absatz; jeder
##-Abschnitt enthält mindestens eine grafische Komponente oder Tabelle. - Kurz: Ein Satz, ein Punkt. Streiche Formulierungen wie „mit anderen Worten“, „das heißt“, „bemerkenswert ist“.
- Gestrichen wird nur Wiederholung, nicht Information: Zahlen, Daten, Namen, Konsequenzen – nichts davon darf fehlen oder verändert werden.
Schnellübersicht grafischer Komponenten
Schreibe ein paar Zeilen in Kurzsyntax, der Generator zeichnet die Grafik. Trenner mit vollbreitem Pfeil ｜, Pfeil →. Vollständige Beispiele in assets/example.md.
| Beschreibt … | Komponente | Syntax |
|---|---|---|
| Alt vs. Neu, Vorher vs. Nachher | Vergleich | ```Vergleich: erste Zeile Vorher → Nachher, dann jede Zeile Punkt｜Alt → Neu |
| Systemaufbau, Datenfluss | Architektur | ```Architektur: eine Zeile pro Ebene Ebene｜Kasten, Kasten; innerhalb der Ebene: A → B; zwischen Ebenen: ↓ Beschreibung |
| Was wann passiert | Zeitleiste | ```Zeitleiste: jede Zeile Zeit｜Titel｜Beschreibung; ✅ für erledigt, 👉 für aktuell |
| Reihenfolge, Schritte, Kausalkette | Schritte | ```Schritte: jede Zeile Titel｜Beschreibung, automatisch nummeriert; bis zu 4 Schritte horizontal, ab 5 vertikal |
| Wichtige Zahlen | Zahlen | ```Zahlen: jede Zeile Zahl Einheit｜Label｜Anmerkung; ein Leerzeichen zwischen Zahl und Einheit wandelt die Einheit in kleinere Schrift |
| Alternativen, Rollen, parallele Einträge | Karten | ```Karten (auch Optionen, Aufteilung): jede Zeile Titel｜Zeile｜Zeile; ★ markiert die empfohlene Option |
| Mehrspaltiger Vergleich | Tabelle | Standard-Markdown-Tabelle. Wenn die Kopfzeile gleichzeitig „Vorher/Alt“ und „Nachher/Neu/Vorschlag“ enthält, wird die alte Spalte automatisch grau, die neue hellgrün |
| Verzweigte Abläufe | Flusskarten | ASCII- oder mermaid-Flussdiagramme (graph/flowchart mit TD, LR); falls die Umwandlung nicht gelingt, bleibt das Original erhalten |
| Fazit, Entscheidung, Hinweis, Risiko | Hervorhebungskasten | > [!Fazit] Titel, ab nächster Zeile > Inhalt. Verfügbare Typen: Fazit, Deine Entscheidung, Hinweis, Risiko, Erledigt, Einfach gesagt, Erklärung |
| Status | Farbmarkierung | Inline {grün:Erledigt} {gelb:Wartet auf dich} {rot:Blockiert} {blau:In Bearbeitung} {grau:Nicht gemacht} |
| Schlüsselwörter in einem Satz | Hervorhebung | ==Schlüsselwort==, maximal eine Stelle pro Absatz |
- Farben haben feste Bedeutung: Blau = Fazit und Information, Grün = Erledigt und Nachher, Gelb = Hinweis und Warten, Rot = Risiko und Blockiert. „Deine Entscheidung“ kommt nur einmal pro Seite vor.
- Syntaxfehler brechen die Seite nicht – es wird nur als grauer Codeblock angezeigt. Prüfe nach der Generierung, ob eine Grafik als grauer Block erscheint.
- Bei zeitlicher oder kausaler Abfolge: Schritte oder Zeitleiste. Wenn die Punkte unabhängig sind: Karten.
- Der Text in Grafiken ist echter Text und kann ebenfalls ausgewählt und kommentiert werden.
Seiten-Check
Bei der Generierung wird automatisch ein „Seiten-Check“ ausgegeben: fehlender Fazit-Kasten am Anfang, zu lange reine Textabschnitte, zu wenige grafische Komponenten, Füllwörter, Gedankenstriche, doppelte Informationen usw. Bei Aufforderung die Markdown-Datei korrigieren und neu generieren, bis „Seiten-Check: Bestanden“ erscheint. Bei Original-Review-Seiten --no-lint verwenden.
Ressourcen sparen
- Grafiken immer in Kurzsyntax, kein handgeschriebenes HTML oder SVG, keine externen Bilder.
- Inhalte durch Bearbeiten der Markdown-Datei und erneutes Generieren ändern, nicht direkt im ausgegebenen HTML.
- Sehr lange Listen mit
--fold "3"einklappen.
Regel 3: Immer den Generator verwenden
- Vorschauseiten immer mit
scripts/md-to-preview.py(Markdown-Quelle) oderscripts/convert/inject.py(bereits formatiertes HTML) generieren – kein eigenes CSS schreiben, keine eigene Kommentarfunktion bauen. - Für Aussehen-Änderungen
assets/preview-tokens.cssbearbeiten und den Generator neu ausführen.
Ablauf
Schritt 1: Quelle und Identität festlegen
Aus dem Chat ableiten, wenn nicht möglich nachfragen:
- Was soll in die Vorschau? (gerade geschriebener Inhalt, Datei vom Nutzer)
- Wer wird kommentieren? Standard-Identitäten:
ich,Gast. Für Kunden z. B.Kunde,ich(erste ist die Standard-Identität).
Bei Inhalten aus dem Chat: zuerst als .md-Datei speichern, im aktuellen Arbeitsverzeichnis des Nutzers (falls nicht vorhanden, im Ordner Vorschau auf dem Desktop). Dateiname auf Deutsch und beschreibend, z. B. Vorschlag-Beispielkunde.md.
Schritt 2: Seite generieren
Quelle ist Markdown (häufigster Fall):
python3 "$SKILL_DIR/scripts/md-to-preview.py" "<Quelle>.md" "<Ausgabe>.html" \
--identities "ich,Gast" --badges "Entwurf,2026-10-19"
| Parameter | Wirkung |
|---|---|
--identities | Liste der Identitäten, durch Komma getrennt; erste ist Standard |
--badges | Graue kleine Labels unter dem Titel, durch Komma getrennt; ohne Angabe keine Anzeige |
--key | Name, unter dem Kommentare im Browser gespeichert werden; pro Seite eindeutig; ohne Angabe wird der Ausgabedateiname verwendet |
--title | Dokumenttitel; ohne Angabe wird der erste #-Titel aus der Markdown-Datei verwendet |
--fold "3,4" | Überschriften der angegebenen Ebenen als aufklappbare Abschnitte darstellen – für lange Seiten |
--no-lint | Kein Seiten-Check (für Verträge, Endfassungen usw.) |
--no-overlay | Saubere Version ohne Kommentarfunktion |
--icon | Zeichen oder Emoji im Tab-Symbol; ohne Angabe wird das erste Zeichen des Titels verwendet |
--fonts copy/link/none | Schriftarten-Verarbeitung; Standard ist copy |
Schriftarten: Standardmäßig wird neben dem ausgegebenen HTML ein Ordner preview-fonts/ erstellt. 🚨 Wenn die Seite an jemand anderen weitergegeben wird: HTML und preview-fonts/-Ordner zusammen packen. Nur das HTML zu verschicken führt zu Systemschriften (funktioniert noch, sieht aber schlechter aus).
Bilder: Eine einzelne -Zeile in der Markdown-Datei wird zu einer Abbildung mit Bildunterschrift; der Pfad ist relativ zum ausgegebenen HTML.
Quelle ist bereits formatiertes HTML (z. B. selbst erstellte Angebotsseite): Layout bleibt erhalten, nur Kommentarfunktion wird hinzugefügt.
python3 "$SKILL_DIR/scripts/convert/inject.py" "<Seite>.html" -o "<Seite>-mit-Kommentaren.html" --identities "ich,Kunde"
-omuss ein neuer Dateiname sein; das Tool überschreibt nicht die Quelle.- Wenn die Seite bereits eine Kommentarfunktion hat und durch eine neue ersetzt werden soll:
--replaceverwenden.
Schritt 3: Für den Nutzer öffnen
Mit dem Standard-Browser des Systems öffnen:
# macOS
open "<Ausgabe>.html"
# Windows (Claude-Terminal ist Git Bash → `start`; PowerShell → `Start-Process "<Ausgabe>.html"`)
start "" "<Ausgabe>.html"
# Linux
xdg-open "<Ausgabe>.html"
Dem Nutzer drei Dinge mitteilen:
- Beliebigen Text auswählen – es erscheint „Neuer Kommentar“.
- Kästchen können direkt angeklickt werden.
- Nach dem Durchsehen oben rechts auf „Alle kopieren“ klicken und den Inhalt zurück in den Chat einfügen.
Schritt 4 (optional): Für Kunden kommentierbar machen
- HTML und den dazugehörigen
preview-fonts/-Ordner als ZIP packen und an den Kunden senden. Er soll die ZIP entpacken und die HTML-Datei doppelklicken. - Identität auf die Rolle des Kunden setzen, z. B.
--identities "Kunde,ich". - Kommentare werden im Browser des Kunden gespeichert und nicht automatisch synchronisiert. Bitte den Kunden, nach dem Durchsehen „Alle kopieren“ zu klicken und den Text per E-Mail oder Nachricht zurückzusenden.
Ankreuz-Bestätigung
Wenn der Nutzer aus einer Liste von Punkten einzeln entscheiden muss und die Optionen feststehen, erstelle eine Ankreuz-Liste – der Nutzer soll nicht tippen müssen. Beispiele: welche Funktionen umgesetzt werden sollen, welche Materialien ausgewählt werden, Checkliste vor dem Go-Live. Bei nur einer oder zwei Optionen oder wenn eine Begründung nötig ist, reicht direktes Fragen oder die auswählbaren Kommentare.
Wie schreiben
In der Markdown-Datei als Checkliste notieren, der Generator wandelt sie in anklickbare Kästchen um:
### Unbedingt umsetzen
- [x] Bestellformular (Kunde füllt aus, landet automatisch in der DB)
- [ ] Schichtkalender (jeder Mitarbeiter sieht nur seine Schichten)
- [ ]= nicht angekreuzt,- [x]= standardmäßig angekreuzt.- Jede Gruppe unter einer eigenen Überschrift (
##oder###): Beim Export wird nach „der nächstgelegenen vorherigen Überschrift“ gruppiert. - Jeder Punkt muss einen Namen und eine kurze Erklärung enthalten, sodass er allein verständlich ist – nicht nur „ja“/„nein“.
- Unter derselben Überschrift dürfen keine zwei identischen Optionstexte stehen.
Was auf der Nutzerseite passiert
- Der Ankreuz-Status bleibt im Browser erhalten, auch nach einem Neuladen. „Zurücksetzen“ löscht nur Kommentare, nicht die Ankreuzungen.
- Nach Klick auf „Alle kopieren“ wird vorangestellt:
## Ankreuz-Ergebnis (angekreuzt: 2/5)
### Umfangsklärung › Unbedingt umsetzen
- [x] Bestellformular (Kunde füllt aus, landet automatisch in der DB)
- [ ] Schichtkalender (jeder Mitarbeiter sieht nur seine Schichten)
Beim Erhalt von Ankreuz-Ergebnissen
- Das Ankreuz-Ergebnis unverändert als Datei speichern und danach genau danach arbeiten – nicht aus dem Gedächtnis neu tippen.
- Nicht angekreuzte Punkte werden nicht umgesetzt oder bleiben wie gehabt – keine eigene Entscheidung treffen.
- Wenn in derselben Gruppe widersprüchliche Optionen angekreuzt wurden, beim Nutzer nachfragen.
- Wenn externe Aktionen betroffen sind (E-Mail versenden, Dateien löschen, Go-Live), erst die endgültige Liste präsentieren und warten, bis der Nutzer sagt „Mach es“.
Umgang mit eingegangenen „Kommentar-Zusammenfassungen“
Wenn der Nutzer „Alle kopieren“ drückt und den Inhalt zurückschickt, enthält dieser: den ausgewählten Originaltext (Zitat), die Position (Abschnittsüberschrift), den Kontext und den Kommentar.
Einzeln interpretieren
| Aussehen des Kommentars | Interpretation |
|---|---|
| Nur ein neuer Text, kein Verb | Ersetzen: Zitat durch Kommentartext ersetzen |
| „Löschen“, „Entfernen“ | Zitierten Abschnitt löschen (nur den Bereich des Zitats) |
| „Hinzufügen“, „Ergänzen“, „darunter ein weiterer“ | Neu: In der Nähe des Zitats Inhalte einfügen |
| Beschreibend („Könnte man …?“, „Ich wünschte …“) | Entsprechend der Anforderung ändern |
| Vage, mehrere Interpretationen möglich | Die minimalinvasive Änderung wählen und bei der Rückmeldung klar angeben, welche Variante gewählt wurde |
- Zuerst mit „Position“ und „Kontext“ die richtige Stelle im Dokument finden. Wenn derselbe Text mehrmals vorkommt, den Kontext nutzen, um sicherzustellen, dass nur eine Stelle geändert wird.
- Kommentare aus derselben Runde können sich mit denen der vorherigen Runde überschneiden – zuerst prüfen, welche bereits umgesetzt wurden.
Anwenden, neu generieren, erneut öffnen
- Die Markdown-Quelldatei bearbeiten, dann mit demselben Befehl und demselben
--keyden Generator neu ausführen – nicht direkt das ausgegebene HTML ändern (es würde beim nächsten Durchlauf überschrieben). Nur mit demselben Key bleiben alte Kommentare erhalten. - Die Seite erneut für den Nutzer öffnen.
- Rückmeldung geben: Punkt für Punkt auflisten „welcher Kommentar → was wurde geändert“. Bei vagen Kommentaren die getroffene Wahl anmerken.
Technische Notizen (für Claude, nicht für den Nutzer bestimmt)
- Kommentarverankerung erfolgt über „ausgewählten Text + Kontext“ – auch bei geringfügigen Textänderungen kann die Position neu zugeordnet werden. Falls nicht möglich, wird „Originaltext geändert“ markiert.
- Hervorhebung nutzt die CSS Custom Highlight API des Browsers – keine Änderung der Seitenstruktur. Unterstützt in Chrome, Edge und neueren Safari-Versionen. In nicht unterstützten Browsern fehlt die gelbe Hervorhebung, die Seitenleiste mit Kommentaren funktioniert aber normal.
- Kommentare und Ankreuzungen werden im
localStoragedes Browsers gespeichert. Jede Seite verwendet einen eigenen--key, sonst würden Kommentare verschiedener Seiten vermischt. - Nach dem Laden der Kommentaroberfläche steht
window.PreviewCommentszur Verfügung:.refresh()aktualisiert die Hervorhebungen,.data()gibt alle Kommentare aus,.exportMd()liefert den exportierten Markdown. - Der z-Index von modalen Fenstern der Seite muss unter 10400 liegen, damit die Kommentar-Buttons nicht verdeckt werden.