Eine technische Analyse des SKILL.md Frontmatters

Dies ist eine technische Referenz für den Frontmatter-Block innerhalb einer Claude SKILL.md-Datei. Ihr Zweck ist es, jedes Feld und seine Auswirkung auf das Skill-Verhalten zu erklären, insbesondere wie es ausgelöst wird. Die hier enthaltenen Informationen sind nicht theoretisch; sie basieren auf unserer direkten Erfahrung beim Parsen, Installieren und Testen von 743 einzigartigen Skills, die bei SkillProof eingereicht wurden. Unsere Methodik beinhaltet das Ausführen jedes Skills gegen einen standardisierten Satz realer Programmieraufgaben, und ein wesentlicher Teil dieses Prozesses ist zunächst das Verständnis der Absicht des Autors, wie sie in der SKILL.md deklariert ist.

Wir haben festgestellt, dass dieser kleine YAML-Block der kritischste und oft missverstandene Teil der Definition eines Skills ist. Ein falsch konfiguriertes Frontmatter kann einen Skill stillschweigend deaktivieren und einen Autor dazu verleiten, sein Skript zu debuggen, obwohl das Problem in den Metadaten liegt. Dieser Leitfaden dokumentiert, was jedes Feld bewirkt, wie sie interagieren und welche Konfigurationen vermieden werden sollten.

Der SKILL.md Frontmatter-Block

Jede SKILL.md-Datei beginnt mit einem YAML-Frontmatter-Block, der durch --- begrenzt ist. Dies ist eine Standardkonvention in vielen statischen Website-Generatoren und Dokumentationstools, aber im Kontext eines Claude Skills ist es nicht nur für den menschlichen Verbrauch gedacht. Das Modell parst diesen Block, um die Identität, Fähigkeiten und Einschränkungen des Skills zu verstehen.

Dieser YAML-Abschnitt des Claude Skills ist die Steuerzentrale für Ihren Skill. Das Basismodell verwendet diese Daten, um zu entscheiden, ob, wann und wie die von Ihnen bereitgestellten Tools ausgeführt werden sollen. Es als bloße Informationskommentare zu betrachten, ist der erste Fehler.

Ein minimaler Frontmatter-Block sieht so aus:

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

Wir werden jedes dieser Felder sowie die kritischen Aufrufsteuerungs-Flags untersuchen, basierend auf Mustern, die in den über 700 von uns analysierten Dateien beobachtet wurden.

Kernidentität: name und description

Diese beiden Felder definieren, was der Skill sowohl für den Benutzer als auch für das Modell ist. Sie haben jedoch sehr unterschiedliche Rollen bei der Auslösung des Skills.

name

Das Feld name ist eine eindeutige Zeichenfolge, die den Skill identifiziert. Es wird für den expliziten Aufruf verwendet, wenn ein Benutzer @ gefolgt vom Skill-Namen eingibt. Zum Beispiel @example-skill. Der Name muss eine einzelne, nicht-leerzeichenhaltige Zeichenfolge sein. Konventionell ist er kleingeschrieben und verwendet Kebab-Case.

Obwohl wichtig für die Identifikation und direkte Benutzeraufrufe, hat der name kaum oder keinen Einfluss auf die autonome Entscheidung des Modells, den Skill zu verwenden. Das Modell leitet keine Fähigkeiten vom Namen git-history-analyzer ab. Dafür verlässt es sich auf die description.

description

Dies ist das wichtigste Feld im gesamten SKILL.md-Frontmatter. Die description ist kein Kommentar. Sie ist der primäre Anweisungssatz, der dem Modell mitteilt, wann Ihr Skill das geeignete Werkzeug für eine bestimmte Aufgabe ist. Sie ist die API-Dokumentation für das Modell selbst.

In unseren Tests ist die Qualität der description die Variable mit der höchsten Korrelation zum Erfolgsscore eines Skills. Vage Beschreibungen führen zu inkonsistentem Auslösen, falscher Tool-Nutzung oder dazu, dass der Skill vollständig ignoriert wird. Dies ist eine häufige Ursache, wenn ein Claude Skill nicht wie erwartet ausgelöst wird.

Eine schlechte description: "Analyzes code."

Dies ist nutzlos. Es liefert keine Informationen darüber, welche Art von Analyse, welche Eingaben es erwartet oder welche Ausgaben es produziert. Das Modell hat keinen Grund, diesen Skill gegenüber seinen eigenen internen Fähigkeiten zu bevorzugen.

Eine funktionale description: "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

Dies ist effektiv, weil es präzise und handlungsorientiert ist:

1. Eingaben: Es wird klar angegeben, dass es einen Dateipfad als Eingabe akzeptiert.
2. Aktionen: Es wird spezifiziert, was es tut (liest die Datei, berechnet die zyklomatische Komplexität).
3. Tools: Es deutet sogar das Tool an, das es verwenden wird (py-complexity).
4. Ausgaben: Es definiert das erwartete Rückgabeformat (eine Liste von Funktionen und deren Komplexitätswerten).

Wenn dem Modell eine Aufgabe wie "Können Sie die Komplexität der Funktionen in main.py überprüfen?" gestellt wird, kann es diese Anfrage direkt den im zweiten description dargelegten Fähigkeiten zuordnen. Die erste description würde ignoriert werden.

Wenn Sie Ihren eigenen Claude Skill schreiben, verbringen Sie die meiste Zeit damit, die description zu verfeinern. Schreiben Sie sie so, als würden Sie eine Funktion für einen anderen Ingenieur dokumentieren, denn genau das tun Sie.

Tool-Berechtigungen: allowed-tools

Das Feld allowed-tools ist eine Liste von ausführbaren Programmen, die der Skill aufrufen darf. Dies fungiert als Sicherheitssandbox. Das Modell kann unter keinen Umständen ein Tool aufrufen, das nicht explizit in diesem Array aufgeführt ist.

allowed-tools: [python, bash, jq]

Dies ist eine kritische Sicherheits- und Zuverlässigkeitsfunktion. Sie verhindert, dass ein Skill beliebigen Code ausführt und definiert klar seinen operativen Umfang. Während unserer Tests überprüfen wir, ob die aufgelisteten Tools für den angegebenen Zweck des Skills geeignet sind. Ein Skill, der vorgibt, ein einfacher JSON-Formatter zu sein, aber bash in allowed-tools auflistet, ist ein Warnsignal. Obwohl er bash verwenden könnte, um an jq weiterzuleiten, gewährt er dem Skill auch die Fähigkeit, beliebige Shell-Befehle auszuführen, was eine unnötige Erweiterung der Privilegien darstellt.

Wir haben Skills scheitern sehen, weil sie versucht haben, ein nicht gelistetes Tool aufzurufen. Umgekehrt haben wir Skills markiert, die übermäßig breite Berechtigungen anfordern, die durch ihre description oder Implementierung nicht gerechtfertigt sind. Das Prinzip der geringsten Privilegien gilt: Erlauben Sie nur die exakten Tools, die für die Funktion des Skills notwendig sind.

Aufrufsteuerung: user-invocable und disable-model-invocation

Diese beiden booleschen Flags sind seltener, haben aber einen tiefgreifenden Einfluss auf das Skill-Verhalten. Sie steuern die Quelle des Aufrufs: Kann ein Benutzer den Skill explizit aufrufen, und kann das Modell selbst entscheiden, ihn zu verwenden? Der Standardwert für beide ist false, wenn sie weggelassen werden, aber das effektive Standardverhalten eines Standard-Skills geht von user-invocable: true und disable-model-invocation: false aus.

Ihre Interaktion kann verwirrend sein, daher hier eine Zusammenfassungstabelle:

user-invocable	disable-model-invocation	Verhalten	SkillProof Urteil
true (oder weggelassen)	false (oder weggelassen)	Standard: Benutzer kann @ erwähnen; Modell kann autonom aufrufen.	Die erwartete Konfiguration für die meisten Skills.
false	false (oder weggelassen)	Nur autonom: Benutzer kann nicht @ erwähnen; Modell kann aufrufen.	Für Hintergrundaufgaben oder Hilfsfunktionen.
true	true	Nur explizit: Benutzer muss @ erwähnen; Modell kann nicht aufrufen.	Für Tools mit Nebenwirkungen oder hohen Kosten.
false	true	Deaktiviert: Weder Benutzer noch Modell können aufrufen.	Fehlerhafte Konfiguration. Wir markieren diese.

user-invocable

Dieses Flag bestimmt, ob ein Benutzer den Skill direkt über eine @-Erwähnung auslösen kann. Der Standardwert, true, ist das Verhalten, das die meisten Benutzer erwarten. Ein user-invocable claude skill ist einer, den Sie bei Bedarf aufrufen können.

Das Setzen von user-invocable: false bedeutet, dass der Skill nur durch den autonomen Entscheidungsprozess des Modells ausgelöst werden kann. Der Benutzer kann ihn nicht zur Ausführung zwingen. Dies ist eine gültige Wahl für Skills, die als Hintergrundhelfer oder Teil einer größeren Toolkette fungieren, kann aber eine große Quelle der Verwirrung sein. Wir haben mehrere Skills getestet, bei denen dieses Flag auf false gesetzt war, ohne dass dies in der Dokumentation vermerkt war. Benutzer, die versucht haben, den Skill mit @ zu erwähnen, sahen keine Reaktion und nahmen an, dass er defekt war. Wenn Sie dies auf false setzen, müssen Sie es klar dokumentieren.

disable-model-invocation

Dieses Flag ist das Gegenteil von user-invocable. Es bestimmt, ob das Modell den Skill proaktiv selbst auswählen darf.

Der Standardwert, false, erlaubt dem Modell, den Skill zu verwenden, wann immer seine description der Anfrage des Benutzers entspricht.

Das Setzen von disable-model-invocation: true verbietet dem Modell, den Skill autonom zu verwenden. Der Skill kann nur ausgeführt werden, wenn user-invocable ebenfalls true ist und der Benutzer ihn explizit mit @ erwähnt. Dies ist nützlich für Tools, die teuer sind, erhebliche Nebenwirkungen haben (wie das Stellen einer Netzwerkanfrage oder das Ändern von Dateien) oder sehr spezifische Eingaben erfordern, die das Modell möglicherweise nicht korrekt selbst ableiten kann.

Die Kombination des stillen Scheiterns

Die problematischste Konfiguration, die wir in unseren Tests entdeckt haben, ist die Kombination von user-invocable: false und disable-model-invocation: true. Wie die Tabelle zeigt, kann ein so konfigurierter Skill auf keine Weise ausgelöst werden. Der Benutzer ist daran gehindert, ihn aufzurufen, und dem Modell ist es verboten, ihn auszuwählen.

Bei unserer Überprüfung von über 700 SKILL.md-Dateien haben wir Skills mit genau dieser Konfiguration gefunden. Aus der Sicht des Benutzers ist der Skill installiert, aber völlig funktionsunfähig. Es ist effektiv toter Code. In jedem Fall reihen wir diese Skills zur manuellen Inspektion ein. Manchmal ist es ein Fehler des Autors. Andere Male scheint es eine Möglichkeit zu sein, einen Skill in einem Repository vorübergehend zu deaktivieren, ohne ihn zu löschen. Unabhängig vom Grund ist das Ausliefern eines Skills mit dieser Konfiguration ein Fehler.

Praktische Implikationen aus 743 Skill-Tests

Das Verständnis des Claude Skill Frontmatters ist keine akademische Übung. Es ist der Schlüssel zum Aufbau zuverlässiger und effektiver Skills. Unsere Tests von 743 Skills haben einige wichtige Wahrheiten bestätigt:

1. Die description ist der Auslöser. Zeit, die für ihre Verfeinerung aufgewendet wird, ist niemals verschwendet.
2. Standardwerte sind normalerweise korrekt. Die meisten Skills sollten user-invocable und model-invocable sein.
3. Abweichungen müssen bewusst und dokumentiert sein. Wenn Sie einen Skill nur autonom oder nur explizit machen, müssen Ihre Benutzer wissen, warum.

Deshalb existiert SkillProof. Von den 743 von uns verarbeiteten Skills schnitten 31 tatsächlich schlechter ab als die Verwendung von reinem Claude. Viele dieser Fehler waren nicht auf schlechten Code zurückzuführen, sondern auf ein schlecht konstruiertes SKILL.md-Frontmatter, das dazu führte, dass der Skill zur falschen Zeit oder überhaupt nicht ausgelöst wurde. Weitere 204 Skills bestanden unsere Tests, erforderten jedoch eine nicht-triviale Einrichtung, oft im Zusammenhang mit dem Verständnis, wie die Aufruf-Flags gesetzt wurden. Wir veröffentlichen diese Ergebnisse – die Erfolge und die Misserfolge –, weil der wahre Wert eines Skills durch seine reale Leistung bestimmt wird, nicht nur durch seinen Code.

Skills zu finden, die dies richtig machen, ist der Zweck unseres Verzeichnisses. Ein gut konfigurierter Skill wie ein Codebase Summarizer wird eine präzise Beschreibung und sinnvolle Aufruf-Einstellungen haben, die es ihm ermöglichen, als zuverlässige Erweiterung des Modells zu funktionieren.

Sie können alle 508 Skills, die unsere Tests bestanden haben, in unserem Katalog durchsuchen. Jede Auflistung enthält das exakte verwendete SKILL.md-Frontmatter und unser Urteil über seine Wirksamkeit. Überzeugen Sie sich selbst, wie ein gut konfigurierter, praxiserprobter Skill aussieht.