SKILL.md-Validator: Frontmatter und Format prüfen

Eine SKILL.md-Datei ist das Herzstück jeder Agenten-Fähigkeit im Agent Skills-Ökosystem. Sie besteht aus zwei Teilen: einem YAML-frontmatter oben und einer Markdown-Anleitung darunter. Der Agent liest zunächst nur den Namen und die Beschreibung aus dem frontmatter. Diese entscheiden, ob die Fähigkeit überhaupt in Betracht gezogen wird. Erst wenn der Agent die Fähigkeit auswählt, wird der Markdown-Teil geladen und ausgeführt.

Stellen Sie sich das wie ein Buchcover und den Klappentext vor: Ohne ansprechende Aufmachung wird niemand das Buch öffnen. Bei SKILL.md ist der Name der Titel und die Beschreibung der Klappentext. Der eigentliche Inhalt (die Anleitung) kommt erst zum Einsatz, wenn der Agent die Fähigkeit tatsächlich nutzen möchte.

Die Datei liegt in einem Ordner, der idealerweise denselben Namen trägt wie die Fähigkeit selbst (z. B. rechnung-validieren für eine Fähigkeit namens rechnung-validieren). Im selben Ordner können weitere Dateien wie Vorlagen, Beispiele oder Referenzdokumente liegen, auf die die SKILL.md verweist. Wichtig ist, dass alle Verweise relativ sind. Absolute Pfade oder tiefe Verschachtelungen führen zu Warnungen im SKILL.md-Prüfer, da sie die Portabilität der Fähigkeit einschränken.

Typische Anwendungsfälle für SKILL.md-Dateien sind etwa die Automatisierung von Geschäftsprozessen (z. B. Rechnungsprüfung nach deutschen GoBD-Richtlinien), die Extraktion von Daten aus PDFs oder die Generierung von Texten nach unternehmensspezifischen Vorgaben. Da die Fähigkeiten oft sensible Workflows abbilden, ist es ein großer Vorteil, dass der SKILL.md-Prüfer lokal im Browser arbeitet: Nichts wird hochgeladen oder extern gespeichert.

Der YAML-frontmatter einer SKILL.md-Datei muss bestimmte Regeln einhalten, damit die Fähigkeit vom Agenten korrekt erkannt wird. Der SKILL.md-Prüfer überprüft diese Regeln und zeigt Fehler, Warnungen oder Hinweise an. Hier die wichtigsten Felder im Überblick:

Ein häufiger Fehler ist ein name, der zu lang ist oder Sonderzeichen enthält. Beispiel: rechnung-prüfen-2024 ist gültig, RechnungPrüfen! dagegen nicht. Die description sollte nicht nur beschreiben, was die Fähigkeit tut, sondern auch, wann sie sinnvoll ist, etwa: „Validiert Rechnungen nach GoBD und prüft auf formale Fehler wie fehlende Steuernummern oder falsche IBANs.“ statt „Ein Tool zur Rechnungsprüfung.“

Der SKILL.md-Prüfer warnt auch bei unbekannten Feldern im frontmatter. Diese sollten stattdessen unter metadata platziert werden, um die Kompatibilität mit verschiedenen Agenten zu gewährleisten. Claude Code erkennt beispielsweise zusätzliche Felder wie model oder hooks, andere Agenten ignorieren sie jedoch. Wer seine Fähigkeit portabel halten möchte, sollte solche Erweiterungen vermeiden oder klar kennzeichnen.

Die description in der SKILL.md-Datei ist der wichtigste Faktor dafür, ob ein Agent Ihre Fähigkeit überhaupt in Betracht zieht. Sie ist das Erste, was der Agent liest, und oft das Einzige, bevor er entscheidet, ob die Fähigkeit zur aktuellen Aufgabe passt. Eine vage oder zu kurze Beschreibung führt dazu, dass die Fähigkeit ignoriert wird, selbst wenn sie technisch einwandfrei funktioniert.

Der SKILL.md-Prüfer warnt, wenn die Beschreibung kürzer als 60 Zeichen ist. Das ist kein hartes Limit, aber eine Empfehlung: Kürzere Beschreibungen enthalten oft zu wenig Kontext. Beispiel für eine schwache Beschreibung: „Ein Tool zur Datenanalyse.“ Besser: „Analysiert Verkaufsdaten nach Regionen und Produktgruppen, um Trends und Ausreißer zu identifizieren, ideal für monatliche Berichte.“

Besonders wichtig ist die „Wann-nutzen“-Komponente. Viele Fähigkeiten scheitern daran, dass sie zwar beschreiben, was sie tun, aber nicht, in welchen Situationen sie sinnvoll sind. Ein gutes Muster ist: „[Was die Fähigkeit tut], wenn [Bedingung oder Anwendungsfall].“ Beispiel: „Extrahiert Kontaktdaten aus E-Mails und speichert sie im CRM, wenn eine neue Kundenanfrage eingeht.“

In deutschen Kontexten lohnt es sich, branchenspezifische Begriffe einzubauen. Eine Fähigkeit zur Rechnungsprüfung könnte etwa schreiben: „Validiert Rechnungen nach GoBD und prüft auf formale Fehler wie fehlende Steuernummern, falsche IBANs oder unplausible Beträge, besonders nützlich für Steuerberater und Buchhaltungsabteilungen.“ So wird klar, für wen die Fähigkeit gedacht ist und in welchen Szenarien sie hilft.

Der SKILL.md-Prüfer gibt auch Hinweise, wenn die Beschreibung Platzhalter wie TODO oder Lorem ipsum enthält. Solche Einträge sollten vor der Veröffentlichung entfernt werden, da sie die Fähigkeit unbrauchbar machen.

Die Agent Skills-Spezifikation empfiehlt, den Markdown-Teil einer SKILL.md-Datei auf etwa 500 Zeilen und 5.000 Token zu beschränken. Der SKILL.md-Prüfer warnt, wenn diese Grenzen überschritten werden, und gibt eine Schätzung der Token-Anzahl aus, basierend auf der Annahme, dass ein Token etwa 4 Zeichen entspricht.

Diese Limits sind keine harten Fehler, aber sie haben praktische Gründe: Lange Fähigkeiten sind schwerer zu warten, langsamer zu laden und verbrauchen mehr Ressourcen. Besonders bei Agenten, die in Echtzeit arbeiten, kann eine zu große SKILL.md die Antwortzeiten verlängern. Zudem neigen lange Anleitungen dazu, unübersichtlich zu werden, sowohl für den Entwickler als auch für den Agenten, der sie ausführt.

Ein häufiges Problem sind Fähigkeiten, die zu viele Details direkt in der SKILL.md unterbringen. Beispiel: Eine Fähigkeit zur Erstellung von Steuererklärungen könnte versucht sein, alle relevanten Paragrafen und Formeln in die Anleitung zu packen. Besser ist es, solche Informationen in separate Dateien im references/-Ordner auszulagern und in der SKILL.md nur die wichtigsten Schritte zu beschreiben. So bleibt die Datei schlank und die Fähigkeit portabel.

Der SKILL.md-Prüfer schätzt die Token-Anzahl anhand der Zeichen, was für deutsche Texte meist ausreichend genau ist. Bei Sprachen mit vielen Sonderzeichen (z. B. Umlaute) oder nicht-lateinischen Schriften (z. B. Chinesisch) kann die tatsächliche Token-Anzahl jedoch abweichen. Die Schätzung dient daher nur als Richtwert. Im Zweifel sollte man die Fähigkeit mit dem tatsächlichen Tokenizer des Ziel-Agenten testen.

Ein weiterer Tipp: Nutzen Sie Markdown-Überschriften, um die Anleitung zu strukturieren. Das hilft nicht nur dem Entwickler, sondern auch dem Agenten, der die Fähigkeit ausführt. Beispiel:

## Eingabedaten
- Rechnungen im PDF- oder CSV-Format
- Mindestens die Felder *Datum*, *Betrag* und *Steuernummer* erforderlich

## Ausgabedaten
- Validierte Rechnungen als JSON
- Fehlermeldungen bei formalen Fehlern

So bleibt die Anleitung übersichtlich und die Fähigkeit bleibt innerhalb der empfohlenen Grenzen.

Nicht alle Felder in einer SKILL.md-Datei werden von jedem Agenten gleich behandelt. Der offizielle Agent Skills-Standard definiert nur eine Handvoll Pflicht- und optionale Felder. Alles andere sind Erweiterungen, die nur von bestimmten Agenten wie Claude Code unterstützt werden. Der SKILL.md-Prüfer unterscheidet zwischen diesen Kategorien und gibt Hinweise, wenn Felder verwendet werden, die nicht zum Standard gehören.

Zu den offiziellen Feldern gehören name, description, compatibility, license und metadata. Diese werden von allen Agenten gelesen, die die Agent Skills-Spezifikation unterstützen. Claude Code erkennt zusätzlich Felder wie model, hooks oder allowed-tools, die jedoch von anderen Agenten ignoriert werden. Wer seine Fähigkeit portabel halten möchte, sollte solche Erweiterungen vermeiden oder sie unter metadata platzieren, wo sie keinen Einfluss auf die Kompatibilität haben.

Ein besonderer Fall ist das Feld allowed-tools. Im offiziellen Standard ist es als experimentell gekennzeichnet und sollte als durch Leerzeichen getrennte Liste von Werkzeugen angegeben werden (z. B. allowed-tools: python curl). Der SKILL.md-Prüfer warnt, wenn das Feld als YAML-Liste formatiert ist, da dies nicht mit allen Agenten kompatibel ist.

Für deutsche Entwickler ist es besonders wichtig, auf die Portabilität zu achten, wenn sie Fähigkeiten für internationale Teams oder Marktplätze erstellen. Beispiel: Eine Fähigkeit zur Validierung von Rechnungen nach deutschen GoBD-Richtlinien sollte nicht von Claude Code-spezifischen Feldern abhängen, wenn sie auch in anderen Agenten-Umgebungen genutzt werden soll.

Der SKILL.md-Prüfer gibt auch Hinweise zu Feldern, die nur von Claude Code gelesen werden. Dazu gehören etwa model (zur Auswahl des Sprachmodells) oder hooks (für Vor- und Nachverarbeitung). Diese Felder sind nützlich, wenn die Fähigkeit ausschließlich für Claude Code entwickelt wird, sollten aber vermieden werden, wenn sie auch in anderen Umgebungen laufen soll.

Ein guter Kompromiss ist es, solche Erweiterungen unter metadata zu platzieren:

metadata:
  claude-code:
    model: haiku
    hooks:
      pre: validate_input.py

So bleibt die Fähigkeit portabel, während die Erweiterungen für Claude Code trotzdem nutzbar sind.

Der SKILL.md-Prüfer liefert einen detaillierten Bericht mit drei Kategorien von Meldungen: Fehlern, Warnungen und Hinweisen. Nur wenn keine Fehler vorliegen, gilt die SKILL.md-Datei als gültig. Warnungen und Hinweise sind Empfehlungen, die die Funktionalität nicht beeinträchtigen, aber die Qualität oder Portabilität verbessern können.

Fehler sind harte Verstöße gegen die Agent Skills-Spezifikation. Dazu gehören: - Fehlendes oder ungültiges YAML-frontmatter (z. B. falsche Einrückung, fehlende Anführungszeichen) - Fehlende Pflichtfelder (name oder description) - Ungültige Werte (z. B. ein name mit Großbuchstaben oder Sonderzeichen) - Überschrittene Längenlimits (z. B. eine description mit mehr als 1.024 Zeichen)

Warnungen weisen auf potenzielle Probleme hin, die die Nutzung der Fähigkeit erschweren könnten: - Eine zu kurze description (unter 60 Zeichen) - Unbekannte Felder im frontmatter (sollten unter metadata platziert werden) - Absolute oder tief verschachtelte Dateipfade - Platzhalter wie TODO oder Lorem ipsum - Ein zu langer Markdown-Teil (über 500 Zeilen oder 5.000 Token)

Hinweise geben zusätzliche Informationen, die für bestimmte Agenten relevant sein könnten: - Felder, die nur von Claude Code gelesen werden (z. B. model oder hooks) - Experimentelle Felder wie allowed-tools - Fehlende „Wann-nutzen“-Formulierung in der description

Der Bericht enthält außerdem Statistiken zur Datei, wie die Anzahl der Zeilen, Zeichen und die geschätzte Token-Anzahl. Diese helfen einzuschätzen, ob die Fähigkeit innerhalb der empfohlenen Grenzen liegt.

Ein wichtiger Hinweis: Der SKILL.md-Prüfer überprüft nur die Formatierung und Struktur der Datei, nicht, ob die verlinkten Dateien tatsächlich existieren oder ob die Anleitung inhaltlich sinnvoll ist. Eine gültige SKILL.md kann also trotzdem fehlerhaft sein, wenn z. B. eine Referenzdatei fehlt oder die Anleitung falsche Befehle enthält.

Für die Weiterverarbeitung bietet der Prüfer die Möglichkeit, den Bericht als CSV oder Bild zu exportieren. Das ist besonders nützlich, wenn man mehrere Fähigkeiten prüfen oder die Ergebnisse mit Kollegen teilen möchte. Da alles lokal im Browser passiert, bleiben die Daten privat. Das ist ein großer Vorteil, wenn die Fähigkeiten sensible Workflows enthalten.

Wenn eine Fähigkeit vom Agenten nicht geladen wird, liegt das in den meisten Fällen an einem der folgenden Probleme, und der SKILL.md-Prüfer hilft, sie zu identifizieren.

1. Die Beschreibung ist zu vage oder zu kurz Das häufigste Problem ist eine description, die nicht klar macht, wann die Fähigkeit eingesetzt werden soll. Beispiel: „Ein Tool zur Datenverarbeitung.“ sagt dem Agenten nicht, ob die Fähigkeit für Rechnungen, Kundenlisten oder Steuererklärungen gedacht ist. Besser: „Validiert Rechnungen nach GoBD und prüft auf formale Fehler wie fehlende Steuernummern oder falsche IBANs, ideal für Buchhaltungsabteilungen.“ Der SKILL.md-Prüfer warnt, wenn die Beschreibung kürzer als 60 Zeichen ist oder keine „Wann-nutzen“-Formulierung enthält.

2. Der Name enthält ungültige Zeichen Der name darf nur Kleinbuchstaben, Ziffern und einzelne Bindestriche enthalten. Ungültige Beispiele: RechnungPrüfen, rechnung_prüfen oder rechnung-prüfen-2024. Gültig wäre rechnung-pruefen. Der SKILL.md-Prüfer zeigt einen Fehler an, wenn der Name gegen diese Regeln verstößt.

3. Das YAML-frontmatter ist fehlerhaft Häufige Ursachen sind: - Fehlende oder falsche Einrückung (YAML erfordert Leerzeichen, keine Tabs) - Ungequotete Sonderzeichen (z. B. description: Prüft Rechnungen (GoBD-konform); die Klammern müssen in Anführungszeichen stehen) - Fehlende Pflichtfelder (name oder description)

4. Die Fähigkeit ist zu groß Wenn der Markdown-Teil über 500 Zeilen oder 5.000 Token umfasst, warnt der SKILL.md-Prüfer. Lange Fähigkeiten sind schwerer zu warten und können die Performance des Agenten beeinträchtigen. Lösung: Details in separate Dateien im references/-Ordner auslagern und in der SKILL.md nur die wichtigsten Schritte beschreiben.

5. Absolute Pfade oder tiefe Verschachtelungen Verweise auf Dateien sollten relativ und nicht tiefer als eine Ebene verschachtelt sein. Beispiel: references/vorlage.pdf ist gültig, ../../daten/vorlage.pdf oder C:\Dokumente\vorlage.pdf führen zu Warnungen.

6. Unbekannte Felder im frontmatter Felder wie model oder hooks werden nur von Claude Code gelesen. Andere Agenten ignorieren sie oder brechen ab, wenn sie nicht unter metadata platziert sind. Der SKILL.md-Prüfer gibt einen Hinweis, wenn solche Felder außerhalb von metadata stehen.

Falls die Fähigkeit trotz gültiger SKILL.md nicht geladen wird, lohnt sich ein Blick auf die compatibility-Angabe. Manche Agenten erwarten hier spezifische Werte (z. B. compatibility: claude-code-3.5). Der SKILL.md-Prüfer überprüft zwar nicht, ob die Angabe korrekt ist, aber er warnt, wenn das Feld zu lang ist (500 Zeichen).

Ein letzter Tipp: Nutzen Sie den JSON-zu-YAML-Konverter, um sicherzustellen, dass das frontmatter korrekt formatiert ist. Besonders bei komplexen Fähigkeiten kann es helfen, die YAML-Struktur zunächst in JSON zu schreiben und dann umzuwandeln.