Was ist eine Skill-Datei für KI? Aufbau, Indizes und Sicherheitsprüfungen

Stellen Sie sich eine sehr fähige Person vor, die nichts über Sie weiß. Sie geben ihr eine kurze Aufgabe ohne Hintergrund, ohne Zweck, ohne Einschränkungen und ohne Vorstellung davon, wie ein gutes Ergebnis aussieht, und erwarten dann, dass das Resultat jedes Mal Ihrem Bild entspricht. Das würde nicht funktionieren.

Agenten haben dasselbe Problem. Eine kurze Anweisung kann ein gültiges Ergebnis liefern, das trotzdem am Gewünschten vorbeigeht. Führen Sie sie erneut aus oder geben Sie sie einem anderen Agenten, und Stil oder Vorgehen können sich ändern, weil die Anweisung Entscheidungen offenlässt, die die KI an Ihrer Stelle trifft. Skill-Dateien schaffen hier Abhilfe.

Ein Skill ist mehr als ein langer Prompt

Ein Skill ist ein wiederverwendbares Bündel aus Kontext und Arbeitsanweisungen. Er sagt einem Agenten, was das Ziel der Aufgabe ist, welchem Ablauf er folgen soll, welche Informationen und Dateien wichtig sind, wie eine gute Ausgabe aussieht, wo die Grenzen seines Handelns liegen und wie er vorgeht, wenn etwas fehlt.

Ein Prompt ist meist ein Befehl für den Moment. Ein Skill trägt die festen Gewohnheiten für eine ganze Art von Arbeit. Er macht das Modell nicht klüger, aber er reduziert unnötiges Raten und gibt der Arbeit eine stabilere Richtung.

Der Vergleich mit dem Restaurant

Angenommen, Sie möchten japanisch essen, sagen dem Koch aber nur: "Nimm Reis und Fleisch, verwende diese Zutaten, und es soll gut schmecken." Falsch ist die Bitte nicht, und der Koch kann etwas Köstliches zubereiten. Aber „köstlich“ lässt einen riesigen Spielraum, und Sie könnten ein thailändisches, koreanisches, indisches oder europäisches Gericht bekommen.

Selbst der Wunsch nach italienischer Küche lässt vieles offen. Sie könnten authentische Pasta al dente bekommen oder eine Fusion-Pizza mit Ananas. Manche lieben Letzteres, andere sind entschieden dagegen, doch beides erfüllt die allgemeine Bitte.

KI verhält sich genauso. Lässt eine Anweisung eine Lücke, wählt das System einen plausiblen Weg, und der kann vernünftig sein, ohne der gemeinte zu sein. Lesen Sie einen Skill deshalb noch einmal, bevor Sie ihn einem Agenten geben, und fragen Sie:

Ließe sich die Aufgabe allein mit diesem Text erledigen? Welche Details wären immer noch Raterei? Und wo eine Entscheidung unvermeidlich ist, ist die Richtung klar?

Diese kurze Durchsicht bringt erstaunlich viele Schwächen ans Licht.

Was in eine Skill-Datei gehört

Der beste Skill ist nicht unbedingt der längste. Er liefert, was nötig ist, um die richtigen Entscheidungen zu treffen. Ein praxistauglicher Skill hat meist diese Teile.

1. Metadaten dazu, wann der Skill greift

Name und Beschreibung sollten klar machen, welche Aufgaben den Skill auslösen sollen und welche nicht. Manche Implementierungen von Agent Skills nutzen Metadaten wie name und description, um zu entscheiden, ob die vollständigen Anweisungen geladen werden, eine Form von Progressive Disclosure. Erkennung, Auswahl und Laden hängen trotzdem vom Modell, der Agenten-Laufzeitumgebung und den verfügbaren Werkzeugen ab.

Achten Sie darauf, dass die Beschreibung nicht so breit ist, dass der Skill jede Aufgabe für sich beansprucht, und nicht so eng, dass der Agent ihn für passende Arbeit nie findet.

2. Ziel und Umfang

Halten Sie fest, wobei der Skill hilft, was als fertig gilt und was außerhalb seines Auftrags liegt. Ohne Grenzen tut ein Agent womöglich mehr als nötig oder vermengt unzusammenhängende Aufgaben zu einem unordentlichen Ergebnis.

3. Ein ausführbarer Ablauf

Formulierungen wie "mach es gut" oder "folge Best Practices" erklären nicht, wie etwas zu tun ist. Ersetzen Sie sie durch beobachtbare Schritte:

1. Die Quelldateien lesen.
2. Prüfen, ob die benötigten Informationen vorhanden sind.
3. Fakten von Annahmen trennen.
4. Die Ausgabe in der geforderten Struktur erstellen.
5. Sie anhand einer Checkliste prüfen.
6. Die passenden Tests oder Validierungen ausführen.

Arbeit mit hohem Risiko verlangt eine besonders ausdrückliche Überprüfung.

4. Grenzen und Entscheidungsregeln

Schreiben Sie aus, was der Agent niemals tun darf. Typische Beispiele sind erfundene Kennzahlen, preisgegebene Geheimnisse, Änderungen an Dateien außerhalb des vereinbarten Umfangs oder die Darstellung einer Anforderung als bereits ausgeliefertes Feature.

5. Ausgabeverträge und Beispiele

Fließt die Ausgabe in einen anderen Prozess, legen Sie ihre Form fest. Das können Markdown-Überschriften sein, ein JSON-Schema, Dateinamen oder Pflichtabschnitte. Beispiele verringern Mehrdeutigkeit, aber zu viele starre Beispiele lassen alle Ergebnisse gleich aussehen. Sie sollen den Vertrag veranschaulichen und kein Urteilsvermögen ersetzen.

6. Qualitätsprüfungen

Ein Skill sollte erklären, woran man erkennt, dass die Arbeit wirklich fertig ist, denn eine Datei zu erzeugen ist nicht immer dasselbe, wie die Aufgabe abzuschließen. Prüfungen können eine Checkliste sein, Linting, Unit-Tests, Schema-Validierung oder Review-Fragen:

• Sind die Tatsachenbehauptungen belegt?
• Geht eine Aussage über den tatsächlichen Stand des Produkts hinaus?
• Erfüllt die Ausgabe den Vertrag?
• Gibt sie personenbezogene Daten oder Geheimnisse preis?

Braucht ein Skill einen Index?

Ein Index wird sehr nützlich, wenn das Material wächst, aber er sorgt nicht automatisch dafür, dass die KI alles im Skill kennt.

Oft wird es so erklärt: Die KI liest von oben, findet den Index und kann zu relevanten Inhalten springen, ohne die ganze Datei zu lesen. Als Denkmodell ist das praktisch, eine allgemeine Regel ist es aber nicht. Wie Informationen gelesen, durchsucht und ausgewählt werden, hängt vom Modell ab, von der Agenten-Laufzeitumgebung, den Werkzeugen für die Dateisuche, der Strategie zum Laden von Kontext und den Systemanweisungen.

Was ein Index zuverlässig leistet, ist eine bessere Organisation des Materials. In der Praxis kann er:

• dem Agenten wie auch einem menschlichen Leser einen schnellen Überblick geben
• beschreiben, was in jedem Abschnitt oder jeder Referenzdatei steht
• dem Agenten helfen, nur die Referenzen auszuwählen, die eine Aufgabe braucht
• die Versuchung verringern, jedes Dokument in den Kontext zu laden
• einen Skill aus mehreren Dateien leichter wartbar machen

Ein guter Index listet also nicht nur Dateinamen auf. Er sagt, wann welche Datei wichtig ist. Zum Beispiel:

references/
├── api-contract.md      # Read when creating or changing an API
├── security-rules.md    # Read when touching auth, secrets, or permissions
├── output-examples.md   # Read when validating the required output shape
└── troubleshooting.md   # Read when validation or tests fail

So ein Aufbau lässt den Agenten wählen und erspart ihm, anhand von Dateinamen zu raten oder vorsichtshalber alles zu laden.

Wann man einen Skill auf mehrere Dateien aufteilt

Ist ein Skill kurz, folgt er einem einzigen Ablauf und lässt er sich leicht überfliegen, ist eine Datei womöglich am klarsten. Zu frühes Aufteilen erzeugt mehr Verweise, die gepflegt werden müssen, und lässt den Leser zwischen Dateien springen.

Das Aufteilen lohnt sich, sobald der Skill umfangreiches Referenzmaterial, mehrere Abläufe, einen Stapel Beispiele oder wiederverwendbare Skripte enthält. Eine mögliche Struktur:

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Welche Verzeichnisse und Namen unterstützt werden, kann je nach Plattform und Laufzeitumgebung variieren, und wie ein Agent die Dateien nutzt, kann vom Modell und seinen Werkzeugen abhängen. Als Faustregel sollte die Hauptdatei sagen, was zu tun ist und wo tiefergehende Details zu finden sind. Nicht alles gehört nach oben, aber was dort steht, sollte schnelle und richtige Entscheidungen unterstützen.

Einen Skill wie Software behandeln

Ein Skill kann Anweisungen, Referenzen und ausführbare Skripte bündeln. Einen fremden Skill ungelesen zu installieren birgt daher ungefähr dasselbe Risiko, wie ein Paket zu installieren oder unbekannten Code auszuführen. Stellen Sie vor der Übernahme mindestens diese Fragen:

• Greift er auf mehr Dateien zu, als er eigentlich bräuchte?
• Gibt es ausgehende Netzwerk- oder API-Aufrufe, und wohin?
• Sind irgendwo Geheimnisse oder Zugangsdaten fest eingetragen?
• Welche Daten können seine Skripte ändern oder löschen?
• Ist darin etwas geschrieben, um Systemregeln zu umgehen?

Organisationen brauchen unter Umständen auch Reviews, Sandboxing und Kompatibilitätstests. Modelle reagieren unterschiedlich auf Anweisungen und wählen Werkzeuge verschieden aus, und jede Plattform oder Firma kann eigene Governance-Regeln durchsetzen.

Weiterführende Lektüre

Offizielle Hinweise zum Schreiben von Skills finden Sie unter https://agentskills.io/skill-creation/best-practices sowie in der Plattformdokumentation von Anthropic zu Agent Skills (auf platform.claude.com, auf der Seite mit Best Practices für agent-skills).

Das Fazit

Mit KI zu arbeiten unterscheidet sich gar nicht so sehr von der Arbeit mit einem Kollegen. Wenn Sie Ziel, Kontext, Ablauf, Einschränkungen und Prüfkriterien klar benennen, hat jeder, der die Aufgabe bekommt, ob Mensch oder Agent, bessere Chancen, das Gewünschte zu liefern. Eine Skill-Datei hält dieses gemeinsame Verständnis fest, damit Sie es nicht jedes Mal von vorn aufbauen müssen.

Wenn ein Skill wächst oder auf mehrere Dateien verweist, fügen Sie einen Index hinzu, aber bauen Sie ihn als Entscheidungslandkarte und nicht als dekoratives Inhaltsverzeichnis. Lesen Sie den Skill dann mit den Augen eines Fremden und fragen Sie:

Könnte diese Person von hier aus wirklich weitermachen, oder müsste sie immer noch Entscheidungen anstelle des Verfassers treffen?

Wenn ja, klären Sie diese Entscheidungen zuerst. Ein guter Skill nimmt einem das Denken nicht ab. Er beseitigt vermeidbares Raten.