Communitygithub.com

HTML-Erklärer

Zeigt einem Agenten, wie man eine „HTML-Erklärseite“ plant, erstellt oder anpasst, sodass das konkrete Ergebnis ein nutzbarer Text oder ein Skript ist. Der Ablauf umfasst HTML-Erklärseiten, Dateien in diesem Skill und das Aussehen. Verwende es, wenn eine neue Aufgabe dieses Handwerk erfordert.

Was ist HTML-Erklärer?

Dieser Skill befähigt einen KI-Agenten, interaktive HTML-Erklärseiten zu erstellen, die Benutzer in einem Browser lesen und per Cmd+Klick direkt in VS Code bearbeiten können. Die Seiten sind minimal gehalten und enthalten nur die vom Benutzer angefragten Informationen, wobei sie standardmäßig ein dunkles Design mit blauen Pillen-Links verwenden. Der Skill folgt einer strikten Dateistruktur: Eine Vorlage (`assets/template.html`) dient als Startpunkt, und verschiedene Referenzdateien (`references/DESIGN.md`, `references/page.md`, `references/writing.md`, `references/diagrams.md`) definieren das Aussehen, die Seitenstruktur, Schreibregeln und Diagrammrichtlinien. Der Skill unterstützt Swimlane-Diagramme und playable Swimlanes mit Steuerelementen (Reset/Back/Next/Play) und stellt über ein Workflow-Skript sicher, dass neue Seiten korrekt mit übergeordneten Master-Seiten verknüpft, das Template ausgefüllt, Abschnitte passend zur Anfrage gewählt, Swimlanes korrekt gezeichnet und alle Dateiverweise und Links geprüft werden. Ziel ist es, dem Benutzer präzise, visuell aufbereitete Antworten zu liefern, die ohne überflüssige Inhalte auskommen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

In Ihrer bevorzugten KI fragen

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

Dokumentation

HTML-Erklärseiten

Der Benutzer liest diese Seiten in einem Browser und klickt per Cmd+Klick direkt von ihnen in VS Code. Sie verstehen einen Ablauf aus einer Swimlane viel schneller als aus Absätzen, und sie möchten, dass jede Seite genau das beantwortet, was sie gefragt haben, und nichts weiter.

Dateien in diesem Skill

  • assets/template.html: der Ausgangspunkt jeder Seite. Kopieren, nie eine Seite von Grund auf neu schreiben.
  • references/DESIGN.md: das Design, dem jede Seite folgt, immer in der dunklen Form, mit jedem Link als blauer Pille (references/page.md, „Das Aussehen“). Lesen, wenn eine Seite eine Farbe oder ein Stück benötigt, das die Vorlage nicht hat.
  • references/page.md: Dateiname und -ort, die Seitenleiste, Dateilinks, der Aufgabenabschnitt, der Abschnitt „Verknüpfte Seiten“, Master- und Erklärseiten. Lesen beim Erstellen einer Seite oder Ändern ihrer Struktur.
  • references/writing.md: der Problemabschnitt und jeglicher Fließtext. Lesen vor dem Schreiben von Text.
  • references/diagrams.md: wie eine Swimlane aussieht und wie man sie überprüft. Lesen vor dem Zeichnen oder Bearbeiten eines Diagramms.
  • references/playable.md, assets/player.js, assets/player.css: abspielbare Swimlanes. Lesen, wenn der Benutzer „abspielbar“ sagt oder beim Bearbeiten einer Seite mit einem div.player.

Das Aussehen

Jede Seite folgt references/DESIGN.md, bleibt durchgehend dunkel, mit jedem Link als blauer Pille, damit er als klickbar hervorsticht: unterstrichen für eine Datei, ↗ für eine andere Seite, nichts für einen Abschnitt derselben Seite (references/page.md, „Das Aussehen: DESIGN.md, immer dunkel“ und „Drei Arten von Links“). Die Vorlage macht dies bereits. Jedes Diagramm befindet sich in einem Bereich, den der Leser in der Größe verändern, zoomen und verschieben kann (references/diagrams.md, „Der Diagrammblock“).

Halte die Seite minimal

Eine Seite enthält nur das, wonach der Benutzer gefragt hat. Jeder zusätzliche Abschnitt, jede Tabelle oder Notiz ist etwas, das sie überlesen müssen, um zur Antwort zu gelangen.

  • Abschnitte: nur die, die die Anfrage benötigt. Eine Swimlane mit einem kurzen Absatz darum herum ist ein Abschnitt. Füge niemals einen Abschnitt hinzu, den der Benutzer nicht verlangt hat: keine Zusammenfassungen, keine Bestandsaufnahmen, kein Abschnitt „Gründe“, keine Register früherer Entscheidungen.
  • Tabellen: nur, wenn der Benutzer eine verlangt. Stattdessen Absätze und Swimlanes schreiben.
  • Unter einem Diagramm: nichts. Keine Dateiliste, keine Notizen, keine Zeile „nicht gezeichnet“. Wenn ein Satz zum Lesen des Diagramms nötig ist, steht er im Absatz davor.

Welche Abschnitte eine Anfrage erhält

Passe die Seite an die Frage an:

  • „Was ist das Problem“, Debugging, Beheben eines Fehlers: zuerst der Problemabschnitt (references/writing.md), mit einer Swimlane des Fehlers (auf einer Masterseite, einer abspielbaren, references/playable.md). Danach alle weiteren Swimlanes, die die Erklärung benötigt.

  • Implementieren einer Funktion oder Beheben eines Fehlers, sobald Aufgaben besprochen wurden: ein Aufgabenabschnitt direkt unter dem Problemabschnitt (references/page.md, „Der Aufgabenabschnitt“). Solange der Benutzer das Problem noch ausarbeitet, gibt es noch keine Aufgaben, also gibt es auch keinen Aufgabenabschnitt.

  • „Wie funktioniert das?“, „Worum geht es in diesem Projekt?“: kein Problemabschnitt, kein Aufgabenabschnitt. Eine Swimlane des Ablaufs, mit kurzen Absätzen, wo sie helfen.

  • „Wie würde ich so etwas bauen?“: ein Abschnitt: die übliche Swimlane dafür, welche zusätzlichen Funktionen hinzugefügt werden könnten und wie man vorgeht.

  • Jede Seite, die mit anderen Seiten verknüpft ist (eine Master-Seite mit ihren Erklärseiten oder Seiten, die der Benutzer zu verknüpfen bittet): ein Abschnitt Verknüpfte Seiten ganz unten (references/page.md, „Der Abschnitt Verknüpfte Seiten“).

Alles andere: Beantworte die Frage mit den wenigsten Abschnitten, die sie beantworten.

Diagramme: nur Swimlanes

Es gibt zwei Arten von Diagrammen, und nur zwei:

  1. Swimlane: ein Flussdiagramm mit einer Box pro Akteur oder System, Schritte innerhalb der Box, die sie ausführt, Pfeile über Boxen hinweg, wenn die Arbeit wechselt (references/diagrams.md).
  2. Abspielbare Swimlane: dieselbe Swimlane mit Reset-/Zurück-/Weiter-/Play-Tasten, einem Pfeil pro Drücken und einer Bildunterschrift darunter (references/playable.md). „Abspielbar“, „abspielbare Swimlane“, „abspielbares Diagramm“ und „abspielbares Vorher/Nachher“ bedeuten alle dasselbe. „Swimlane“ allein bedeutet eine einfache.

Jede andere Anfrage nach einem Diagramm („ein Mermaid-Diagramm“, „zeichne den Ablauf“, „ein Diagramm davon“) erhält eine Swimlane.

Arbeitsablauf

  1. Ist dies eine Erklärung einer Masterseite? Durchsuche den Ordner des Tickets nach einem markanten Begriff aus der Anfrage, selbst wenn der Benutzer nur den Text eines Elements einfügt und die Master-Seite nie nennt. Wenn es übereinstimmt, ist die neue Seite die Erklärung dieser Master-Seite: Verwende das Dateinamen-Präfix der Master-Seite und verlinke beide Wege in derselben Änderung (references/page.md).
  2. Erstelle die Datei (references/page.md, „Die Datei“), kopiert von assets/template.html. Fülle die {{…}} Platzhalter aus und ändere den localStorage-Schlüssel toc-open-CHANGE-ME in einen, der für die Seite eindeutig ist.
  3. Entscheide die Abschnitte aus „Welche Abschnitte eine Anfrage erhält“ und schreibe nur diese.
  4. Zeichne die Swimlanes (references/diagrams.md). Vor dem Rendern liste jede Schleife, Verzweigung, jeden Fehlerpfad und jede vorzeitige Rückkehr im abgedeckten Code auf und überprüfe, ob jeder gezeichnet ist.
  5. Verknüpfe jeden Dateiverweis mit #L<Zeile>. Überprüfe, ob jeder Pfad existiert und jede Zielzeile wirklich das sagt, was der Text behauptet.
  6. Führe die unten stehenden Prüfungen durch und melde dann im Chat mit dem Link zur Seite (unten). Wenn irgendetwas, was der Code tut, in einem Diagramm fehlt, sag dies in dieser Antwort.

Prüfungen, bevor es als erledigt gemeldet wird

  • Die Seite hat nur die Abschnitte, die die Anfrage benötigte: kein Problemabschnitt, es sei denn, sie erklärt ein Problem; kein Aufgabenabschnitt, es sei denn, Aufgaben wurden besprochen; keine Tabelle, es sei denn, eine wurde verlangt; nichts unter einem Diagramm.
  • Wo die Seite erklärt, was eine Person gesagt hat oder möchte, sagt ihr erster Satz, was sie wollen, in Worten, die der Benutzer verwenden würde (references/writing.md, „Erklären, was jemand gemeint hat“).
  • Die Seite behält das Aussehen der Vorlage: immer dunkel, jede Farbe aus references/DESIGN.md, jeder Link eine blaue Pille mit ihrem einen Zeichen, kein prefers-color-scheme helles Design, das wieder hinzugefügt wurde (references/page.md, „Das Aussehen“).
  • Legenden benennen Bedeutungen, nicht Farben („wo es schiefgeht“, niemals „ocker = …“); die Seite hat keine Liste ihrer eigenen Farben (references/page.md).
  • Jedes Diagramm ist eine Swimlane: Die Seite hat kein sequenceDiagram, stateDiagram, classDiagram oder einen anderen Diagrammtyp.
  • Rendere jedes Diagramm mit mermaid-cli und betrachte das PNG (references/diagrams.md, „Rendern zur Überprüfung“). Die Seite muss ohne Mermaid-Syntaxfehler laden.
  • Jede Box, die sendet, schreibt, aufruft oder liest, sagt in ihrem Text zu oder von wo und ihr Pfeil endet auf der Box für dieses System. Jeder Aufruf an ein anderes System ist ein Pfeil hinaus plus ein Pfeil zurück, wenn der nächste Schritt die Antwort verwendet.
  • Swimlane-Spuren: durchsuche die Quelle nach [" "] und ghost; es darf keine geben. Im PNG ist keine Spurbreite oder -höhe größer als nötig für ihre eigenen Schritte.
  • Eine abspielbare Swimlane: Schrittweise von Anfang bis Ende und zurück in einem Browser.
  • Jeder Sidebar-href und data-href löst sich zu einer id auf der Seite auf, und jeder Dateilink-Pfad existiert relativ zur Seite.
  • Eine Erklärseite: Die Master-Seite verlinkt darauf, wo immer sie das Thema behandelt, und der Einleitungstext der Erklärung verlinkt zurück.
  • Verknüpfte Seiten: Jede Seite listet die andere in ihrem Abschnitt „Verknüpfte Seiten“, der Abschnitt ist der letzte der Seite, und jeder darin enthaltene Link öffnet eine vorhandene Datei.
  • Nach dem Ändern eines Aufgabenstatus: Ein Durchsuchen listet die Checkbox-Klasse und das Label jeder Aufgabe nebeneinander auf, und alle erledigten Aufgaben sehen gleich aus (references/page.md).
  • Ein durch Automatisierung geöffneter Browser-Tab ist normalerweise im Hintergrund (document.visibilityState === "hidden"), daher feuern dort keine Scroll-Ereignisse. Teste das Scroll-Spy, indem du markActive() nach jedem scrollIntoView() aufrufst, und schließe nicht, dass es defekt ist.

Eine Seite im Chat erwähnen

Wann immer eine Chat-Antwort eine HTML-Seite erwähnt, gib zwei Zeilen an, die der Benutzer direkt in die Adressleiste des Browsers einfügen kann, jede für sich auf einer eigenen Zeile:

file:///Users///_/.html

/Users///_/.html

Die erste Zeile ist die vollständige file:///-URL, die zweite der absolute Pfad auf der Festplatte. Nichts anderes steht auf einer der beiden Zeilen: kein Fließtext, keine Backticks, kein Markdown-Link, kein Aufzählungspunkt, kein >-Blockzitat. Setze bei Bedarf eine kurze Beschreibung auf die Zeile darüber („Füge dies in deinen Browser ein:“). Füge ein #id eines Abschnitts an die URL an, wenn du einen bestimmten Abschnitt meinst, nachdem du überprüft hast, dass die id existiert. Codedateien im Chat behalten die üblichen relativen Links.

Warum: Ein relativer Link öffnet den HTML-Quellcode in VS Code, und ein file:///-Link öffnet die gerenderte Seite im Browser. Eine URL, die in einem Satz vergraben oder in Markdown verpackt ist, muss von Hand herausgesucht werden.

Verwandte Skills