json-canvas

## Überblick über den json-canvas Skill

### Was der json-canvas Skill leistet
Der `json-canvas` Skill hilft einem AI-Agenten dabei, `.canvas`-Dateien zu erstellen und zu bearbeiten, die der JSON Canvas 1.0-Struktur folgen, wie sie in visuellen Boards im Obsidian-Stil verwendet wird. Sein eigentlicher Nutzen liegt nicht im „Diagrammerstellen allgemein“, sondern darin, gültiges `nodes`- und `edges`-JSON mit den richtigen IDs, Koordinaten und Referenzen zu erzeugen, damit sich die Datei sauber öffnen lässt, statt auf subtile Weise kaputtzugehen.

### Für wen sich json-canvas lohnt
Dieser `json-canvas skill` passt am besten zu Nutzerinnen und Nutzern, die schon wissen, welches Ergebnis sie wollen — etwa eine Mindmap, ein Flowchart, ein Projektboard, eine Concept Map oder ein Notiz-Canvas — aber das Schema nicht von Hand schreiben möchten. Besonders sinnvoll ist er, wenn du in Obsidian arbeitest, `.canvas`-Dateien in einem Repo verwaltest oder reproduzierbare, AI-gestützte Änderungen an bestehenden Canvases möchtest statt einmaliger visueller Vorschläge.

### Warum er besser ist als ein generischer Prompt
Ein normaler Prompt kann Boxen und Pfeile beschreiben, lässt aber oft Formatdetails aus, auf die es ankommt: eindeutige 16-stellige Hex-IDs, gültige `fromNode`- und `toNode`-Referenzen, nicht überlappende Platzierung und den Unterschied zwischen Textknoten und Gruppenknoten. Der `json-canvas` Skill gibt dem Agenten ein konkretes Zielformat und Beispiele vor, wodurch nach der Generierung deutlich weniger Nacharbeit nötig ist.

### Was du vor der Einführung wissen solltest
Dieser Skill ist bewusst eng zugeschnitten. Er unterstützt bei der Struktur von `.canvas`-Dateien und bei typischen Bearbeitungs-Workflows; er ersetzt jedoch weder eine vollwertige visuelle Layout-Engine noch ein semantisches Diagrammtool oder einen automatischen Design-Optimizer. Wenn du vor allem auf ausgefeiltes Styling oder den Export in viele Diagrammformate angewiesen bist, kann sich `json-canvas for Diagramming` zu niedrigschwellig beziehungsweise zu nah am Format anfühlen. Wenn du dagegen schnell valides Canvas-JSON brauchst, ist er eine gute Wahl.

## So verwendest du den json-canvas Skill

### Installationskontext und womit du zuerst anfangen solltest
Um `json-canvas install` in einer Umgebung mit Skills zu nutzen, füge den Skill aus dem Repository `kepano/obsidian-skills` hinzu und lies zuerst `skills/json-canvas/SKILL.md`, danach `skills/json-canvas/references/EXAMPLES.md`. Diese beiden Dateien sind der praktische Kern: Die erste erklärt die erforderliche Struktur und die Workflows, die zweite zeigt vollständige Beispiele, an denen du dich konkret orientieren kannst.

### Welche Eingaben der Skill für gute Ergebnisse braucht
Die Qualität bei der `json-canvas usage` hängt stark davon ab, wie konkret deine Anfrage ist. Gib nach Möglichkeit Folgendes an:
- den Ziel-Dateipfad oder den bestehenden `.canvas`-Inhalt
- ob du ein neues Canvas erstellen oder ein vorhandenes bearbeiten willst
- welche Knotentypen du brauchst, etwa `text` oder `group`
- die grobe Layout-Absicht, zum Beispiel einen Fluss von links nach rechts oder Kanban-Spalten
- die gewünschten Verbindungen zwischen den Knoten
- Vorgaben zu Größe oder Abständen

Eine schwache Anfrage wäre: „make a project canvas.“ Eine deutlich bessere ist: „Create a new `.canvas` with three group columns labeled To Do, In Progress, Done, each 300x500, spaced 50px apart, and add three text task nodes inside the first two groups.“

### So machst du aus einem groben Ziel einen starken Prompt für json-canvas
Für eine gute `json-canvas guide`-Qualität solltest du sowohl Generierung als auch Validierung anfordern. Ein starker Prompt folgt meist diesem Muster:

1. Formuliere das Ziel in einfachem Englisch.
2. Gib an, ob etwas neu erstellt oder geändert werden soll.
3. Definiere die Knotenstruktur und die Beziehungen.
4. Bitte den Agenten, JSON und Edge-Referenzen vor der finalen Ausgabe zu validieren.

Beispiel:
“Use the `json-canvas` skill to create a new `.canvas` file for a product launch plan. Add one central text node, four supporting text nodes around it, connect each support node to the center, keep 100px spacing to avoid overlap, generate unique 16-character hex IDs, and return valid JSON only.”

### Praktische Workflow-Tipps, die beim json-canvas Einsatz Zeit sparen
Für eine bessere `json-canvas usage` gilt: erst einfach anfangen, dann schrittweise erweitern:
- Bitte zuerst um ein strukturell valides minimales Canvas.
- Öffne es oder prüfe es.
- Fordere dann jeweils nur eine Änderung pro Schritt an: Knoten hinzufügen, neu gruppieren, neu verbinden oder neu positionieren.

Wenn du eine bestehende Datei bearbeitest, sage dem Agenten ausdrücklich, dass er die vorhandenen IDs zuerst parsen soll, bevor er etwas ergänzt. Die häufigsten Fehler entstehen durch ID-Kollisionen und Edges, die auf fehlende Knoten zeigen. Wenn das Layout wichtig ist, formuliere Abstandsregeln explizit; sonst kann das JSON zwar valide sein, aber visuell unordentlich wirken.

## FAQ zum json-canvas Skill

### Ist json-canvas auch für Einsteiger geeignet?
Ja, sofern du schon weißt, was dein Canvas enthalten soll. Der Skill nimmt dir den Großteil des Schema-Ratens ab, sodass auch Einsteiger gültige `.canvas`-Dateien erzeugen können, ohne die Spezifikation auswendig zu kennen. Weniger geeignet ist er, wenn du die Logik des Diagramms selbst noch nicht festgelegt hast; der Skill hilft dabei, Struktur zu codieren, nicht dabei, das gesamte Informationsdesign für dich zu erfinden.

### Wann sollte ich json-canvas statt eines normalen AI-Prompts verwenden?
Nutze `json-canvas`, wenn das Ergebnis eine funktionierende `.canvas`-Datei sein muss — besonders dann, wenn du ein bestehendes Canvas bearbeitest. Ein generischer Prompt kann beim Strukturieren oder Brainstorming helfen, aber dieser Skill ist die bessere Wahl, wenn Korrektheit zählt: eindeutige IDs, gültige Arrays, echte Knotenreferenzen und Obsidian-kompatible Formatierung.

### Deckt json-canvas alle Diagramm-Anforderungen ab?
Nein. `json-canvas for Diagramming` eignet sich am besten für Node-Edge-Canvases, einfache Boards und visuelle Organisation rund um verknüpfte Notizen. Es ist kein Ersatz für BPMN-Tools, hochwertige Präsentationsgrafiken oder fortgeschrittene Auto-Layout-Systeme. Wenn du breite Diagrammstandards oder umfangreiche Styling-Kontrollen brauchst, solltest du ein anderes Tool verwenden und nur bei Bedarf konvertieren.

### Wo liegen die wichtigsten Grenzen und ungeeigneten Einsatzfälle?
Lass diesen Skill aus, wenn dein Zielformat keine `.canvas`-Datei ist, wenn du starke automatische Layout-Optimierung brauchst oder wenn die maßgebliche Quelle in einem anderen Format bleiben soll, etwa Mermaid, Excalidraw oder einer Tabellenkalkulation. Vermeide außerdem vage Prompts wie „make it look nice“; der Skill liefert die besten Ergebnisse bei expliziter Struktur und klarer Platzierungsabsicht.

## So verbesserst du den json-canvas Skill

### Gib dem json-canvas Skill stärkere strukturelle Vorgaben
Die größte Qualitätssteigerung erreichst du, wenn du die Struktur von Anfang an besser vorgibst. Benenne die Knoten, die du brauchst, die Verbindungen zwischen ihnen und das gewünschte räumliche Muster. Formulierungen wie „hub-and-spoke“, „three-column board“ oder „timeline from left to right“ geben dem Agenten genug Kontext, um Knoten sinnvoll zu platzieren, statt nur zu raten.

### Vermeide die typischen Fehlerquellen
Die meisten `json-canvas`-Probleme sind mechanischer Natur:
- doppelte IDs
- Edges, die auf nicht vorhandene Knoten zeigen
- überlappende Koordinaten
- fehlende Pflichtfelder wie `type`, `x`, `y`, `width`, `height`

Bitte den Agenten, vor der Rückgabe der Datei alle IDs und Referenzen zu validieren. Wenn du ein Canvas änderst, weise ihn an, vorhandene IDs beizubehalten, außer eine Änderung erfordert tatsächlich einen neuen Knoten oder eine neue Edge.

### Iteriere nach der ersten Ausgabe
Betrachte das erste Ergebnis als Gerüst. Verbessere danach jeweils nur eine Ebene:
- Abstände und Ausrichtung anpassen
- Gruppen hinzufügen
- Labels und Textinhalte verfeinern
- Verbindungen hinzufügen oder entfernen

Das funktioniert besser, als in einem einzigen Schritt ein dichtes finales Canvas anzufordern, weil sich Fehler in der visuellen Struktur früh viel leichter erkennen lassen als nach einer großen Generierung.

### Nutze Beispiele und Repository-Muster gezielt
Um die Ergebnisse mit dem `json-canvas skill` zu verbessern, übernimm Muster aus `references/EXAMPLES.md`, statt alles nur abstrakt zu beschreiben. Wenn dein gewünschtes Ergebnis einem Projektboard ähnelt, bitte den Agenten, dem gruppenbasierten Muster zu folgen. Wenn es eher einer Concept Map entspricht, fordere das einfache Muster mit verbundenen Textknoten an. Die Wiederverwendung repository-naher Muster führt meist zu saubererem JSON und zu weniger Kompatibilitätsüberraschungen.