yctimlin/excalidraw-skill

Was macht excalidraw-skill?

Schritt 0: Wählen Sie eine Schnittstelle

Drei Schnittstellen steuern dieselbe Live-Canvas. Wählen Sie die erste, die zutrifft:

1. MCP-Tools — Wenn excalidraw/*-Tools (z. B. batch_create_elements) in Ihrer Werkzeugliste sind, bevorzugen Sie sie: Ergebnisse landen direkt in Ihrem Kontext, und Screenshots werden als Bilder zurückgegeben, ohne die Festplatte zu berühren.
2. CLI (Standard, wenn keine MCP-Tools vorhanden sind):

   npx -y mcp-excalidraw-server <Befehl>
   

   Keine Einrichtung erforderlich — jeder Canvas-berührende Befehl startet den Canvas-Server automatisch auf http://127.0.0.1:3000 (der erste npx-Lauf lädt das Paket herunter). Wenn die CLI global installiert ist (npm i -g mcp-excalidraw-server), funktioniert auch der kürzere Alias excalidraw-canvas <Befehl>.
3. REST-API (letzter Ausweg, z. B. aus Anwendungscode): HTTP-Endpunkte auf http://127.0.0.1:3000 — siehe references/cheatsheet.md für Nutzdaten. Der Server muss bereits laufen.

Die Canvas-URL stammt aus EXPRESS_SERVER_URL (Standard http://127.0.0.1:3000). Erinnern Sie den Benutzer daran, diese URL in einem Browser zu öffnen — Screenshots, Bildexport, Mermaid-Konvertierung und Viewport-Steuerung benötigen einen offenen Tab (die CLI beendet sich mit Exit-Code 4, wenn dieser fehlt).

CLI-Kurzreferenz

Ergebnisse sind JSON auf stdout — außer describe (Klartext) und Rohinhaltsausgabe, wenn --out weggelassen wird (export-Szenen-JSON, screenshot --format svg). Diagnose auf stderr. Exit-Codes: 0 ok, 1 Fehler, 2 Nutzung, 3 Canvas nicht erreichbar, 4 Browser-Tab erforderlich.

Aufgabe	Befehl
Server starten / stoppen / prüfen	start, stop, status
Elemente (Batch) erstellen	add elements.json oder echo '[...]' | add oder add --one '{...}'
Multi-Op-Patch in einem Aufruf	apply patch.json — {"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}
Eines lesen / mehrere abfragen	get <id>, query [--type t] [--bbox x0,y0,x1,y1] [--filter k=v] [--filter-json '{...}']
Aktualisieren / Löschen	update <id> --set '{...}', delete <id> [...]
Szene verstehen	describe (Klartext-Zusammenfassung: IDs, Positionen, Labels, Verbindungen)
Szene sehen	screenshot [--out f.png] (PNG ohne --out → temporärer Dateipfad in JSON; SVG ohne --out → rohes SVG)
Layout-Operationen	arrange align|distribute|group|ungroup|lock|unlock|duplicate --ids a,b,c [--to left|horizontal|...]
Szenen-Dateien	export [--out szene.excalidraw], `import [szene.excalidraw
Mermaid → Canvas	mermaid [diagramm.mmd|-] (oder stdin)
Snapshots	snapshot save|list|restore <name>
Link teilen	share (verschlüsselter Upload → excalidraw.com-URL)
Canvas leeren	clear --yes
Dieses Skill installieren / aktualisieren	install-skill --dir <skills-root> (Agent wählt Projekt-/globales Wurzelverzeichnis)

Elementformat (CLI und MCP)

Die CLI und die MCP-Tools akzeptieren dasselbe agentenfreundliche Format und normalisieren es automatisch:

• Labels: Setzen Sie "text": "Mein Label" auf jede Form — wird für Sie in das Excalidraw-Bound-Label-Format konvertiert.
• Pfeilbindung: "startElementId": "a" / "endElementId": "b" — Pfeile werden automatisch zu Elementkanten geroutet.
• fontFamily: Übergeben Sie einen Zeichenfolgennamen ("helvetica", "cascadia", "excalifont", ...) oder eine Zeichenfolgennummer "1"–"8".
• points: Sowohl [[x,y], ...]-Tupel als auch [{"x":..,"y":..}]-Objekte werden akzeptiert.
• Patch-Updates: In apply können Update-Einträge entweder direkte Felder ({"id":"a","x":120}) oder ein set-Objekt ({"id":"a","set":{"x":120}}) verwenden. Mischen Sie beide Formen nicht in einem Update-Eintrag.

Rohe REST ist strenger: Labels müssen "label": {"text": "..."} sein, Bindungen müssen "start": {"id": "..."} / "end": {"id": "..."} sein. Machen Sie sich nur darum Sorgen, wenn Sie direkt per POST an die API senden.

---

Koordinatensystem

Die Canvas verwendet ein 2D-Koordinatengitter: (0, 0) ist der Ursprung, x nimmt nach rechts zu, y nimmt nach unten zu. Planen Sie Ihr Layout, bevor Sie JSON schreiben.

Allgemeine Abstandsrichtlinien:

• Vertikaler Abstand zwischen Ebenen: 80–120px (genug, damit Pfeile Labels nicht überladen)
• Horizontaler Abstand zwischen Geschwistern: mindestens 40–60px; geben Sie beschrifteten Pfeilen 120px+
• Formbreite: max(160, labelZeichenAnzahl * 12), um das Label in einer Zeile zu halten
• Formhöhe: 60px einzeilig, 80px zweizeilige Labels
• Hintergrund-/Zonenabstand: 50px auf allen Seiten um enthaltene Elemente

Styling für ein professionelles Aussehen:

• "fillStyle": "solid" auf Formen ergibt klare, flache Füllungen — die Standardeinstellung ist ein skizzenhaftes Schraffurmuster
• Kombinieren Sie pastellfarbene backgroundColor-Füllungen mit ihren dunkleren strokeColor (Palette im Spickzettel)
• "strokeStyle": "dashed" auf Zonengrenzen und asynchronen Pfeilen liest sich wie "Grenze / Hintergrund"

---

Layout-Anti-Patterns (Kritisch für komplexe Diagramme)

Dies sind die häufigsten Fehler, die unlesbare Diagramme produzieren. Vermeiden Sie alle.

1. Verwenden Sie NICHT label.text (oder text) auf großen Hintergrundzonen-Rechtecken

Wenn Sie ein Label auf ein Hintergrundrechteck setzen, erstellt Excalidraw ein gebundenes Textelement, das in der Mitte dieser Form zentriert ist — genau dort, wo Ihre Service-Boxen platziert werden. Der Text überlappt alles innerhalb der Zone und kann nicht neu positioniert werden.

Falsch:

{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "text": "VPC (10.0.0.0/16)"}

Richtig — verwenden Sie ein freistehendes Textelement, das oben in der Zone verankert ist:

{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "backgroundColor": "#e3f2fd"},
{"id": "vpc-label", "type": "text", "x": 70, "y": 60, "width": 300, "height": 30, "text": "VPC (10.0.0.0/16)", "fontSize": 18}

Das freistehende Textelement sitzt in der oberen Ecke der Zone und stört nicht mit darin platzierten Elementen.

2. Vermeiden Sie Zonenübergreifende Pfeile in komplexen Diagrammen

Ein Pfeil von einem Element in einer Layoutzone zu einem Element in einer entfernten Zone zeichnet eine lange diagonale Linie, die alles dazwischen durchquert. In einem mehrzonigen Infrastrukturdiagramm ergibt dies ein unlesbares Spaghettigewirr.

Entwurfsregel: Halten Sie Pfeile innerhalb derselben Zone oder Ebene. Um zonenübergreifende Beziehungen darzustellen, verwenden Sie Anmerkungstexte oder trennen Sie die Zonen so, dass ihre Kanten benachbart sind (keine Elemente dazwischen), und leiten Sie den Pfeil entlang der Kante.

Wenn Sie unbedingt über Zonen hinweg verbinden müssen, verwenden Sie einen abgewinkelten Pfeil, der entlang des Umfangs verläuft — niemals durch die Mitte einer anderen Zone.

3. Verwenden Sie Pfeillabel sparsam

Pfeillabel werden am Mittelpunkt des Pfeils platziert. Auf kurzen Pfeilen überlappen sie die Formen an beiden Enden. In überfüllten Diagrammen kollidieren sie mit benachbarten Elementen.

• Fügen Sie ein Pfeillabel nur hinzu, wenn der Beziehungsname wirklich wesentlich ist (z. B. Protokoll, Portnummer, Datenrichtung).
• Wenn Sie jedem Pfeil ein Label hinzufügen, überlegen Sie es noch einmal — es fügt normalerweise visuelles Rauschen hinzu, nicht Klarheit.
• Halten Sie Pfeillabel auf ≤ 12 Zeichen. Lassen Sie sie in dichten Diagrammen ganz weg.

---

Qualität: Warum sie wichtig ist (und wie man sie überprüft)

Excalidraw-Diagramme sind visuelle Kommunikation. Wenn Text abgeschnitten ist, Elemente sich überlappen oder Pfeile durch nicht zusammenhängende Formen kreuzen, wird das Diagramm verwirrend und unprofessionell — es vereitelt den ganzen Zweck des Zeichnens. Überprüfen Sie daher nach jedem Batch, bevor Sie weitere hinzufügen.

Qualitäts-Checkliste

Nach jedem add / apply / batch_create_elements machen Sie einen Screenshot und prüfen Sie:

1. Textabschneidung — Ist der gesamte Labeltext vollständig sichtbar? Abgeschnittener Text bedeutet, dass die Form zu klein ist. Erhöhen Sie width und/oder height.
2. Überlappung — Teilen sich Formen denselben Raum? Hintergrundzonen müssen Kinder mit Abstand vollständig enthalten.
3. Pfeilkreuzung — Kreuzen Pfeile durch nicht zusammenhängende Elemente? Wenn ja, leiten Sie sie mit Kurven- oder Ellenbogenpfeilen herum (siehe Pfeilführung unten).
4. Pfeil-Label-Überlappung — Pfeillabel sitzen am Mittelpunkt. Wenn sie eine Form überlappen, kürzen Sie das Label oder passen Sie den Pfeilpfad an.
5. Abstand — Mindestens 40px Lücke zwischen Elementen. Gedrängte Layouts sind schwer lesbar.
6. Lesbarkeit — Schriftgröße ≥ 16 für Fließtext, ≥ 20 für Titel.
7. Zonenlabel-Platzierung — Wenn Sie text/label.text auf einem Hintergrundzonenrechteck verwendet haben, wird das Zonenlabel in der Mitte der Zone zentriert und überlappt alles darin. Behebung: Löschen Sie das gebundene Textelement und fügen Sie stattdessen ein freistehendes Textelement oben in der Zone hinzu (siehe Layout-Anti-Patterns oben).

Wenn Sie ein Problem finden: Stoppen Sie, beheben Sie es, machen Sie einen neuen Screenshot, dann machen Sie weiter. Sagen Sie "Ich sehe [Problem], behebe es", anstatt Probleme zu übergehen. Fahren Sie erst fort, wenn alle Prüfungen bestanden sind.

---

Arbeitsablauf: Zeichnen eines neuen Diagramms

Mermaid vs. Direkterstellung — Welche verwenden?

Verwenden Sie mermaid / create_from_mermaid wenn: Der Benutzer bereits ein Mermaid-Diagramm hat oder die Struktur sauber auf ein Flussdiagramm/Sequenz-/ER-Diagramm mit Standard-Mermaid-Syntax abbildet. Es ist schnell und erledigt die Konvertierung automatisch, bietet aber weniger Kontrolle über das genaue Layout.

Erstellen Sie Elemente direkt wenn: Sie präzise Layout-Kontrolle benötigen, der Diagrammtyp nicht gut auf Mermaid abbildet (z. B. benutzerdefinierte Architektur, kommentierte Cloud-Diagramme) oder Sie Elemente in einem bestimmten Koordinatengitter positionieren möchten.

Schritte (CLI gezeigt; MCP-Tools sind 1:1 — siehe Spickzettel)

1. Planen Sie Ihr Koordinatengitter — skizzieren Sie Ebenen und x-Positionen, bevor Sie JSON schreiben. (MCP-Modus: Rufen Sie read_diagram_guide für Farben/Größen auf; dieselbe Anleitung finden Sie in references/cheatsheet.md.)
2. Optionaler Neustart: npx -y mcp-excalidraw-server clear --yes
3. Erstellen Sie Formen und Pfeile in einem Aufruf. Benutzerdefinierte id-Felder (z. B. "id": "auth-svc") erleichtern spätere Aktualisierungen:

   npx -y mcp-excalidraw-server add - <<'EOF'
   [
     {"id": "lb", "type": "rectangle", "x": 300, "y": 50, "width": 180, "height": 60, "text": "Load Balancer"},
     {"id": "svc-a", "type": "rectangle", "x": 100, "y": 200, "width": 160, "height": 60, "text": "Web Server 1"},
     {"id": "svc-b", "type": "rectangle", "x": 450, "y": 200, "width": 160, "height": 60, "text": "Web Server 2"},
     {"id": "db", "type": "rectangle", "x": 275, "y": 350, "width": 210, "height": 60, "text": "PostgreSQL"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-a"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-b"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "db"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-b", "endElementId": "db"}
   ]
   EOF
   

   (Das --Positionsargument ist optional — ohne Dateiargument liest add von stdin.)
4. Setzen Sie Formbreiten mit max(160, labelLength * 12).
5. screenshot → Datei ansehen → Qualitäts-Checkliste durchlaufen → Probleme beheben, bevor Sie den nächsten Batch hinzufügen.

---

Pfeilführung — Überlappungen vermeiden

Gerade Pfeile können in komplexen Diagrammen durch Elemente kreuzen. Verwenden Sie bei Bedarf Kurven- oder Ellenbogenpfeile:

Kurvenpfeile (glatter Bogen über Hindernisse):

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2}
}

Der Zwischenwegpunkt [50, -40] hebt den Pfeil nach oben. roundness: {type: 2} macht ihn glatt.

Ellenbogenpfeile (rechtwinklige / L-förmige Führung):

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

Wann welches verwenden:

• Fan-out (eine Quelle → viele Ziele): Kurvenpfeile mit Wegpunkten, die überlappend verteilt werden
• Quer zwischen Bahnen (Verbindung zu Seitenfeldern): Ellenbogenpfeile, die nach oben, dann quer, dann nach unten gehen
• Lange horizontale Verbindungen: Kurvenpfeile mit leichtem vertikalem Versatz

Regel: Wenn ein Pfeil durch eine nicht zusammenhängende Form verlaufen würde, fügen Sie einen Wegpunkt hinzu, um sie herumzuleiten.

---

Arbeitsablauf: Iterative Verfeinerung

Die Kombination von describe mit screenshot macht dieses Skill leistungsstark.

• describe (describe_scene in MCP) → strukturierter Text: Element-IDs, Typen, Positionen, Labels, Verbindungen. Verwenden Sie es, um zu wissen, was auf der Canvas ist, bevor Sie programmatische Aktualisierungen vornehmen (IDs finden, Begrenzungsrahmen verstehen).
• screenshot (get_canvas_screenshot in MCP) → PNG der tatsächlich gerenderten Canvas. Verwenden Sie es für visuelle Qualitätsprüfung — es zeigt genau, was der Benutzer sieht, einschließlich Textabschneidung, Überlappung und Pfeilführung. Die CLI gibt den gespeicherten Dateipfad als JSON aus; lesen/sehen Sie diese Datei.

Rückkopplungsschleife:

elemente hinzufügen
  → screenshot → ansehen → "text auf auth-svc abgeschnitten"
  → update auth-svc --set '{"width": 220}' → screenshot → "überlappung zwischen auth-svc und rate-limiter"
  → update rate-limiter --set '{"x": 520}' → screenshot → "alle prüfungen bestanden"
  → fortfahren

Arbeitsablauf: Ein vorhandenes Diagramm verfeinern

1. describe, um den aktuellen Zustand zu verstehen — notieren Sie Element-IDs und Positionen.
2. Identifizieren Sie Elemente anhand von id oder Labeltext (nicht anhand von x/y-Koordinaten — diese ändern sich).
3. update <id> --set '{...}', um die Größe/Farbe/Position zu ändern; delete <id>, um zu entfernen; oder bündeln Sie alles in einem apply-Patch. Gebundene Pfeile werden automatisch neu geroutet, wenn Sie ihre Endpunkte verschieben oder in der Größe ändern — Sie müssen sie nicht löschen und neu erstellen.
4. screenshot, um zu bestätigen, dass die Änderung richtig aussieht.
5. Wenn Aktualisierungen fehlschlagen: Überprüfen Sie, ob die ID mit get <id> existiert; entsperren Sie mit arrange unlock --ids <id>, wenn gesperrt.

Arbeitsablauf: Mermaid-Konvertierung

echo 'graph TD
  A[Client] --> B[API]
  B --> C[(DB)]' | npx -y mcp-excalidraw-server mermaid

Erfordert einen offenen Browser-Tab (Konvertierung läuft im Frontend; Exit-Code 4 teilt Ihnen mit, die Canvas-URL zu öffnen). Danach screenshot, um das Layout zu überprüfen. Wenn das automatische Layout schlecht ist (Knoten gedrängt, Kanten kreuzen sich), finden Sie Problem-Elemente mit describe und positionieren Sie sie mit update neu.

Arbeitsablauf: Datei-I/O

• Szene exportieren: export --out diagramm.excalidraw (kein --out → JSON auf stdout)
• Szene importieren: import diagramm.excalidraw (anhängen) oder import diagramm.excalidraw --replace
• Bild: screenshot --out diagramm.png / screenshot --format svg --out diagramm.svg (Browser-Tab erforderlich)
• Link teilen: share — verschlüsselt die Szene und gibt einen teilbaren exc

…

[gekürzt für die Übersetzung]