Warum eure KI immer wieder danebenliegt - und wie Markdown das behebt

Die meisten Skills, die inkonsistente Ergebnisse liefern, haben eines gemeinsam: Anweisungen sind als Fließtext geschrieben. Ein Absatz erklärt, was die KI tun soll, ein weiterer, was sie vermeiden soll. Alles hintereinander, ohne strukturiertes Signal, das Regeln von Kontext oder von Beispielen trennt.

Sowas passiert schnell bei der Erstellung von Skills. Fließtext fühlen sich natürlich an, und die Anweisungen ergeben beim Gegenlesen Sinn. Das Problem zeigt sich erst im Output. Das Modell liest alles als gleich gewichteten Text und trifft ein eigenes Urteil darüber, was zählt. Manchmal liegt es damit richtig. Aber nicht immer. Das Ergebnis: die Qualität des Outputs schwankt.

Das ist kein Problem mit dem Modell, sondern ein strukturelles. Außerdem ist es der häufigste Grund dafür, dass Skills nicht so funktionieren, wie sie sollten. Die gute Nachricht vorweg: Es gibt eine einfache Lösung. Mit Markdown gebt ihr euren Anweisungen die Struktur, die die Unklarheit beendet und zu konsistenten Ergebnissen führt. In diesem Artikel lernt ihr, wie das konkret funktioniert.

Was ist Markdown eigentlich?

Markdown ist Klartext mit einem kleinen Satz an Formatierungssymbolen, die einem Renderer mitteilen, wie der Inhalt dargestellt werden soll. 2004 von John Gruber entwickelt (mit Aaron Swartz als zentralem Mitentwickler), entstand es unter einer Prämisse: Die Rohdatei soll lesbar sein, ohne sie zu rendern. Das ##-Symbol für eine Überschrift, die ** für fetten Text - diese Zeichen wurden gewählt, weil sie ihre Funktion visuell andeuten, bevor ein Tool sie verarbeitet.

Web Dev Simplified’s Markdown Crash Course bringt es auf den Punkt: Markdown ist ein schreiborientiertes Format, das Klartext in strukturell valides HTML umwandelt. Die Rohansicht ist der Bauplan. Die gerenderte Ansicht ist das fertige Haus.

Wenn beim Öffnen einer .md-Datei in Notepad oder TextEdit ##-Symbole sowie Sternchen statt formatiertem Text angezeigt werden, ist nichts kaputt. Die Datei wurde lediglich in einem Tool geöffnet, das den Bauplan anzeigt, statt das Haus zu rendern. Dieselbe Datei in Dillinger, Typora oder nuwacom’s Skill-Editor geöffnet, sieht aus wie ein normales Dokument. Die Datei ist die gleiche, nur das Tool, das sie anzeigt hat sich geändert.

Markdown-Syntax: Die sechs Symbole, die ihr kennen solltet

Die folgende Tabelle zeigt, was in einem rohen Texteditor zu sehen ist und was ein Renderer daraus macht.

Sechs Muster. Das ist das Arbeitsvokabular für die meisten Skill-Dateien und Knowledge Base-Einträge, die ihr in nuwacom schreiben werdet.

Überschriften verwenden #-Symbole. Ein # ist der Dokumenttitel. ## markieren einen Hauptabschnitt. ### ist ein Unterabschnitt. Die meisten Dokumente gehen nicht tiefer als drei Ebenen - wer tiefer geht, muss meistens die Struktur überdenken, nicht die Verschachtelung.

Fett und kursiv verwenden Sternchen. **Text** wird zu fett. *Text* wird zu kursiv. Beide Markierungen verschwinden nach dem Rendern. Web Dev Simplified empfiehlt * statt _ für Kursivschrift -, denn Unterstriche können sich innerhalb von zusammengesetzten Wörtern unerwartet verhalten.

Links folgen dem Muster sichtbarerTextsichtbarer Text(URL). Kein Leerzeichen zwischen der schließenden eckigen Klammer und der öffnenden runden Klammer. Einer der wenigen Fälle, in denen ein fehlendes Zeichen die Ausgabe vollständig zerstört.

Code verwendet Backticks. Einzelner Backtick für Inline-Referenzen: `so`. Drei Backticks auf einer eigenen Zeile öffnen und schließen einen Block - nützlich für Skill-Anweisungen, Konfigurationsbeispiele oder alles, was wörtlich angezeigt statt interpretiert werden soll.

Der Markdown Guide Cheat Sheet deckt die vollständige Syntax ab. Die Basic Syntax Referenz enthält die Details hinter jedem Element.

Warum Struktur verändert, was die KI mit euren Anweisungen macht

Große Sprachmodelle lesen Text nicht einfach. Sie parsen ihn. Wenn Eingaben als unformatierter Fließtext ankommen, muss das Modell inferieren, was eine Regel, was Kontext, was ein Beispiel und was eine Einschränkung ist, alles aus demselben undifferenzierten Textstrom. Es trifft vernünftige Schlussfolgerungen. Doch einige davon sind falsch.

Hier ein Beispiel aus der Praxis.

Dieselbe Skill-Anweisung, auf zwei verschiedene Arten geschrieben:

Version als Fließtext:

Du bist ein Kundenantwort-Assistent. Antworte bei Kundenanfragen professionell und direkt. Beantworte zuerst die Frage, bevor Du Kontext hinzufügst. Halte Antworten kurz, unter 150 Wörtern. Vermeide Passivkonstruktionen oder Zusagen zu Lieferterminen ohne bestätigte Verfügbarkeit. Schließ immer mit einem konkreten nächsten Schritt. Vermeide Abschlussformeln wie „Zögert nicht, uns zu kontaktieren."

Strukturierte Markdown-Version:

Beide enthalten dieselben Informationen. Das Modell, das die Fließtextversion liest, behandelt sie als kontinuierliches Argument, in dem alles ungefähr gleich gewichtet ist. Es muss raten, ob „unter 150 Wörter" eine harte Einschränkung oder eine Präferenz ist und ob „kein Passiv" eine Regel oder eine stilistische Empfehlung ist.

Das Modell, das die Markdown-Version liest, muss nicht raten. ## Anweisungen signalisiert Direktive. ## Vermeiden signalisiert Einschränkungen. ## Erwartete Ausgabe signalisiert Bewertungskriterien. Die Hierarchie ist explizit.

Das Modell wird dadurch nicht intelligenter. Aber, es muss weniger Inferenzaufwand für die Struktur betreiben und kann mehr auf die Ausführung verwenden. So kommt der Qualitätsunterschied im Output zustande.

Wie man MD-Dateien in nuwacom verwendet

MD-Dateien tauchen an drei Stellen innerhalb von nuwacom auf. Das macht ihr jeweils konkret damit.

Skills und benutzerdefinierte Anweisungen

Ein Skill in nuwacom ist ein strukturierter Anweisungssatz, der definiert, wie die KI bei einer bestimmten Aufgabe vorgeht: was sie produzieren soll, wie sie es produzieren soll, was sie vermeiden soll. Der Skill ist in Markdown geschrieben. Die Überschriften sind keine Dekoration: Sie sind die Signale, die dem Modell mitteilen, welche Kategorie von Information es gerade liest.

Die meisten Skill-Dateien beginnen mit einem YAML-Metadatenblock. Bevor die KI eine einzige Anweisung liest, muss sie wissen, mit welcher Art von Dokument sie es zu tun hat und wer damit arbeitet. Der YAML-Block beantwortet das. Ihr könnt ihn euch wie ein Etikett auf einem Aktenhefter vorstellen - der Ordner enthält eure Anweisungen, und das Etikett sagt dem System, was drin ist, bevor es ihn überhaupt öffnet.

Jede Zeile ist ein Feld. Das role-Feld ist das entscheidende. Es legt die professionelle Identität fest, die die KI annimmt, bevor sie irgendetwas anderes im Skill liest. Wenn ein LLM role: Expert Customer Communication Specialist sieht, startet das Modell nicht von null. Es startet von einem definierten Verhaltensbasiswert. Alles, was folgt, wird durch diese Linse interpretiert. Der Abschnitt Best Practices erklärt, was in jedes Feld gehört und warum das wichtig ist.

Unterhalb des YAML-Blocks wird der Skill selbst in Markdown geschrieben. Eine vollständige, funktionierende Datei sieht so aus:

Das Modell liest ## Anweisungen und weiß, dass es Direktive parst. Es liest ## Vermeiden und weiß, dass es Einschränkungen parst. Beides als unformatierten Fließtext und das Modell behandelt sie als gleich gewichteten Text. Dies führt zu variablen Ergebnissen.

Dokumentation

nuwacom kann Leitfäden, Prozesse und Referenzdokumentation in Markdown speichern, weil Klartext sowohl von Menschen als auch von Retrieval-Systemen gelesen werden kann. Aktualisierungen erfordern keine Spezialsoftware. Jeder Texteditor verarbeitet die Änderung. Jeder Markdown-Renderer verifiziert das Ergebnis.

Praktisch heißt das: Einen Abschnitt zu einer bestehenden Datei hinzufügen, ohne ihre Struktur zu brechen. Eine ## Überschrift auf der richtigen Ebene einfügen, den Inhalt darunter schreiben, speichern. Die Datei bleibt valides Markdown. Jedes Tool, das sie vorher verarbeitet hat, tut das weiterhin.

Knowledge Base-Einträge

Knowledge Base-Einträge definieren, was das System über euer Unternehmen weiß: Produkte, Prozesse, Terminologie, Einschränkungen, Ausnahmefälle. Struktur ist hier wichtig, weil sie einen spezifischen Fehlerfall reduziert - das Modell, das Informationen im falschen Kontext anwendet.

nuwacom kann viele verschiedene Dateitypen verarbeiten, darunter PDFs, Word-Dokumente, Tabellen, Präsentationen und mehr. Ihr müsst also nichts konvertieren, nur um es zu verwenden. Aber es gibt einen Unterschied zwischen dem, was funktioniert, und dem, was gut funktioniert. Wenn ein Knowledge Base-Eintrag in Markdown mit sauberen Überschriften vorliegt, kann das Modell den Unterschied zwischen einem „Technische Spezifikationen"-Abschnitt - das sind allgemeine Produktdaten - und einem „Bekannte Ausnahmefälle"-Abschnitt - das ist Verhalten, das von der Norm abweicht - erkennen. Ist alles in Fließtext geschrieben, oder in einem PDF ohne strukturelle Signale gespeichert - und das Modell muss inferieren, welche Aussagen allgemein und welche Ausnahmen sind. Das kostet Rechenaufwand und erhöht die Wahrscheinlichkeit, dass das Modell Gefundenes falsch anwendet.

Wann lohnt sich die Konvertierung?

Dies ist keine Empfehlung, jede Datei in der Organisation zu konvertieren. Das wäre übertrieben. Das lohnt sich vor allem, wenn ihr ein spezifisches Projekt aufbaut - sagen wir, ihr erstellt eine Kundenpräsentation oder startet einen Produktlaunch, und es stellt fünf bis zehn Dateien bereit, die für diese Arbeit besonders relevant sind. Produktspezifikationen, Markenrichtlinien, zentrale Referenzdokumente. Bei diesen Dateien lohnt sich die Konvertierung zu Markdown vor dem Hochladen in eure Knowledge Base. Das ist eine kleine, gezielte Investition in Struktur, die sich jedes Mal auszahlt, wenn das Modell Informationen aus diesen Dokumente abruft.

Nützliche Tools

Die folgenden Tools sind kleine, kostenlose Helfer, die wir für unsere Markdown-Workflows gern nutzen:

• Markdown-zu-Richtext-Konverter. Wie der Name sagt, konvertiert dieser Markdown zu Richtext - nützlich, wenn ihr zum Beispiel Skill-Anweisungen in einer für Menschen besser lesbaren Form teilen möchtet.

• Richtext-zu-Markdown-Konverter: Dieser übernimmt die Konvertierung in die andere Richtung sehr zuverlässig. Wenn ihr bestehende Dokumente an KI übergeben wollt, ist das Tool sehr hilfreich.

• t0md - Files to MD converter: Ein guter Konvertierer für PDFs, PPTX, Docx und andere Dateien zu Markdown.

Best Practices für das Schreiben von Markdown in nuwacom

Korrektes Markdown und effektives Markdown sind nicht dasselbe. Eine Datei kann ohne Fehler rendern und trotzdem inkonsistente KI-Outputs produzieren, weil die Struktur mehrdeutig, die Abschnitte überladen oder die Einschränkungen zu vage sind. Durch befolgen von Best Practices vermeidet ihr dies.

YAML-Metadaten

• Füllt den YAML-Block jedes Mal aus. Er ist kein optionaler Boilerplate. LLMs lesen das role-Feld, bevor sie das Markdown darunter verarbeiten. Ein Skill ohne definierte Rolle gibt der KI keinen Identitätsanker - das Modell fällt in eine generische Antworthaltung zurück, egal wie gut die Anweisungen geschrieben sind.

• Schreibt die Rolle als Berufsbezeichnung, nicht als Beschreibung. Expert Customer Communication Specialist funktioniert. „Ein hilfreicher Assistent, der auf Kundenanfragen antwortet" tut es nicht - zu diffus, um eine aussagekräftige Verhaltensbasis zu etablieren.

• Begrenzt die Beschreibung auf einen Satz. Es ist ein Routing-Signal, keine Zusammenfassung. Wer mehr als einen Satz schreibt, platziert Anweisungsinhalt im falschen Feld.

Überschriften-Hierarchie

• Beginnt jeden Skill mit einem einzelnen #-Titel. Ein H1 pro Datei. Alles andere ist ## oder ###. Mehrere H1s signalisieren dem Modell, dass das Dokument mehrere Wurzeln hat, was die Hierarchie untergräbt, die ihr aufzubauen versucht.

• Verwendet ## für Hauptabschnitte, ### nur wenn ein Abschnitt wirklich Unterkomponenten hat. Wer nach ### greift, weil ein ##-Abschnitt lang wird, muss den Abschnitt wahrscheinlich aufteilen, nicht untergliedern.

• Keine Ebenen überspringen. Von ## zu #### ohne ### dazwischen zu springen, erzeugt strukturelle Lücken, die das Modell inferentiell überbrücken muss. Die Hierarchie sollte nicht unterbrochen werden.

Skill-Abschnitte

• Jeden Abschnitt kurz genug halten, um ihn in unter zehn Sekunden zu scannen. Wenn ## Anweisungen zwölf Aufzählungspunkte umfasst, arbeitet das Modell durch eine Liste, die lang genug ist, um die Prioritätsgewichtung zu verlieren. Dann lieber in zwei benannte Abschnitte aufteilen.

• Ein Gedanke pro Aufzählungspunkt. Ein Punkt, der zwei Anweisungen mit „und" verbindet, sind zwei Punkte. Zusammengesetzte Anweisungen erzeugen zusammengesetzte Mehrdeutigkeit.

• ## Das „Warum" hinter der Einschränkung mitliefern „Kein Passiv" ist eine Regel. „Passivkonstruktionen vermeiden, weil sie verschleiern, wer für eine Handlung verantwortlich ist, was in kundengerichteten Antworten wichtig ist" ist eine Einschränkung, auf die das Modell auch bei unvorhergesehenen Ausnahmefällen urteilen kann. Die Begründung ist das, was die Regel übertragbar macht.

Beispiel-Abschnitte

• Immer ## Beispiel-Eingabe und ## Beispiel-Ausgabe einschließen. Diese zwei Abschnitte tun mehr zur Verankerung konsistenten KI-Verhaltens als jeder andere Teil des Skills. Das Modell nutzt sie zur Kalibrierung der Lücke zwischen einer rohen Eingabe und einer akzeptablen Ausgabe - Länge, Ton, Struktur, Detailtiefe. Anweisungen sagen dem Modell, was es tun soll. Beispiele zeigen, wie fertig aussieht.

• Ein echtes Beispiel verwenden, kein Platzhalter. [Beispiel hier einfügen] trägt nichts bei. Ein tatsächliches Beispiel aus dem Workflow ziehen - eine echte Kundenanfrage, eine echte Meetingnotiz, eine echte Produktfrage - und die Ausgabe schreiben, die die KI produzieren soll. Je näher das Beispiel an der Produktionsrealität ist, desto besser die Kalibrierung.

• Wenn ein Skill mehr als einen Eingabetyp verarbeitet, für jeden Typ ein Beispiel einschließen. Ein Skill, der sowohl kurze Anfragen als auch detaillierte Beschwerden verarbeitet, braucht beide abgebildet. Ein einzelnes Beispiel verankert das Modell an einem einzigen Muster.

Knowledge Base-Einträge

• Fakten und Ausnahmefälle auf Überschriftenebene trennen. Allgemeine Produktinformationen und bekannte Ausnahmefälle gehören unter verschiedene ## Überschriften, nicht in denselben Absatz. Die Überschrift sagt dem Modell, welche Kategorie von Aussagen es liest.

• Die wichtigsten Informationen innerhalb jeden Abschnitts zuerst. nuwacom ruft Kontext unter Zeit- und Token-Einschränkungen ab. Wenn die kritische Spezifikation im fünften Satz eines Absatzes vergraben ist, taucht sie möglicherweise nicht auf, wenn sie gebraucht wird. Mit der Aussage führen, dann belegen.

• Ausnahmefälle explizit kennzeichnen. Nicht auf Abschwächungssprache wie „normalerweise" oder „in den meisten Fällen" vertrauen, um eine Ausnahme zu signalisieren. Einen ## Ausnahmefälle- oder ## Sonderfälle-Abschnitt schreiben und die Abweichung dort explizit benennen.

Dokumentationsdateien

• Ein Thema pro Datei. Eine Dokumentationsdatei, die drei verwandte Prozesse abdeckt, ist schwieriger abzurufen und schwieriger zu pflegen als drei spezifische Dateien. nuwacom’s Retrieval funktioniert bei engen, gut beschrifteten Dokumenten besser als bei Dokumenten, die mehrere Themen abdecken.

• Den Dateinamen als Zusammenfassung nutzen. kundenanfragen-beantworten.md ist abrufbar. dok-v3-final.md ist es nicht. Der Dateiname ist Teil der Metadaten. Behandelt ihn dementsprechend.

• Das YAML-Beschreibungsfeld aktualisieren, wenn sich der Inhalt ändert. Veraltete Metadaten erzeugen einen Widerspruch zwischen dem, was nuwacom in einer Datei zu finden erwartet, und dem, was tatsächlich darin steht. Die Beschreibung aktuell halten.

Starter-Template

Ihr könnt diese Vorlage verwenden, wenn ihr einen neuen Skill in nuwacom aufbaut. Kopiert ihn, passt die Werte an, verifiziert die Ausgabe in Dillinger und ladet sie dann als Skill hoch.

Mit .md-Endung speichern - den Dateinamen manuell im Speichern-Dialog eingeben, wenn der Editor standardmäßig .txt verwendet. In Dillinger öffnen, um zu verifizieren, dass die Struktur korrekt rendert, dann in nuwacom’s Skill-Editor laden.

Zum Abschluss

Markdown ist keine technische Anforderung. Es ist eine Kommunikationsentscheidung. Jedes Mal, wenn ihr ein Dokument strukturiert - ob einen Skill, einen Knowledge Base-Eintrag, einen Prozessleitfaden - entscheidet ihr, wie viel inferentiellen Aufwand ihr der KI abverlangt, bevor sie zur eigentlichen Aufgabe kommt. Strukturierter Input bedeutet weniger Unklarheit. Weniger Unklarheit bedeutet konsistentere Outputs. Diese Beziehung gilt, egal ob ihr einen einzelnen Skill aufbaut oder ein System aus fünfzig verwaltet.

Das Format lernt man an einem Nachmittag. Was sich langfristig auszahlt, ist die Disziplin, es konsequent einzusetzen. Markdown macht Dokumente einfacher zu aktualisieren, einfacher zu scannen und für jeden lesbar, ob Mensch oder Maschine.

Gut geschriebenes Markdown macht nicht nur eure Dateien besser verständlich. Es macht euer gesamtes System zuverlässiger.