Wie man SKILL.md und Tool-Beschreibungen in Markdown für KI-Agenten schreibt

KI-Assistenten werden wesentlich nützlicher, wenn sie stabilen Anweisungen folgen, Domänenwissen laden und Tools sicher ausführen können. Markdown ist das ideale Format für diese Ebene, da es für Menschen leicht lesbar und versionierbar ist, während es für Modelle eine klar strukturierte logische Hierarchie bietet.

Dieser Artikel erklärt, wie man Markdown-basierte SKILL.md-Dateien, Agenten-Anweisungsdateien und Tool-Nutzungsbeschreibungen schreibt. Das Ziel ist nicht, Prompts unnötig zu verlängern. Das Ziel ist es, Fähigkeiten für einen KI-Agenten leichter auffindbar, verständlich und zum richtigen Zeitpunkt ausführbar zu machen.

Was ist eine SKILL.md-Datei?

Eine SKILL.md-Datei ist eine in Markdown verfasste Anweisungsdatei, die eine wiederverwendbare Fähigkeit (Skill) beschreibt. In Systemen wie Claude Code von Anthropic sind Skills Dateisystem-Artefakte, die in einem speziellen Skills-Verzeichnis gespeichert werden. Jeder Skill wird durch eine eigene SKILL.md-Datei definiert. Das Prinzip ist über verschiedene Agenten-Systeme hinweg dasselbe: Ein kurzes, strukturiertes Dokument teilt dem Agenten mit, wann er eine Fähigkeit nutzen soll, welchem Workflow er folgen muss und wo unterstützende Skripte oder Referenzen liegen.

Das mentale Modell dahinter ist denkbar einfach:

  • Ein normaler Prompt sagt der KI, was sie im aktuellen Schritt tun soll.
  • Ein Skill (SKILL.md) lehrt die KI, wie sie eine ganze Kategorie von Aufgaben wiederholt ausführen kann.
  • Eine Tool-Beschreibung sagt der KI, wann und wie sie eine bestimmte externe Funktion oder API aufrufen soll.

Da ein Skill hauptsächlich aus Anweisungen, Beispielen, Einschränkungen und Verweisen besteht, ist Markdown dafür das perfekte Format.

Warum Markdown so gut für Agenten-Skills funktioniert

Agenten-Anweisungen müssen zwei Lesern dienen: dem KI-Modell und dem menschlichen Entwickler. Markdown unterstützt beide hervorragend.

Für die KI trennen Überschriften und Listen die Aktivierungsbedingungen, Workflow-Schritte, Einschränkungen, Beispiele und das Fehlerhandling voneinander ab. Für Menschen kann dieselbe Datei in Git überprüft, in jedem Texteditor bearbeitet und direkt neben dem Code dokumentiert werden.

Dies ist bei Skills und Tools von entscheidender Bedeutung, da unklare Anweisungen zu Fehlern im automatisierten Ablauf führen können. Ein vager Skill wird möglicherweise zum falschen Zeitpunkt aktiviert. Eine ungenaue Tool-Beschreibung kann dazu führen, dass das Modell ein Tool mit falschen Argumenten aufruft. Ein fehlender Sicherheitshinweis kann dazu führen, dass der Agent eine Aktion ausführt, bevor ausreichende Belege vorliegen.

Der Unterschied zwischen Skills und Tool-Beschreibungen

Skills und Tools sind verwandt, erfüllen jedoch unterschiedliche Aufgaben:

| Element | Zweck | Beispiel | |---|---|---| | Skill (Fähigkeit) | Vermittlung eines wiederverwendbaren Workflows oder Verfahrens | „Wie man einen Pull-Request überprüft“ | | Tool-Beschreibung | Teilt dem Modell mit, was eine aufrufbare Funktion tut und wann sie genutzt wird | „Suche GitHub-Issues nach Suchbegriff“ | | System-Prompt | Legt das globale Verhalten und die Persönlichkeit des Assistenten fest | „Antworte präzise und überprüfe Fakten“ | | Projekt-Anweisungsdatei | Erklärt lokale Konventionen und Regeln des Repositories | „Nutze pnpm und führe den Build nicht manuell aus“ |

Laut den offiziellen APIs von OpenAI und den verschiedenen Agenten-SDKs sind Tools (Werkzeuge) eine Methode für Modelle, um Daten abzurufen, externe APIs aufzurufen, Code auszuführen oder mit der Außenwelt zu interagieren. Die SDK-Richtlinien empfehlen: Tool-Beschreibungen sollten kurz und präzise sein und erklären, was das Tool tut und wann es aufgerufen werden soll. Derselbe Grundsatz gilt für Markdown-Skills: Seien Sie explizit bei Aktivierung und Zweck.

Eine praktische SKILL.md-Struktur

Eine nützliche Skill-Datei sollte sechs Kernfragen beantworten:

  1. Welche Fähigkeit stellt dieser Skill bereit?
  2. Wann sollte der Agent ihn aktivieren?
  3. Wann sollte der Agent ihn keinesfalls aktivieren?
  4. Welchen konkreten Schritten muss der Agent folgen?
  5. Welche Dateien, Skripte oder Referenzen stehen zur Verfügung?
  6. Wie sollte das Endergebnis formatiert sein?

Hier ist eine bewährte Vorlage:

---
name: markdown-conversion-review
description: Nutze diesen Skill, wenn du in Markdown konvertierte Dokumente, PDFs, HTML- oder Office-Dateien überprüfen, bereinigen oder verbessern musst.
---

# Skill: Review konvertierter Markdown-Dateien

## Aktivierungsszenarien (Use This Skill When)
- Der Benutzer bittet darum, konvertiertes Markdown zu bereinigen oder zu verfeinern.
- Ein Dokument soll für die Verwendung in einer README, Dokumentation, einem Blog oder einem System-Prompt optimiert werden.
- Die Quelle enthält Tabellen, Überschriften, Links oder Codeblöcke, die repariert werden müssen.

## Ausschlusskriterien (Do Not Use This Skill When)
- Der Benutzer stellt lediglich eine allgemeine Frage zur Markdown-Syntax.
- Die Aufgabe erfordert das Bearbeiten von Quelldateien außerhalb des bereitgestellten Dokuments.

## Standard-Workflow (Workflow)
1. **Strukturanalyse**: Überprüfe das konvertierte Markdown auf fehlerhafte Hierarchien, beschädigte Tabellen, verloren gegangene Links und nicht geschlossene Codeblöcke.
2. **Inhaltsbewahrung**: Bewahre die ursprüngliche Absicht des Autors und die Reihenfolge des Textes, es sei denn, der Benutzer verlangt explizit ein Umschreiben.
3. **Formatierungsnormalisierung**: Verwende einfaches, standardisiertes Markdown, um Überschriften, Listen, Links und Tabellen zu vereinheitlichen.
4. **Fehlermarkierung**: Markiere Quellformatierungen, die nicht zuverlässig wiederhergestellt werden konnten, am Ende der Datei.
5. **Ergebnisbereitstellung**: Gib das bereinigte Markdown und eine kurze Änderungsnotiz an den Benutzer zurück.

## Qualitätskriterien & Einschränkungen (Quality Bar)
- Erfinde keine fehlenden Quellinhalte.
- Behalte Codeblöcke exakt bei, sofern keine Formatierungsanweisungen vorliegen.
- Bevorzuge sauberes Markdown gegenüber komplexem eingebettetem HTML.

## Erwartetes Ausgabeformat (Output Format)
Gib Folgendes zurück:
1. Das bereinigte Markdown.
2. Eine kurze Änderungsnotiz zu wichtigen Formatierungsentscheidungen.
3. Eine Liste ungelöster oder nicht wiederherstellbarer Formatierungsprobleme.

Die Frontmatter-Felder hängen vom jeweiligen Agenten-System ab. Der Aufbau des Dokuments (Aktivierung, Ausschluss, Workflow, Qualität, Ausgabeformat) ist jedoch universell portabel.

Wie man ein hervorragendes Beschreibungsfeld (Description) schreibt

Das Feld description in der Skill- oder Tool-Definition ist von entscheidender Bedeutung, da der Agent dieses Feld nutzt, um semantisch zu entscheiden, ob er diese Fähigkeit laden soll.

Schlechte Beschreibung:

description: Hilft bei Markdown-Problemen.

Gute Beschreibung:

description: Nutze diesen Skill, wenn der Benutzer konvertierte Markdown-Dokumente bereinigen, normalisieren oder für die Verwendung in Dokumentationen, READMEs, Blogs oder AI-Prompts vorbereiten möchte.

Die bessere Version enthält:

  • Den Auslöser: „wenn der Benutzer... möchte“
  • Die Aktion: „bereinigen, normalisieren oder vorbereiten“
  • Das Objekt: „konvertierte Markdown-Dokumente“
  • Die Zielumgebung: „Dokumentationen, READMEs, Blogs oder AI-Prompts“

Wie man Tool-Nutzungsbeschreibungen schreibt

Tool-Beschreibungen sollten kürzer sein als Skills. Ein Tool führt eine spezifische Operation aus, daher benötigt das Modell eine präzise Antwort auf drei Fragen:

  • Was tut das Tool?
  • Wann sollte es aufgerufen werden?
  • Welche Eingabeparameter benötigt es?

Beispiel in JSON:

{
  "name": "convert_file_to_markdown",
  "description": "Konvertiert eine hochgeladene PDF-, DOCX-, PPTX-, XLSX-, HTML- oder Bilddatei in Markdown, wenn der Benutzer editierbaren Text oder KI-bereite Dokumenteninhalte wünscht.",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "Die eindeutige ID der hochgeladenen Datei, die konvertiert werden soll."
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "Ob Tabellen nach Möglichkeit als Markdown-Tabellen erhalten bleiben sollen (Standard: true)."
      }
    },
    "required": ["file_id"]
  }
}

Die Beschreibung verzichtet auf vage Füllwörter und nennt stattdessen präzise die unterstützten Dateitypen, den Einsatzzweck und die Parameterdetails. Das reduziert Fehlaufrufe durch die KI erheblich.

Werkzeug-Dokumentation in Markdown

Es empfiehlt sich, die im Code definierten Tools zusätzlich in einer für die KI lesbaren Markdown-Datei zu beschreiben, um Verhaltensregeln festzulegen:

# Tool-Spezifikation: convert_file_to_markdown

## Zweck
Konvertiert unterstützte Dokumente in Markdown.

## Empfohlene Aktivierung
- Der Benutzer lädt eine Datei hoch und bittet direkt um die Konvertierung in Markdown.
- Der Dokumenteninhalt soll für ein LLM, eine README, eine Dokumentationsseite oder ein Blog-Dossier vorbereitet werden.

## Nicht aktivieren bei
- Der Benutzer stellt lediglich eine konzeptionelle Frage zu Markdown.
- Der Input ist bereits sauberes Markdown und erfordert keine Konvertierung.

## Eingaben
| Parameter | Typ | Erforderlich | Beschreibung / Hinweise |
|---|---|---:|---|
| file_id | string | Ja | Eindeutige ID der hochgeladenen Datei |
| preserve_tables | boolean | Nein | Tabellenstruktur erhalten, wenn möglich |

## Ausgabe
Das konvertierte Markdown sowie Konvertierungshinweise bei Fehlern.

## Fehlerbehandlung
- Bei nicht unterstützten Dateitypen wird eine Liste der erlaubten Formate ausgegeben.
- Wenn das Originallayout nicht erhalten werden kann, wird die beste reine Textextraktion geliefert und die Einschränkung vermerkt.

Dies ist besonders nützlich, wenn die Werkzeuge zwar im Programmcode definiert sind, der Agent jedoch zusätzliche Richtlinien benötigt, um Fehlentscheidungen zu vermeiden.

Was einen Skill für die KI wirklich nützlich macht

Ein guter Skill ist operational. Er hilft dem Agenten, während einer echten Aufgabe fundierte Entscheidungen zu treffen.

1. Präzise Aktivierungsregeln

Geben Sie genaue Auslöser anstelle von vagen Kategorien an.

Schlecht:

# SEO-Skill

Gut:

## Aktivierungsszenarien
- Der Benutzer verlangt die Optimierung einer Webseite für Suchmaschinen (SEO).
- Der Inhalt erfordert Anpassungen bei Meta-Titeln, Meta-Beschreibungen, Überschriften (H2/H3), internen Links oder FAQs.
- Der Benutzer erwähnt Richtlinien wie E-E-A-T oder die Optimierung für hilfreiche Inhalte (Helpful Content).

2. Klare Ausschlusskriterien (Non-Goals)

Richtlinien darüber, was der Agent nicht tun soll, sind oft genauso wichtig wie Arbeitsanweisungen. Sie verhindern, dass der Agent seine Kompetenzen überschreitet.

## Ausschlusskriterien
- Biete keine rechtliche, medizinische oder finanzielle Beratung an.
- Erfinde keine gefälschten Kundenrezensionen, Statistiken, Referenzen oder Erfolgszahlen.
- Bearbeite keine Seiten, deren Inhalt nicht im Bezug zum Produkt oder den Benutzerabsichten steht.

3. Konkrete Workflow-Schritte

Stellen Sie einen schrittweisen Ablauf bereit, dem der Agent auch bei komplexen Aufgaben folgen kann. Formulieren Sie die Schritte konkret genug, um das Verhalten zu steuern, aber lassen Sie genügend Raum für Flexibilität.

4. Beispiele für gute und schlechte Ergebnisse

In der KI-Instruktion gilt: Ein konkretes Textbeispiel sagt mehr als tausend abstrakte Adjektive.

## Beispiel für den Formulierungston

- **Zu vermeiden (schlecht)**:
  „Unser revolutionärer Konverter garantiert makellose Ergebnisse für jedes Dokument.“
  *(Grund: Klingt übertrieben werblich und unaufrichtig.)*

- **Zu bevorzugen (gut)**:
  „Das Tool extrahiert Textinhalte in Markdown. Es erzielt die besten Ergebnisse, wenn die Quelldatei klare Überschriften, Listen und Tabellen aufweist.“
  *(Grund: Ehrlich, sachlich und beschreibt sowohl Mehrwert als auch Grenzen.)*

5. Sicherheitsregeln und Berechtigungsgrenzen

Wenn Ihr Skill die Ausführung von Skripten oder das Ändern von Dateien im System erlaubt, legen Sie Sicherheitsgrenzen fest:

## Sicherheitsregeln & Berechtigungen
- Lese Dateien vollständig, bevor du sie bearbeitest.
- Lösche niemals Benutzerdateien, ohne vorher eine explizite Bestätigung einzuholen.
- Bitte um Erlaubnis, bevor du Daten an externe APIs sendest.

Häufige Fehler bei der Skill-Erstellung

  • Fehler 1: Zu viele Aufgaben in einen Skill packen: Ein Skill sollte sich auf eine einzige, kohärente Aufgabe konzentrieren. Ein allgemeiner „Marketing-Skill“, der SEO, Analyse, Copywriting, Anzeigenrichtlinien und E-Mail-Kampagnen umfasst, überfordert den Agenten.
  • Fehler 2: Vage, nicht messbare Adjektive nutzen: Vermeiden Sie Anweisungen wie „schreibe erstklassigen Code“ oder „mache den Text ansprechend“. Formulieren Sie stattdessen überprüfbare Kriterien wie „füge Quelllinks für Behauptungen hinzu“, „schränke die Länge auf 150 Wörter ein“.
  • Fehler 3: Wichtige Regeln im Fließtext verstecken: Nutzen Sie Listen. Regeln in langen Absätzen werden von Modellen (und Menschen) leicht übersehen.
  • Fehler 4: Fehlendes Error-Handling: Werkzeuge fallen aus, Netzwerke hängen. Geben Sie dem Agenten immer eine Anweisung für den Fehlerfall mit auf den Weg (z. B. „biete bei Verbindungsfehlern einen lokalen Fallback an“).

Fazit

Markdown-basierte SKILL.md-Dateien und präzise Tool-Beschreibungen sind der beste Weg, um das Verhalten von KI-Agenten zu steuern, ohne sie in starre Schablonen zu pressen. Sie definieren, wann eine Fähigkeit greift, wie sie ausgeführt wird und wo die Grenzen liegen.

Wenn Sie KI-Workflows für Dokumentenkonvertierung, Wissensdatenbanken oder Codierungsaufgaben entwickeln, sind gut gepflegte SKILL.md-Dateien die stabilste Brücke zwischen Ihren Prozessen und der zuverlässigen Ausführung durch den Agenten.

Quellen und weiterführende Literatur