Auf dieser Seite

Skills für KI-Agenten bauen

Ein Leitfaden sagt einem KI-Agenten, was in einem Projekt immer gilt. Ein Skill sagt ihm, wie eine bestimmte Aufgabe geht. Der Leitfaden ist die Küchenordnung, der Skill das Rezept.

Was ich einem Agenten zweimal erklärt habe, mache ich zum Skill. Dieser Artikel beschreibt, wie ich Skills baue. Er vertieft einen Abschnitt aus Vom Prompt zum Pull Request.

Ein Skill hat einen Zweck

Ein Skill ist ein Ordner, der wie der Skill heißt. Darin liegt eine Datei SKILL.md. Sie beginnt mit einem kurzen Kopf, dem Frontmatter, aus Name und Beschreibung. Daneben können Skripte und Beispiele liegen, die der Agent erst liest, wenn er sie braucht. Das Format ist als Agent Skills offen beschrieben, und mehrere Agenten-Werkzeuge lesen es. Ein vereinfachtes Beispiel, das ein Skript check in der package.json voraussetzt:

---
name: verify
description: Prüft den aktuellen Stand. Verwenden nach jeder Änderung am Code und bevor eine Änderung als fertig gemeldet wird.
---

# Prüfen

1. `bun run check` ausführen. Das Skript prüft Typen, Linting, Tests und Build parallel. Bei Erfolg gibt es eine Zeile aus, bei Fehlern nur die Meldungen, nach Prüfschritt getrennt.
2. Bei Erfolg eine Zeile melden.
3. Bei Fehlern je Meldung die vermutliche Ursache nennen.

Schlägt ein Test fehl, wird der Code korrigiert. Der Test wird nicht übersprungen und nicht angepasst.
Scheint der Test veraltet, Ursache nennen und nachfragen. Die Entscheidung trifft ein Mensch.

Die Beschreibung im Kopf ist wichtiger, als sie aussieht. Der Agent sieht zunächst nur Name und Beschreibung aller Skills und lädt den Rest erst, wenn ein Skill passt. Eine vage Beschreibung führt dazu, dass er nie oder ständig verwendet wird. Deshalb nennt sie nicht nur, was der Skill tut, sondern auch, wann er gebraucht wird.

Klein halten

Ein Skill, der eine Spezifikation schreibt, sie umsetzt, testet und einen Pull Request öffnet, klingt praktisch. Er scheitert an derselben Stelle wie ein überladener Prompt: Je mehr er tun soll, desto ungenauer erledigt er jede einzelne Aufgabe.

Ich baue viele kleine Skills und lasse sie nacheinander laufen. Jeder hat eine Eingabe und ein Ergebnis. Scheitert einer, ist klar, welcher.

Nach unten gibt es auch eine Grenze. Jede Beschreibung belegt dauerhaft Kontext, und ähnliche Beschreibungen konkurrieren miteinander. Was in einen Satz passt, gehört in den Leitfaden, nicht in einen eigenen Skill.

Was sich als Skill eignet

Bei mir sind das etwa: eine Spezifikation schreiben, einen neuen Artikel mit gültigem Frontmatter anlegen, den Stand prüfen, eine Beschreibung für einen Pull Request aus der Spezifikation erzeugen.

Nicht geeignet sind Aufgaben, die jedes Mal anders sind. Für sie genügt eine gute Beschreibung der Aufgabe selbst.

Deterministisches gehört in Skripte

Ein Skill ist Text, den ein Agent deutet. Was immer gleich ablaufen muss, gehört nicht in Text, sondern in ein Skript, das der Skill aufruft.

Im Beispiel oben steht deshalb kein Ablauf aus Einzelschritten, sondern ein Aufruf: bun run check. Der Agent entscheidet, wann geprüft wird und was mit dem Ergebnis geschieht. Wie geprüft wird, steht im Skript und ist bei jedem Lauf dasselbe. Ob vor einem Commit geprüft wird, darf allerdings nicht vom Agenten abhängen. Das gehört in einen Git-Hook oder in die CI. Der Skill sorgt dafür, dass der Agent schon vorher prüft und mit dem Ergebnis sinnvoll umgeht.

Diese Aufteilung ist die wichtigste Regel. Agenten sind gut darin, zu entscheiden und zusammenzufassen. Für exakte Wiederholung gibt es Programme.

Ausgabe sparen

Ein Agent hat begrenzte Aufmerksamkeit. Ein Prüfschritt, der dreitausend Zeilen erfolgreicher Tests ausgibt, verdrängt, was wichtig ist.

Meine Skills verlangen deshalb knappe Ergebnisse: Bei Erfolg eine Zeile, bei Fehlern nur die Fehlermeldungen. Das hält den Agenten bei der Aufgabe und spart Kontext und Kosten. Am zuverlässigsten ist es, wenn schon das Skript knapp ausgibt, statt dass der Agent lange Ausgaben kürzen muss. Ob der Lauf gelungen ist, entscheidet dabei der Exit-Code, nicht der gekürzte Text. Fehlermeldungen behalten Datei, Zeile und Testname, sonst sucht der Agent die Stelle selbst und verbraucht den gesparten Kontext wieder.

Mit Beispielen arbeiten

Für Aufgaben mit einem bestimmten Format, etwa eine Spezifikation, liegt dem Skill ein Beispiel bei. Ein Beispiel ist genauer als eine Beschreibung des Formats und wird zuverlässiger eingehalten.

Für ein festes Format genügt meist ein Beispiel, denn hier ist erwünscht, dass der Agent es nachahmt. Soll er verallgemeinern, helfen mehrere Beispiele, die sich deutlich unterscheiden. Ähnliche Beispiele führen dazu, dass er ihre Gemeinsamkeiten überbetont.

Skills pflegen

Skills liegen versioniert im Repository. Sie ändern sich wie Code:

Übertragbar

Ein Skill, der keine Eigenheiten eines Projekts enthält, lässt sich in ein anderes übernehmen. Projektspezifisches steht im Leitfaden, auf den der Skill verweist. So entsteht über die Zeit eine Sammlung allgemeiner Abläufe, die ich in neue Vorhaben mitbringe.

Wiederholbar, nicht richtig

Ein Skill macht einen Ablauf wiederholbar. Richtig wird das Ergebnis dadurch nicht. Deshalb geht bei mir jedes Ergebnis erst durch die automatischen Prüfungen und dann durch mein Review, bevor ich es übernehme. Wie das aussieht, beschreibt Vom Prompt zum Pull Request.

Thema für Ihr Projekt?

Passende Leistung: Agentische Entwicklung einführen. Schildern Sie mir kurz, worum es geht. Ich melde mich mit einer ersten Einschätzung.

Projekt anfragen