Markdown und Mermaid Schreiben
Überblick
Diese Fähigkeit lehrt Sie — und setzt einen Standard durch — für die Erstellung wissenschaftlicher Dokumentation unter Verwendung von Markdown mit eingebetteten Mermaid-Diagrammen als Standard- und kanonischem Format.
Die Kernannahme: Eine als Mermaid-Diagramm innerhalb einer .md-Datei ausgedrückte Beziehung ist wertvoller
als jedes Bild. Es ist Text, also diffed es sauber in Git. Es erfordert keinen Build-Schritt.
Es rendert nativ auf GitHub, GitLab, Notion, VS Code und jedem Markdown-Viewer. Es verwendet
weniger Tokens als eine Prosabeschreibung derselben Beziehung. Und es kann jederzeit in ein
poliertes Bild konvertiert werden — aber die Textversion bleibt die Source of Truth.
„Je mehr Sie Ihre Berichte und Dateien in .md in normalem Text halten, was Mermaid ebenfalls ist, als einfache „Skriptsprache“. Dies hilft bei jedem nachgelagerten Rendering und besonders bei KI-generierten Bildern (Verwendung von Mermaid anstelle von langem Fließtext zur Beschreibung von Beziehungen < Tokens). Darüber hinaus kann Mermaid zusammen mit Markdown rendern für einfache Verwendung fast überall durch Menschen oder KI."
— Clayton Young (@borealBytes), K-Dense Discord, 19.02.2026
Wann Diese Fähigkeit Verwenden
Verwenden Sie diese Fähigkeit, wenn:
- Sie ein wissenschaftliches Dokument erstellen — Berichte, Analysen, Manuskripte, Methodenteile
- Sie Dokumentation schreiben — READMEs, Anleitungen, Entscheidungsprotokolle, Projektdokumente
- Sie ein Diagramm erstellen — Arbeitsabläufe, Datenpipelines, Architekturen, Zeitpläne, Beziehungen
- Sie eine Ausgabe generieren, die versioniert wird — wenn es in Git geht, sollte es Markdown sein
- Sie mit einer anderen Fähigkeit arbeiten — diese Fähigkeit definiert die Dokumentationsebene, die jede andere Ausgabe umschließt
- Jemand Sie bittet, „ein Diagramm hinzuzufügen“ oder „die Beziehung zu visualisieren“ — Mermaid zuerst, immer
Verwenden Sie NICHT zuerst Python matplotlib, seaborn oder KI-Bildgenerierung für strukturelle oder relationale Diagramme. Dies sind Phase 2 und Phase 3 — nur verwendet, wenn Mermaid nicht ausdrücken kann, was benötigt wird (z. B. Streudiagramme mit echten Daten, fotorealistische Bilder).
🎨 Die Philosophie des Quellformats
Warum textbasierte Diagramme gewinnen
| Was zählt | Mermaid in Markdown | Python / KI-Bild |
|---|---|---|
| Git-diff lesbar | ✅ | ❌ binärer Blob |
| Bearbeitbar ohne Neugenerierung | ✅ | ❌ |
| Tokeneffizienter als Prosa | ✅ kleiner | ❌ größer |
| Rendert ohne Build-Schritt | ✅ | ❌ benötigt Hosting |
| Von KI ohne Sicht auslesbar | ✅ | ❌ |
| Funktioniert in GitHub/GitLab/Notion | ✅ | ⚠️ wenn gehostet |
| Barrierefrei (Screenreader) | ✅ accTitle/accDescr | ⚠️ benötigt Alt-Text |
| Später in Bild konvertierbar | ✅ jederzeit | — bereits Bild |
Der Drei-Phasen-Workflow
flowchart LR
accTitle: Drei-Phasen-Dokumentations-Workflow
accDescr: Phase 1 Mermaid in Markdown ist immer erforderlich und ist die Source of Truth. Phasen 2 und 3 sind optionale nachgelagerte Konvertierungen für polierte Ausgaben.
p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(IMMER — Source of Truth)"]
p2["🐍 Phase 2<br/>Python Generiert<br/>(optional — Datencharts)"]
p3["🎨 Phase 3<br/>KI Generierte Visuals<br/>(optional — Politur)"]
out["📊 Endgültiges Ergebnis"]
p1 --> out
p1 -.->|"wenn nötig"| p2
p1 -.->|"wenn nötig"| p3
p2 --> out
p3 --> out
classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class p1 required
class p2,p3 optional
class out output
Phase 1 ist obligatorisch. Auch wenn Sie zu Phase 2 oder 3 übergehen, bleibt die Mermaid-Quelle committed.
Was Mermaid ausdrücken kann
Mermaid umfasst 24 Diagrammtypen. Fast jede wissenschaftliche Beziehung passt in einen:
| Anwendungsfall | Diagrammtyp | Datei |
|---|---|---|
| Experimenteller Arbeitsablauf / Entscheidungslogik | Flussdiagramm | references/diagrams/flowchart.md |
| Dienstinteraktionen / API-Aufrufe / Nachrichten | Sequenzdiagramm | references/diagrams/sequence.md |
| Datenmodell / Schema | ER-Diagramm | references/diagrams/er.md |
| Zustandsmaschine / Lebenszyklus | Zustandsdiagramm | references/diagrams/state.md |
| Projektzeitplan / Roadmap | Gantt-Diagramm | references/diagrams/gantt.md |
| Proportionen / Zusammensetzung | Kreisdiagramm | references/diagrams/pie.md |
| Systemarchitektur (Zoomstufen) | C4-Diagramm | references/diagrams/c4.md |
| Konzepthierarchie / Brainstorming | Mindmap | references/diagrams/mindmap.md |
| Chronologische Ereignisse / Verlauf | Zeitleiste | references/diagrams/timeline.md |
| Klassenhierarchie / Typbeziehungen | Klassendiagramm | references/diagrams/class.md |
| Benutzerreise / Zufriedenheitskarte | Benutzerreise | references/diagrams/user_journey.md |
| Zwei-Achsen-Vergleich / Priorisierung | Quadrantendiagramm | references/diagrams/quadrant.md |
| Anforderungsrückverfolgbarkeit | Anforderungsdiagramm | references/diagrams/requirement.md |
| Flussstärke / Ressourcenverteilung | Sankey-Diagramm | references/diagrams/sankey.md |
| Numerische Trends / Balken- + Liniendiagramme | XY-Diagramm | references/diagrams/xy_chart.md |
| Komponentenlayout / räumliche Anordnung | Blockdiagramm | references/diagrams/block.md |
| Arbeitsitem-Status / Aufgabenspalten | Kanban-Board | references/diagrams/kanban.md |
| Cloud-Infrastruktur / Service-Topologie | Architekturdiagramm | references/diagrams/architecture.md |
| Mehrdimensionaler Vergleich / Fähigkeiten-Radar | Radardiagramm | references/diagrams/radar.md |
| Hierarchische Proportionen / Budget | Treemap-Diagramm | references/diagrams/treemap.md |
| Binäres Protokoll / Datenformat | Paketdiagramm | references/diagrams/packet.md |
| Git-Verzweigung / Merge-Strategie | Git-Graph | references/diagrams/git_graph.md |
| Code-artige Sequenz (Programmiersyntax) | ZenUML | references/diagrams/zenuml.md |
| Multi-Diagramm-Kompositionsmuster | Komplexe Beispiele | references/diagrams/complex_examples.md |
💡 Wählen Sie den richtigen Typ, nicht den einfachen. Verwenden Sie nicht standardmäßig Flussdiagramme für alles. Eine Zeitleiste ist besser als ein Flussdiagramm für chronologische Ereignisse. Ein Sequenzdiagramm ist besser als ein Flussdiagramm für Dienstinteraktionen. Durchsuchen Sie die Tabelle und wählen Sie passend.
🔧 Kern-Workflow
Schritt 1: Identifizieren Sie den Dokumenttyp
Prüfen Sie, ob eine Vorlage existiert, bevor Sie von Grund auf schreiben:
| Dokumenttyp | Vorlage |
|---|---|
| Pull-Request-Protokoll | templates/pull_request.md |
| Issue / Fehler / Funktionswunsch | templates/issue.md |
| Sprint / Projektboard | templates/kanban.md |
| Architekturentscheidung (ADR) | templates/decision_record.md |
| Präsentation / Briefing | templates/presentation.md |
| Forschungsarbeit / Analyse | templates/research_paper.md |
| Projektdokumentation | templates/project_documentation.md |
| Anleitung / Tutorial | templates/how_to_guide.md |
| Statusbericht | templates/status_report.md |
Schritt 2: Lesen Sie den Styleguide
Bevor Sie eine .md-Datei schreiben: lesen Sie references/markdown_style_guide.md.
Wichtige Regeln zu verinnerlichen:
- Ein H1 pro Dokument — der Titel. Niemals mehr.
- Emoji nur auf H2-Überschriften — ein Emoji pro H2, keins in H3/H4
- Alles zitieren — jede externe Behauptung erhält eine Fußnote
[^N]mit vollständiger URL - Fettdruck sparsam verwenden — max. 2–3 fette Begriffe pro Absatz, niemals ganze Sätze
- Horizontale Linie nach jedem
</details>— obligatorisch - Tabellen vor Fließtext für Vergleiche, Konfigurationen, strukturierte Daten
- Diagramme vor Textwänden — wenn es Fluss, Struktur oder Beziehungen beschreibt, fügen Sie Mermaid hinzu
Schritt 3: Wählen Sie den Diagrammtyp und lesen Sie dessen Anleitung
Bevor Sie ein Mermaid-Diagramm erstellen: lesen Sie references/mermaid_style_guide.md.
Öffnen Sie dann die spezifische Typdatei (z. B. references/diagrams/flowchart.md) für das Beispiel, Tipps und die Kopiervorlage.
Obligatorische Regeln für jedes Diagramm:
accTitle: Kurzname 3-8 Wörter
accDescr: Ein oder zwei Sätze, die erklären, was dieses Diagramm zeigt.
- Keine
%%{init}-Direktiven — bricht GitHub Dark Mode - Kein Inline-
style— verwenden Sie nurclassDef - Max. ein Emoji pro Knoten — am Anfang des Labels
snake_case-Knoten-IDs — passen Sie zum Label
Schritt 4: Schreiben Sie das Dokument
Beginnen Sie mit der Vorlage. Wenden Sie den Markdown-Styleguide an. Platzieren Sie Diagramme inline beim zugehörigen Text — nicht in einem separaten „Abbildungen“-Abschnitt.
Schritt 5: Als Text committen
Die .md-Datei mit eingebettetem Mermaid wird committed. Wenn Sie auch ein PNG oder KI-Bild generiert haben, sind diese ergänzend — das Markdown ist die Quelle.
⚠️ Häufige Fallstricke
Radar-Chart-Syntax (radar-beta)
FALSCH:
radar
title Beispiel
x-axis ["A", "B", "C"]
"Serie" : [1, 2, 3]
RICHTIG:
radar-beta
title Beispiel
axis a["A"], b["B"], c["C"]
curve serie["Serie"]{1, 2, 3}
max 3
- Verwenden Sie
radar-betanichtradar(das bloße Schlüsselwort existiert nicht) - Verwenden Sie
axisum Dimensionen zu definieren, nichtx-axis - Verwenden Sie
curveum Datenreihen zu definieren, nicht zitierte Labels mit Doppelpunkt - Kein
accTitle/accDescr— radar-beta unterstützt keine Barrierefreiheits-Anmerkungen; fügen Sie immer einen beschreibenden kursiven Absatz oberhalb des Diagramms hinzu
XY-Chart vs. Radar-Verwechslung
| Diagramm | Schlüsselwort | Achsen-Syntax | Datensyntax |
|---|---|---|---|
| XY-Chart (Balken/Linien) | xychart-beta | x-axis ["Label1", "Label2"] | bar [10, 20] oder line [10, 20] |
| Radar (Spinnennetz) | radar-beta | axis id["Label"] | curve id["Label"]{10, 20} |
Vergessen von accTitle/accDescr bei unterstützten Typen
Nur einige Diagrammtypen unterstützen accTitle/accDescr. Fügen Sie bei solchen, die es nicht tun, immer einen beschreibenden kursiven Absatz direkt oberhalb des Code-Blocks ein:
Radarchart, der drei Methoden über fünf Leistungsdimensionen vergleicht. Hinweis: Radarcharts unterstützen kein accTitle/accDescr.
radar-beta
...
🔗 Integration mit anderen Fähigkeiten
Mit scientific-schematics
scientific-schematics generiert KI-gestützte publikationsfähige Bilder (PNG). Verwenden Sie das Mermaid-Diagramm als Vorlage für die Schemazeichnung:
Workflow:
1. Erstellen Sie das Konzept als Mermaid in .md (diese Fähigkeit — Phase 1)
2. Beschreiben Sie dasselbe Konzept für scientific-schematics für ein poliertes PNG (Phase 3)
3. Committen Sie beides — die .md als Quelle, das PNG als ergänzende Abbildung
Mit scientific-writing
Wenn scientific-writing ein Manuskript erstellt, sollten alle Diagramme und Strukturabbildungen die Standards dieser Fähigkeit verwenden. Die Schreibfähigkeit behandelt Prosa und Zitate; diese Fähigkeit behandelt visuelle Struktur.
Workflow:
1. Verwenden Sie scientific-writing, um das Manuskript zu verfassen
2. Ersetzen Sie für jede Abbildung, die einen Arbeitsablauf, eine Architektur oder eine Beziehung zeigt:
- Platzhalter durch ein Mermaid-Diagramm gemäß der Anleitung dieser Fähigkeit
3. Verwenden Sie scientific-schematics nur für Abbildungen, die wirklich fotorealistisches/komplexes Rendering benötigen
Mit literature-review
literature-review erzeugt Zusammenfassungen mit vielen Beziehungsdaten. Verwenden Sie diese Fähigkeit, um:
- Konzeptkarten (Mindmap) der Literaturlandschaft zu erstellen
- Publikationszeitpläne anzuzeigen (Timeline oder Gantt)
- Methodiken zu vergleichen (Quadrant oder Radar)
- Datenflüsse aus Papieren zu diagrammieren (Sequenz oder Flowchart)
Mit jeder Fähigkeit, die Ausgabedokumente erzeugt
Bevor Sie ein Dokument aus einer Fähigkeit finalisieren, wenden Sie die Checkliste dieser Fähigkeit an:
- Verwendet das Dokument eine Vorlage? Wenn ja, habe ich mit der richtigen begonnen?
- Sind alle Diagramme in Mermaid mit
accTitle+accDescr? - Kein
%%{init}, kein Inline-style, nurclassDef? - Sind alle externen Behauptungen mit
[^N]zitiert? - Ein H1, Emoji nur auf H2?
- Horizontale Linien nach jedem
</details>?
📚 Referenzindex
Styleguides
| Anleitung | Pfad | Zeilen | Was wird behandelt |
|---|---|---|---|
| Markdown-Styleguide | references/markdown_style_guide.md | ~733 | Überschriften, Formatierung, Zitate, Tabellen, Mermaid-Integration, Vorlagen, Qualitätscheckliste |
| Mermaid-Styleguide | references/mermaid_style_guide.md | ~458 | Barrierefreiheit, Emoji-Set, Farbklassen, Themenneutralität, Typauswahl, Komplexitätsstufen |
Diagrammtyp-Anleitungen (24 Typen)
Jede Datei enthält: ein produktionsreifes Beispiel, Tipps spezifisch für diesen Typ und eine Kopiervorlage.
references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml
Dokumentvorlagen (9 Typen)
templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report
Beispiele
assets/examples/example-research-report.md — ein vollständiger wissenschaftlicher Forschungsbericht, der die richtige Überschriftenhierarchie, mehrere Diagrammtypen (Flussdiagramm, Sequenz, Gantt), Tabellen, Fußnotenzitate, einklappbare Abschnitte und alle Regeln des Styleguides demonstriert.
📝 Zuschreibung
Alle Styleguides, Diagrammtyp-Anleitungen und Dokumentvorlagen in dieser Fähigkeit stammen aus dem Repository SuperiorByteWorks-LLC/agent-project unter der Apache-2.0-Lizenz.
- Quelle: https://github.com/SuperiorByteWorks-LLC/agent-project
- Autor: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- Lizenz: Apache-2.0
Diese Fähigkeit (als Teil von scientific-agent-skills) wird unter der MIT-Lizenz vertrieben. Die enthaltenen Apache-2.0-Inhalte sind kompatibel für die nachgelagerte Nutzung unter Beibehaltung der Zuschreibung, wie in den Dateiköpfen dieser Fähigkeit erhalten.