Communitygithub.com

CoderMoray/SkillFlowChart

KI-generierte semantische Struktur plus deterministisches Scripting für Entscheidungsflussdiagramme als HTML.

Was ist SkillFlowChart?

Dieses Skill wandelt eine beliebige `SKILL.md` in ein Entscheidungsflussdiagramm (HTML) um, indem es die Arbeit zwischen KI und einem deterministischen Script aufteilt. Die KI extrahiert aus dem natürlichen Sprachtext der `SKILL.md` semantisch korrekte strukturierte Daten (`nodes.json`), während ein Python-Script ausschließlich die geometrische Berechnung der Positionen und die SVG-Rendering übernimmt. Dadurch wird garantiert, dass die Layouts reproduzierbar und pixelgenau sind, ohne dass die KI über Koordinaten oder SVG entscheiden muss. Es unterstützt alle gängigen Plattformen, die mit SKILL.md-Dateien arbeiten, und legt großen Wert auf saubere Trennung von Semantik (KI-seitig) und Geometrie (Script-seitig). Zu den Besonderheiten gehören explizite Seitenangaben (`side`) für Kanten, was die KI vollständig verantwortet, sowie die Unterstützung von Entscheidungsdiamanten, regulären Prozessschritten, Rückkopplungsschleifen (als gestrichelte Linien) und automatischer Legenden-Generierung. Das Ergebnis ist eine eigenständige HTML-Datei, die ohne externe Abhängigkeiten auskommt.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add CoderMoray/SkillFlowChart

In Ihrer bevorzugten KI fragen

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

Dokumentation

Skill Entscheidungsflussdiagramm-Generator

Liest eine SKILL.md, extrahiert strukturierte Daten nodes.json und generiert deterministisch ein Flussdiagramm als HTML.

Arbeitsteilung

PhaseWerWarum
SKILL.md → nodes.jsonKISKILL.md ist natürliche Sprache, semantisch instabil, die KI versteht den Kontext
nodes.json → HTMLScriptKoordinatenberechnung muss deterministisch, reproduzierbar und pixelgenau sein

Die KI gibt nur strukturierte Daten aus, niemals Koordinaten oder SVG; das Script macht nur Geometrie, niemals Semantik.

Ausführungsschritte

1. SKILL.md lesen

Liest die vom Benutzer angegebene SKILL.md. Falls nicht gefunden, fragt es nach dem Pfad.

2. KI extrahiert nodes.json

Gibt JSON nach folgendem Schema aus. Jede ausgehende Kante muss explizit das Feld side enthalten – dies ist die semantische Entscheidung der KI, das Script rät nicht.

Top-Level-Struktur

{
  "title": "Skill-Name",
  "subtitle": "Optionale Beschreibung",
  "nodes": [ ... ],
  "edges": [ ... ],
  "loops": [ ... ],
  "legend": [ ... ]
}
  • nodes: Pflicht, Knoten-Array
  • edges: Pflicht, Array gerichteter Kanten
  • loops: Optional, Rückkopplungsschleifen gestrichelt (siehe unten)
  • legend: Üblich [] (leer), Standardlegende wird verwendet

Knoten type

typeBedeutungForm
entryStartpunktAbgerundetes Rechteck
decisionEntscheidungspunkt (Ja/Nein, Vorhanden/Nicht vorhanden)Raute
processVerarbeitungsschrittAbgerundetes Rechteck
outputBericht/Datei-AusgabeAbgerundetes Rechteck
terminalBeenden/Fehler-AbbruchAbgerundetes Rechteck

Knoten role (Farbgebung)

roleBedeutungfill / stroke
aiKI-Schlussfolgerung / LLM-Aufruf#E6F1FB / #185FA5
outputBericht / Datei-Ausgabe#EEEDFE / #534AB7
decisionEntscheidungspunkt#FAEEDA / #854F0B
scriptSkriptausführung#E1F5EE / #0F6E56
terminalBeenden / Fehler#FCEBEB / #A32D2D

Ein Knoten darf nur eine role haben. Enthält ein Schritt Arbeiten unterschiedlicher Art (entsprechend verschiedenen roles), muss er in mehrere Knoten aufgeteilt werden. Beispielsweise kann „Script holt Basis + KI ergänzt Analyse“ nicht zu einem Knoten mit role=ai zusammengefasst werden, sondern muss in Knoten mit role=script und role=ai aufgeteilt werden.

Kanten side (entscheidend!)

sideBedeutungLayout-Verhalten
bottomHauptfluss nach untenZiel in nächster Ebene, cx wird von Quelle geerbt
leftLinker Ast der Entscheidung / Abzweigung linksEntscheidung → gleiche Ebene horizontal; Normal → nächste Ebene orthogonale Knicklinie
rightRechter Ast der Entscheidung / Abzweigung rechtsWie links, umgekehrte Richtung

Die semantische Entscheidung von side wird von der KI getroffen:

  • Entscheidungsrauten (type=decision) mit left/right → gleiche Ebene wie die Quelle, horizontale Linie
  • Normale Rechtecke (type=process/output) mit left/right → nächste Ebene, orthogonale Knicklinie (senkrecht → waagerecht → senkrecht, keine Diagonalen)

loops (Rückkopplungsschleifen, optional, gestrichelt)

Werden verwendet, wenn der Fluss zu einem vorherigen Schritt zurückkehrt, z. B.:

  • Nach Reparatur erneut prüfen (apply_fix → entry)
  • Wiederholen (retry → checkpoint)
  • Schleife bis Bedingung erfüllt (recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Nach Reparatur erneut prüfen", "path": "left_edge" }

Feldbeschreibung:

  • from: Startknoten der Schleife (meist der letzte Schritt)
  • to: Zielknoten der Schleife (meist der Startpunkt oder ein Prüfpunkt)
  • label: Bezeichnung der Schleife, wird neben der gestrichelten Linie angezeigt
  • path: Fest auf "left_edge" (Routing entlang des linken Randes)

Hinweis:

  • Zwischen Start und Ziel der Schleife darf in edges keine weitere Kante gezeichnet werden, sonst kommt es zu doppelter Darstellung
  • Knoten in loops from/to nehmen nicht an der depth-Berechnung teil

legend

Üblich leer [], das Script verwendet die standardmäßige 5-Farben-Legende. Für benutzerdefinierte Legende:

[
  { "label": "KI-Ausführung",   "fill": "#E6F1FB", "stroke": "#185FA5" },
  { "label": "Ausgabe/Bericht", "fill": "#EEEDFE", "stroke": "#534AB7" },
  { "label": "Entscheidungspunkt",    "fill": "#FAEEDA", "stroke": "#854F0B" },
  { "label": "Script",      "fill": "#E1F5EE", "stroke": "#0F6E56" },
  { "label": "Beenden",      "fill": "#FCEBEB", "stroke": "#A32D2D" }
]

3. Script aufrufen, HTML generieren

python3 <skill_verzeichnis>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html

Das Script wird:

  • id-Eindeutigkeit, Gültigkeit von side/type/role sowie Gültigkeit von from/to-Referenzen prüfen
  • Ebenen automatisch berechnen (Seitenäste der Entscheidung gleiche Ebene / normale Abzweigungen nächste Ebene / Zusammenführung = max( eingehende Kanten ) + 1)
  • x (durch side bestimmt) und y (nach Ebene + Knotenhöhe) automatisch berechnen
  • Verbindungslinien rendern (horizontale Seitenäste / orthogonale Knicklinien / vertikaler Hauptfluss / dreiteilige Zusammenführung / gestrichelte Rückkopplungsschleifen)
  • viewBox automatisch + Legende unten
  • Eigenständiges HTML ausgeben

nodes.json-Beispiele

  • docs/halucatch-v2-nodes.json — Vollständiges Beispiel (mit loop-Schleife, Dreifach-Verzweigung, Zusammenführung)
  • docs/halucatch-nodes.json — Einfaches Beispiel
  • docs/security-review-nodes.json — Beispiel mit mehreren Entscheidungspunkten
  • docs/self-nodes.json — Minimalbeispiel (9 Knoten)

Checkliste zur Selbstprüfung

  • Eintrittsknoten type=entry ganz oben
  • Jede Kante hat das Feld side (bottom/left/right)
  • Entscheidungsrauten mit side=left/right sind Seitenäste (gleiche Ebene, horizontale Linie)
  • Normale Rechtecke mit side=left/right sind Abzweigungen (nächste Ebene, orthogonale Knicklinie)
  • Ein Knoten, eine role; gemischte Schritte wurden aufgeteilt
  • Zusammenführungspunkte (mehrere eingehende Kanten zum selben Knoten) benötigen keine spezielle Behandlung, das Script erkennt sie automatisch
  • Rückkopplungsschleifen nutzen das Feld loops, nicht edges
  • Alle Knoten-ids werden in from/to der Kanten referenziert (keine isolierten Knoten)
  • Legende leer []

Häufige Fragen

F: Was tun, wenn sich Knoten überlappen? Prüfen, ob das Feld side fehlt. Entscheidungszweige müssen side (left/right/bottom) haben, sonst erben die beiden Zielknoten dieselbe Position.

F: Die gestrichelte Rückkopplungsschleife wird nicht angezeigt? Die Schleife muss im Array loops deklariert werden (nicht in edges), und from/to dürfen in edges nicht wiederholt werden. path ist fest auf "left_edge" gesetzt.

F: Das Script meldet JSON-Formatfehler? JSON unterstützt keine Kommentare und keine einfachen Anführungszeichen. Häufige Probleme: fehlende Kommas, überflüssige Kommas (am Array-Ende), einfache Anführungszeichen.

Weitere Fragen siehe docs/FAQ.md.

Verwandte Skills