Agent Skills 2026: Definition, Aufbau und Praxis

Sie geben Ihrem AI Agent immer wieder dieselben Anweisungen, trotzdem werden Schritte ausgelassen oder Werkzeuge zu früh ausgeführt. Die schnellste Lösung ist kein zusätzliches Modelltraining: Agent Skills 2026 verpacken wiederholbare, prüfbare Abläufe in einen Ordner mit SKILL.md, optionalen Skripten und Referenzmaterial, das nur bei Bedarf geladen wird.

Diese Anleitung richtet sich an Entwickler, die zum ersten Mal mit Agent Skills arbeiten, an Verantwortliche, die Team-SOPs an einen AI Agent übergeben möchten, und an Produktmanager, die Prompt, Rules, Skills und Workflow sauber voneinander abgrenzen müssen. Wenn Sie eine Remote-Entwicklungsumgebung für solche Tests bewerten, sollten Sie neben der Skill-Struktur auch Betriebsverantwortung, Datenschutz und Zugriffskontrollen prüfen; eine neutrale Einordnung dazu finden Sie in den Informationen zur Arbeitsweise von kvmboot.

Zuletzt aktualisiert am 12.08.2026; die Angaben wurden anhand der aktuellen Agent Skills-Spezifikation, der Claude-Code-Dokumentation und der Dokumentation zu unterstützten Clients überprüft.

Agent Skills 2026: Das Grundprinzip hinter dem Begriff

Agent Skills sind keine neue Modellarchitektur und keine dauerhafte Erweiterung der Parameter eines Sprachmodells. Sie sind portable Fähigkeitspakete, mit denen ein Agent prozedurales Wissen, konkrete Arbeitsschritte und ergänzende Ressourcen zur passenden Aufgabe laden kann.

Der Kern besteht aus einer Verzeichnisstruktur mit mindestens einer Datei namens SKILL.md. Diese Datei enthält Metadaten und Anweisungen. Je nach Aufgabe können zusätzlich Skripte, Referenzdokumente, Vorlagen oder andere Ressourcen enthalten sein. Die offizielle Übersicht zu Agent Skills beschreibt Skills als wiederverwendbare Ordner für spezialisiertes Wissen und Arbeitsabläufe.

Was sind Agent Skills im praktischen Sinn? Ein Skill ist eine versionierbare Arbeitsanweisung für einen AI Agent. Sie beschreibt nicht nur, was ein Ergebnis sein soll, sondern auch, in welcher Reihenfolge der Agent prüft, welche Werkzeuge er verwenden darf, welche Dateien relevant sind und wann ein Mensch oder ein automatisierter Test die Ausgabe abnehmen muss.

Das unterscheidet einen Skill von einer langen Eingabeaufforderung. Ein Prompt existiert häufig nur für eine einzelne Sitzung. Ein Skill liegt dagegen im Projekt oder in einem persönlichen Skill-Verzeichnis, kann gemeinsam gepflegt werden und wird bei passenden Aufgaben erneut verwendet.

Der Nutzen entsteht vor allem in vier Situationen:

• Der Ablauf wiederholt sich regelmäßig.
• Die einzelnen Schritte sind relativ stabil.
• Das Ergebnis lässt sich durch Tests, Regeln oder menschliche Kriterien überprüfen.
• Mehrere Personen oder Agenten sollen denselben Prozess verwenden.

Für eine einmalige kreative Anfrage, eine noch völlig unklare Problemstellung oder ein Verfahren ohne überprüfbares Ergebnis ist ein Skill dagegen meist die falsche Abstraktion.

Vor dem Erstellen: Geeignete Prozesse systematisch auswählen

Bevor Sie eine SKILL.md schreiben, sollten Sie nicht mit dem Dateiformat beginnen, sondern mit dem Prozess. Viele schlecht gepflegte Skills sind eigentlich nur unpräzise Prompts, die in einen Ordner verschoben wurden.

Ein Prozess eignet sich typischerweise, wenn Sie die folgenden Fragen überwiegend mit „Ja“ beantworten können:

1. Kommt die Aufgabe regelmäßig vor?

Beispiele sind Code-Reviews, Release-Notizen, Datenbereinigung, API-Dokumentation oder die Prüfung einer CI/CD-Pipeline.

1. Sind die Eingangsdaten erkennbar?

Ein Skill sollte erkennen können, ob beispielsweise ein Pull Request, ein Logfile, eine CSV-Datei oder eine bestimmte Dokumentklasse vorliegt.

1. Lässt sich der Ablauf in überprüfbare Schritte zerlegen?

„Analysieren Sie das Projekt gründlich“ ist zu offen. „Prüfen Sie zuerst die Abhängigkeiten, führen Sie danach den Linter aus und dokumentieren Sie anschließend alle Fehler“ ist deutlich besser.

1. Gibt es ein erwartbares Ausgabeformat?

Das kann ein Prüfbericht, ein Patch, eine strukturierte Tabelle, eine Zusammenfassung oder eine Liste von offenen Risiken sein.

1. Kann jemand die Qualität nach der Ausführung bewerten?

Ein Skill ist kein Ersatz für Abnahme. Er sollte aber ein Ergebnis produzieren, das anhand von Tests, Diff-Prüfung oder fachlichen Kriterien kontrolliert werden kann.

Nicht geeignet sind dagegen einmalige Fragen, spontane Brainstorming-Aufgaben und ungeprüfte Wissenssammlungen. Auch ein beliebiges Shell-Skript sollte nicht allein deshalb zu einem Skill werden, weil ein Agent es ausführen kann. Der eigentliche Wert liegt in der Kombination aus Auslöser, Verfahren, Einschränkungen und Kontrolle.

Fallbeispiel: Ein Team macht aus Code-Reviews einen Skill

Angenommen, Ihr Team prüft jeden Pull Request nach einem festen Muster. Zuerst werden Änderungen nach Sicherheitsrisiken durchsucht, anschließend werden betroffene Tests ausgeführt, danach wird geprüft, ob öffentliche Schnittstellen dokumentiert sind. Zum Schluss soll der Agent nur begründete Befunde mit Dateipfad und Priorität ausgeben.

Das ist ein guter Skill-Kandidat, weil Eingabe, Ablauf und Ergebnis klar begrenzt sind. Ein allgemeiner Skill mit dem Titel „Verbessere den Code“ wäre hingegen zu unspezifisch. Seine Beschreibung würde kaum zuverlässig erkennen lassen, wann er aktiviert werden soll.

Aufbau einer Skill-Datei: Bestandteile von SKILL.md

Die öffentliche Spezifikation für Agent Skills schreibt eine SKILL.md mit YAML-Frontmatter und Markdown-Inhalt vor. Für die Standardkonformität sollten Sie nur Felder verwenden, deren Bedeutung in der Spezifikation oder in der Dokumentation des jeweiligen Clients eindeutig beschrieben ist.

Die minimale Struktur sieht so aus:

code-review/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── weitere-dateien/

In der SKILL.md sind name und description die zentralen Pflichtfelder. Der Name dient der eindeutigen Identifikation und muss dem Verzeichnisnamen entsprechen. Die Beschreibung erklärt, was der Skill erledigt und bei welchen Aufgaben er verwendet werden sollte.

---
name: code-review
description: Prüft Pull-Request-Änderungen auf Sicherheitsrisiken,
Testlücken und dokumentationspflichtige Schnittstellen. Verwenden Sie
diesen Skill bei Code-Reviews und vor dem Zusammenführen eines Pull Requests.
---

## Vorgehen

1. Lesen Sie zuerst den Änderungsumfang.
2. Prüfen Sie sicherheitsrelevante Stellen.
3. Führen Sie die verfügbaren Tests aus.
4. Geben Sie nur nachvollziehbare Befunde aus.

Die Spezifikation begrenzt den Namen auf maximal 64 Zeichen und die Beschreibung auf maximal 1.024 Zeichen. Das sind keine Empfehlungen für bessere Schreibweise, sondern formale Grenzen der öffentlichen Strukturdefinition.

Optionale Felder können beispielsweise Lizenzinformationen, Umgebungsanforderungen oder zusätzliche Metadaten beschreiben. compatibility ist sinnvoll, wenn ein Skill bestimmte Systempakete, Netzwerkzugriff oder eine konkrete Laufzeitumgebung benötigt. metadata kann für interne Angaben wie Versionsnummern oder Verantwortliche verwendet werden. allowed-tools ist als experimentelles Feld gekennzeichnet; die Unterstützung kann je nach Implementierung abweichen.

Welche Aufgabe hat die Datei SKILL.md? Sie ist der Einstiegspunkt des Skills. Die Datei verbindet die Erkennung durch den Agenten mit dem eigentlichen Arbeitsverfahren. Sie sollte deshalb weder nur aus einer Kurzbeschreibung bestehen noch zu einem unstrukturierten Handbuch mit beliebigen Hintergrundinformationen anwachsen.

Die Verzeichnisse haben unterschiedliche Aufgaben:

• scripts/ enthält ausführbaren Code, etwa Prüfprogramme, Konverter oder Parser.
• references/ enthält Fachinformationen, die der Agent nur bei Bedarf lesen muss.
• assets/ enthält Vorlagen, Beispieldateien, Schemata oder statische Ressourcen.
• Weitere Dateien sind möglich, sollten aber eine klar erkennbare Funktion haben.

Die Spezifikation empfiehlt, die Hauptdatei überschaubar zu halten und ausführliche Referenzinformationen auszulagern. Im veröffentlichten Progressive-Disclosure-Modell werden Metadaten zuerst, die vollständigen Anweisungen bei Aktivierung und zusätzliche Ressourcen erst bei Bedarf geladen. Die Dokumentation nennt dafür ungefähr 100 Tokens für Metadaten, weniger als 5.000 Tokens für den Anweisungsteil und eine empfohlene Obergrenze von 500 Zeilen für die zentrale Datei.

Diese Werte sind Planungsrichtlinien, keine Garantie für identisches Verhalten in jedem Client. Sie zeigen jedoch, warum eine große Wissensdatenbank nicht ungefiltert in SKILL.md gehört.

Entdeckung und Aktivierung: Der Weg vom Namen zur vollständigen Anleitung

Der Lebenszyklus beginnt mit der Discovery. Ein kompatibler Client durchsucht bekannte Skill-Verzeichnisse und liest zunächst die Metadaten. Der Agent muss zu diesem Zeitpunkt noch nicht sämtliche Anweisungen, Skripte und Referenzdokumente in den Kontext laden.

Anschließend bewertet er, ob die aktuelle Aufgabe zur Beschreibung passt. Genau hier entsteht eine der häufigsten Fehlerquellen: Eine unpräzise Beschreibung verschlechtert die Aktivierung, obwohl der eigentliche Ablauf korrekt sein kann.

Die Anleitung zur Optimierung von Skill-Beschreibungen empfiehlt, den Zweck und typische Auslöser konkret zu benennen. „Hilft bei Dokumenten“ ist zu allgemein. „Extrahiert Tabellen aus PDF-Dateien und erstellt daraus eine strukturierte CSV-Datei, wenn der Nutzer PDF-Tabellen oder Dokumentenimport erwähnt“ gibt dem Agenten deutlich bessere Signale.

Ist die Beschreibung eine Form des Modelltrainings? Nein. Die Beschreibung verändert nicht dauerhaft die Gewichte des Modells. Sie dient als kostengünstiger Index, anhand dessen der Client entscheidet, ob der vollständige Skill relevant sein könnte. Erst nach dieser Entscheidung wird die eigentliche Anleitung geladen.

Die Aktivierung kann automatisch oder manuell erfolgen. Die Quickstart-Anleitung für Agent Skills zeigt ein einfaches Beispiel, bei dem eine passende Aufgabe zur Aktivierung einer vollständigen SKILL.md führt.

Wichtig ist die Trennung zwischen Standard und Client-Erweiterung:

• Die Agent-Skills-Spezifikation definiert Dateiformat, Metadaten und Grundstruktur.
• Ein Client entscheidet, in welchen Verzeichnissen er Skills sucht.
• Ein Client kann zusätzliche Felder, Slash-Befehle oder Berechtigungsmodelle anbieten.
• Ein Feld, das in einem bestimmten Produkt funktioniert, ist deshalb nicht automatisch Teil des offenen Standards.

Die Dokumentation zu clientabhängigen Skill-Verzeichnissen und Berechtigungen zeigt, warum projektbezogene und persönliche Speicherorte sowie zusätzliche Berechtigungsoptionen getrennt bewertet werden müssen. Diese Details sind clientabhängig und sollten nicht als allgemeine Pflichtbestandteile jedes Skills ausgegeben werden.

Ausführung: Laden, Werkzeuge und externe Inhalte

Nach der Aktivierung lädt der Agent den vollständigen Anweisungsteil und entscheidet, ob er weitere Dateien benötigt. Ein Skill für Datenanalyse kann zunächst nur die Prozessbeschreibung lesen und später ein Schema aus references/ oder ein Validierungsskript aus scripts/ verwenden.

Diese schrittweise Auflösung hat drei praktische Vorteile:

• Nicht jede Aufgabe erhält den vollständigen Inhalt aller Skills.
• Große Referenzdokumente können getrennt gepflegt werden.
• Das Team kann den eigentlichen Arbeitsablauf von Detailwissen und ausführbarem Code trennen.

Sie sollten in der SKILL.md deshalb ausdrücklich festlegen, wann eine Ressource geladen oder ein Skript ausgeführt wird. Ein bloßer Dateiname reicht nicht immer aus. Beschreiben Sie Eingaben, erwartete Ausgaben, Fehlerfälle und Abbruchbedingungen.

Berechtigungen sind Teil des Designs

Ein Skill kann fachlich korrekt sein und trotzdem ein Sicherheitsrisiko darstellen. Das gilt besonders dann, wenn er Shell-Befehle, Netzwerkzugriff, Dateien mit Geheimnissen oder externe Inhalte verarbeitet.

Die Sicherheitshinweise für Skills mit Shell- und Bash-Werkzeugen warnen davor, ausführbare Werkzeuge ohne Prüfung vorab zu erlauben. Dadurch könnten manipulierte Skills oder Prompt-Injection-Inhalte Aktionen auslösen. Wenn Sie ein Werkzeug nicht zwingend benötigen, sollte der Agent vor der Nutzung um Bestätigung bitten.

Prüfen Sie vor der Freigabe mindestens:

• Welche Dateien darf der Skill lesen?
• Darf er Dateien verändern oder löschen?
• Welche Shell-Befehle sind wirklich notwendig?
• Kann ein Eingabedokument eigene Anweisungen enthalten, die der Skill nicht befolgen sollte?
• Werden Zugangsdaten, Kundendaten oder personenbezogene Informationen verarbeitet?
• Ist der Netzwerkzugriff erforderlich und dokumentiert?
• Gibt es einen reproduzierbaren Probelauf ohne produktive Daten?

Für Unternehmen ist zusätzlich die Datenschutzperspektive wichtig. Ein Skill sollte keine vertraulichen Informationen in Referenzdateien hardcodieren und keine unnötigen Daten an externe Dienste übergeben. Bei personenbezogenen Daten müssen Sie die geltenden DSGVO-Vorgaben, Auftragsverarbeitung und Zugriffskontrollen getrennt prüfen. Ein Skill allein ersetzt keine Datenschutzprüfung.

Prüfung und Versionierung als Betriebsstandard

Ein AI Agent kann eine Anleitung befolgen und trotzdem ein falsches Ergebnis erzeugen. Die Abnahme muss daher außerhalb der bloßen Textausgabe stattfinden.

Gehen Sie bei der Einführung in dieser Reihenfolge vor:

1. Definieren Sie einen repräsentativen Testfall.

Verwenden Sie eine echte, anonymisierte Aufgabe mit bekanntem Soll-Ergebnis.

1. Ergänzen Sie einen Negativfall.

Testen Sie, was passiert, wenn Eingabedateien fehlen, das Format nicht stimmt oder eine Berechtigung nicht verfügbar ist.

1. Prüfen Sie die Werkzeuggrenzen.

Der Agent sollte nicht automatisch auf produktive Systeme zugreifen, nur weil ein Skript vorhanden ist.

1. Vergleichen Sie die Ausgabe mit einem festen Abnahmeschema.

Bei Code sind Tests, Linter und Diff-Prüfung geeignet. Bei Dokumenten können Pflichtabschnitte, Quellenprüfung und Formatregeln verwendet werden.

1. Dokumentieren Sie Fehler und ändern Sie den Skill gezielt.

Schreiben Sie nicht nach jedem Fehlversuch die gesamte Anleitung um. Kennzeichnen Sie, welche Regel missverstanden wurde und ob das Problem in der Beschreibung, dem Ablauf, einem Skript oder einer fehlenden Referenz liegt.

1. Versionieren Sie den Skill gemeinsam mit dem Projekt.

Änderungen an SKILL.md, Skripten und Referenzen sollten nachvollziehbar bleiben. Ein Review durch eine zweite Person ist besonders wichtig, wenn Berechtigungen oder produktive Systeme betroffen sind.

Für die strukturelle Prüfung können Sie ein Validierungswerkzeug wie skills-ref validate einsetzen. Eine solche Prüfung kontrolliert vor allem die Verzeichnisstruktur und das Frontmatter; sie beweist nicht, dass der fachliche Ablauf korrekt ist. Deshalb benötigen Sie zusätzlich echte Testfälle, Negativtests und eine fachliche Abnahme.

Prompt, Rules, Workflow und Skill im direkten Vergleich

Die Begriffe überschneiden sich, erfüllen aber unterschiedliche Aufgaben. Für eine Architekturentscheidung hilft folgende Einordnung:

Was unterscheidet AI Agent Skills von einem normalen Prompt? Ein Prompt beschreibt meist die aktuelle Absicht. Ein Skill beschreibt ein wiederverwendbares Verfahren, das in einem definierten Kontext erneut aktiviert werden kann. Der Skill kann außerdem Skripte, Referenzmaterial und Vorlagen mitführen. Damit wird aus einer textlichen Bitte ein wartbarer Baustein für den Agenten.

Rules eignen sich für Vorgaben wie „Verwenden Sie dieses Testframework“ oder „Ändern Sie keine generierten Dateien“. Ein Skill für die Aufgabe „Führen Sie eine Release-Prüfung durch“ sollte dagegen nur bei diesem Prozess geladen werden. Ein Workflow ist noch stärker orchestriert: Er kann einen Trigger, mehrere Agenten, externe Systeme und feste Übergaben enthalten. Ein Skill kann Bestandteil eines Workflows sein, ersetzt ihn aber nicht automatisch.

Übertragbarkeit zwischen verschiedenen AI-Tools

Können Agent Skills in verschiedenen AI-Tools verwendet werden? Das Format ist auf Portabilität ausgelegt, aber „kompatibel“ bedeutet nicht „identisch unterstützt“. Die öffentliche Agent-Skills-Spezifikation beschreibt ein offenes Format, während einzelne Clients eigene Suchpfade, Berechtigungen und Werkzeugaufrufe verwenden können.

In der Praxis müssen Sie drei Ebenen unterscheiden:

1. Gemeinsames Format:

Eine gültige SKILL.md mit standardnahen Feldern kann in mehreren Clients als Ausgangspunkt dienen.

1. Verzeichnis- und Installationsregeln:

Jeder Client kann eigene Suchpfade und Projektstrukturen verwenden. Projektbezogene und persönliche Skills liegen nicht zwingend am selben Ort.

1. Werkzeuge und Berechtigungen:

Ein Skript, ein MCP-Anschluss oder ein spezielles Berechtigungsfeld funktioniert nur, wenn der jeweilige Client diese Funktion unterstützt.

Wenn Sie einen Skill portieren, testen Sie deshalb nicht nur das Frontmatter. Prüfen Sie auch die Pfade, Shell-Befehle, Dateirechte, Toolnamen, Netzwerkabhängigkeiten und das Verhalten bei fehlenden Ressourcen. Für Claude Skills oder Skills in anderen Umgebungen sollten Sie clientbezogene Erweiterungen klar dokumentieren und nicht als Bestandteil des allgemeinen Standards ausgeben.

Typische Einsatzgebiete und klare Grenzen

Agent Skills eignen sich besonders für:

• Code-Review und Sicherheitsprüfung
• Test- und Debugging-Abläufe
• Dokumentation aus Quellcode oder Änderungslisten
• Datenanalyse mit festem Eingabe- und Ausgabeformat
• Release- und Migrationsvorbereitung
• Interne SOPs für Support, Betrieb und Qualitätssicherung
• Wiederkehrende CI/CD-Aufgaben mit menschlicher Freigabe

Weniger geeignet sind Skills für:

• völlig offene Forschungsfragen ohne festgelegte Prüfkriterien
• einmalige Aufgaben, die schneller mit einem direkten Prompt erledigt sind
• Entscheidungen, bei denen ausschließlich vertrauliche oder unvollständige Daten vorliegen
• Prozesse, die zwingend deterministisch und ohne Modellinterpretation ablaufen müssen
• ungeprüfte Skripte mit Schreibzugriff auf produktive Systeme

Für solche Fälle kann ein klassischer Workflow, ein deterministisches Skript oder eine menschliche Prüfung die bessere Lösung sein. Agent Skills erhöhen die Wiederverwendbarkeit von Anweisungen; sie garantieren weder korrekte Schlussfolgerungen noch sichere Ausführung.

Wenn Sie die praktische Umgebung für Agent-Workflows getrennt von der Konzeptentscheidung bewerten möchten, finden Sie technische Hinweise zur verfügbaren Arbeitsumgebung im kvmboot-Hilfecenter. Entscheidend bleibt jedoch die technische Prüfung des konkreten Clients: Unterstützt er die erwarteten Suchpfade, Skripte, Dateirechte und Freigabeschritte?

Die nächste sinnvolle Umsetzung

Beginnen Sie nicht mit zehn Skills gleichzeitig. Wählen Sie einen einzelnen Prozess, bei dem Eingaben, Schritte und Abnahme bereits bekannt sind. Schreiben Sie zuerst eine kleine SKILL.md, ergänzen Sie nur die wirklich benötigten Referenzen und lassen Sie den Skill anschließend mit einem Erfolgs- und einem Negativfall laufen.

Wenn Sie Claude Skills praktisch erstellen möchten, sollte der nächste Schritt ein konkreter Aufbau mit Testfällen, Versionskontrolle und Berechtigungsprüfung sein. Wenn Sie noch zwischen dauerhaft geltenden Rules und kontextabhängigen Skills schwanken, vergleichen Sie beide Strukturen anhand der Frage: Muss diese Vorgabe bei jeder Aufgabe gelten oder nur bei einem klar erkennbaren Prozess?

Eine eigene, stabile Entwicklungsumgebung ist dafür nicht in jedem Fall erforderlich. Für kurze Evaluierungen, Kompatibilitätstests oder temporäre Agent-Workflows kann eine gemietete Mac-Umgebung jedoch praktischer sein als eine lokale Installation: Beim lokalen Mac entstehen Anschaffungskosten, Wartungsaufwand und eine feste Bindung an vorhandene Hardware; bei einer gewöhnlichen Cloud-Umgebung können macOS-spezifische Werkzeuge und realistische Build-Bedingungen fehlen. Wenn Sie nur vorübergehend testen, mehrere Skill-Versionen vergleichen oder einen reproduzierbaren Remote-Arbeitsplatz benötigen, können Sie die Anforderungen einer verfügbaren Mac-Umgebung anhand der technischen Zugangsoptionen von kvmboot prüfen. Für dauerhaft hohe Auslastung, spezielle physische Schnittstellen oder langfristig kalkulierbare Infrastruktur bleibt der Kauf eigener Hardware beziehungsweise eine fest geplante Umgebung die ehrlichere Wahl.