Communitygithub.com

khollingworth/d2-diagram-skill

Claude Code-Plugin, das professionelle D2-Architekturdiagramme (TALA/ELK) mit einer selbstprüfenden Render-Schleife erstellt.

Was ist d2-diagram-skill?

Diese Fertigkeit ermöglicht es Claude Code, D2-Quellcode zu schreiben, zu rendern und das gerenderte SVG-Bild visuell zu überprüfen – in einer Schleife – bis das Diagramm versandfertig ist. Sie stellt sicher, dass kein Diagramm ungesehen bleibt, indem sie den Benutzer auffordert, das Ergebnis zu prüfen und Layoutprobleme automatisch oder manuell zu beheben. Die Fertigkeit unterstützt mehrere Layout-Engines (TALA, ELK, dagre) mit einem intelligenten Fallback-Mechanismus, der Wasserzeichen vermeidet. Sie ist in Claude Code integriert, nutzt geskriptete Tools und bietet Referenzdokumente für Syntax, Layout-Engines und Diagrammmuster.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

In Ihrer bevorzugten KI fragen

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

Dokumentation

D2-Diagramme

Schreibe D2-Quellcode, rendere ihn in SVG, schau dir dann das Rendering an und korrigiere, was du siehst – in einer Schleife, bis das Diagramm versandfertig ist. Ein Diagramm, das du nicht gesehen hast, ist ein Diagramm, das du nicht fertiggestellt hast.

Referenzdateien – bei Bedarf laden

DateiWann lesen
references/d2-language.mdBeim Schreiben eines nicht-trivialen D2 – Syntax, Shapes, Container, Klassen, Variablen und die stillen Fallstricke, die fehlerfrei kompilieren, aber falsch rendern
references/layout-engines.mdBei der Auswahl oder Fehlersuche des Layouts: TALA vs. ELK vs. dagre, Lizenzierung, Seeds, enginespezifische Verhaltensunterschiede
references/diagram-patterns.mdBei der Auswahl eines Diagrammtyps und seiner Struktur – Architektur, Sequenz, ERD, Grid, C4; Themes, Icons, Dark Mode, GitHub-Einbettung

Schritt 0 – Toolchain-Prüfung

Einmal pro Sitzung vor dem ersten Rendern ausführen (scripts/ bezieht sich hier auf das eigene Verzeichnis dieser Fertigkeit – in Claude Code wird ${CLAUDE_SKILL_DIR} darauf aufgelöst):

bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
  • d2: ok → fortfahren.
  • d2: MISSING → den Benutzer informieren, dann scripts/setup.sh (ohne Flags) ausführen, um via Homebrew zu installieren, wo verfügbar, oder die angezeigten Installationsbefehle anzuzeigen. Nicht blind rendern – nichts anderes in dieser Fertigkeit funktioniert ohne d2.
  • tala: not installed oder unlicensed → in Ordnung. ELK ist der automatische Fallback und erzeugt gute Layouts. TALA nur einmal erwähnen, wenn das Diagramm ein Software-Architekturdiagramm ist (wo TALA deutlich besser ist) und der Benutzer sich für die Ausgabequalität zu interessieren scheint; niemals nörgeln.

Schritt 1 – Planen vor dem Schreiben

Zuerst drei Dinge entscheiden:

  1. Die Botschaft. Was soll ein Leser in fünf Sekunden erkennen? Ein Diagramm argumentiert etwas – „Anfragen verteilen sich hier", „dieser Dienst ist der Engpass", „diese beiden Pfade berühren sich nie". Wenn du das Argument nicht formulieren kannst, wirst du gleich eine Sammlung beschrifteter Kästen zeichnen.
  2. Der Typ. Architektur/Topologie → einfache Shapes und Container. Interaktion über Zeit → sequence_diagram. Datenmodell → sql_table. Strenge Ausrichtung (Matrix, Dashboard, legendenlastig) → Grid. Siehe references/diagram-patterns.md für Strukturhinweise pro Typ.
  3. Der Maßstab. 5–15 Knoten lesen sich gut; 15–25 benötigen Container zur Gruppierung; jenseits von ~25 in mehrere Diagramme aufteilen oder layers verwenden. Ein zweites Diagramm ist einer Wandmalerei vorzuziehen.

Verwende bei technischen Diagrammen realer Systeme echte Namen – tatsächliche Dienstnamen, tatsächliche Tabellennamen, tatsächliche Ereignisnamen aus der Codebasis oder Beschreibung des Benutzers. Durchsuche den Code, wenn verfügbar. Service A -> Service B verschwendet das Vertrauen des Lesers.

Schritt 2 – D2 schreiben

Lies references/d2-language.md, bevor du etwas über ein triviales Diagramm hinaus schreibst. Die Regeln, die 90% defekter Ausgaben verhindern:

  • Keys verbinden, nicht Labels. Nach api: API Gateway schreibe api -> db, niemals API Gateway -> db – Letzteres erzeugt still einen doppelten Shape.
  • Labels mit # oder ; in Anführungszeichen setzen – nicht in Anführungszeichen gesetztes # startet einen Kommentar mitten im Label und nicht in Anführungszeichen gesetztes ; teilt die Zeile in zwei Shapes, beide kompilieren fehlerfrei. Jedes Label mit Satzzeichen in Anführungszeichen zu setzen, ist die sichere Gewohnheit.
  • Stil über classes:, nicht knotenweise Stile – eine Definition, angewendet mit class:. Vermeide style.fill auf einzelnen Knoten; hartcodierte Füllungen kämpfen mit dem Theme und brechen das Dark-Mode-Rendering.
  • direction: right setzen für die meisten Architekturflüsse (von links nach rechts liest sich natürlich). Alle Engines beachten die root-level-Richtung; TALA unterstützt zusätzlich die per-Container direction.
  • Speichere die Quelle als {name}.d2 neben dem Ort, an den die Ausgabe gehört (Standard: ./diagrams/ im Projekt).

Schritt 3 – Rendern

Immer über das gebündelte Skript rendern – es wählt die Layout-Engine, schützt vor Wasserzeichen und validiert zuerst:

bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
  • --png schreibt auch output.png – benötigt für Schritt 4 (das Lese-Tool zeigt Rasterbilder an, kein SVG).
  • Das Skript gibt engine: (was tatsächlich gerendert hat) und fallback: (warum, wenn TALA nicht verwendet wurde) aus. Gib dem Benutzer nur dann eine einzeilige Notiz, wenn er nach Engines gefragt oder explizit TALA gewünscht hat.
  • Nützliche Flags: --theme N, --dark-theme 200 (SVG reagiert auf das Farbschema des Lesers), --sketch, --pad N, --seed N (TALA-Neuberechnung), --engine tala|elk|dagre (erzwingen), --allow-watermark (TALA-Auswertung).
  • Bei Fehlern gibt das Skript den d2-Kompilierungsfehler mit datei:zeile:spalte aus – behebe die Quelle an dieser Stelle und führe erneut aus. Wenn der Fehler unklar ist, überprüfe den Abschnitt „Fallstricke" in references/d2-language.md.

Rendere niemals TALA-Ausgabe zur Auslieferung mit einem Wasserzeichen, es sei denn, der Benutzer akzeptiert dies ausdrücklich; das Skript erzwingt dies durch Fallback auf ELK.

Schritt 4 – Anschauen, dann korrigieren (nicht optional)

Die .d2-Quelle sagt nichts darüber aus, wie das Rendering tatsächlich angekommen ist – Layout ist die Entscheidung der Engine, nicht deine. Öffne das PNG mit dem Lese-Tool und überprüfe es in zwei Durchgängen:

Durchgang 1 – Vermittelt es die Botschaft?

  • Tritt das Auge dort ein, wo die Geschichte beginnt, und tritt es dort aus, wo sie endet?
  • Ist die Flussrichtung konsistent (nicht unbeabsichtigt zurücklaufend oder von unten nach oben lesend)?
  • Entsprechen die Containergruppierungen den geplanten logischen Gruppierungen?
  • Ist das wichtigste Element visuell hervorgehoben oder vergraben?

Durchgang 2 – Layout-Mängel (Auto-Layout-Engines erzeugen alle diese):

  • Kantenbeschriftungen weit von ihrer Kante abgedriftet oder mehrdeutig, zu welcher Kante sie gehören
  • Kanten überlappen sich in parallelen Läufen, kreuzen Knoten oder Container oder nehmen absurde Umwege
  • Text abgeschnitten oder kollidierend mit Shapes/Icons
  • Eine Region überfüllt, während eine andere leer ist; ein Container erheblich größer als sein Inhalt
  • Knoten so klein, dass sein Label dominiert, oder stark inkonsistente Knotengrößen
  • Alles, was du entschuldigend erklären müsstest, wenn du es dem Benutzer zeigen würdest

Behebe mit D2s Hebeln, nicht mit Pixel-Justierung (Auto-Layout bedeutet, du änderst Eingaben, nicht Koordinaten): ändere direction; gruppiere oder gruppiere mit Containern um; kürze Kantenbeschriftungen (lange Beschriftungen driften bei ELK am stärksten ab); führe parallele Kanten zu einer beschrifteten Kante zusammen; verschiebe Legenden/Titel aus dem Fluss mit near; teile ein überladenes Diagramm in layers auf; passe --pad an; bei TALA mit --seed N neu berechnen (probiere 2–3 Seeds – Layouts variieren erheblich); als letztes Mittel wechsle die Engine für diese Diagrammform (siehe references/layout-engines.md).

Erneut rendern, erneut ansehen, wiederholen. Plane zwei bis vier Renderzyklen ein – ein erstes Rendering, das beide Durchgänge besteht, ist selten. Fertig bedeutet: beide Durchgänge sauber, und nichts im Bild benötigt eine Entschuldigung oder eine Erklärung.

Schritt 5 – Ausliefern

  • Bestätige die endgültigen .svg- (und .d2-Quell-)Pfade – gib dem Benutzer immer beide; die .d2 ist das bearbeitbare Artefakt.
  • Wenn das Diagramm in einem GitHub-README oder einer Dokumentationsseite leben wird, biete eine Dark-Mode-fähige Variante an: erneut rendern mit --dark-theme 200 (einzelnes SVG, das dem Farbschema des Lesers folgt). Muster für PNG/<picture>-Einbettung findest du in references/diagram-patterns.md.
  • Wenn der Benutzer selbst am Diagramm iterieren wird, erwähne d2 --watch input.d2 für eine Live-Vorschau im Browser.

Fehlerbehebung

SymptomUrsache / Behebung
d2: command not foundFühre scripts/setup.sh aus (geführte Installation)
D2_LAYOUT "tala" is not bundledTALA nicht im PATH – Skript fällt automatisch auf ELK zurück; installiere TALA nur, wenn der Benutzer es möchte
UNLICENSED-Text in der AusgabeTALA ohne Lizenz – das Render-Skript rendert automatisch mit ELK erneut; ein Lizenzschlüssel kommt in TSTRUCT_TOKEN oder ~/.config/tstruct/auth.json
PNG-Export fehlschlägt, SVG funktioniertDer erste PNG-Render lädt einen Headless-Browser herunter; einmal wiederholen. Wenn blockiert (offline/CI), liefere SVG und überprüfe es durch Konvertierung mit einem verfügbaren SVG-Rasterisierer
Kompilierungsfehler unter --layout tala, den ELK fehlerfrei rendertd2/TALA-Versionskonflikt – Skript fällt automatisch zurück; schlage vor, beide zu aktualisieren
Icons fehlen in der AusgabeIcon-URL gab 403/404 zurück – entferne das Icon oder wähle ein anderes von icons.terrastruct.com; teste Icons frühzeitig

Verwandte Skills