Agentenfähigkeiten sind ein Code: Bestimmen, offenlegen, scripten und testen Sie sie

Eine SKILL.md-Datei liest sich wie Dokumentation, doch ihre Bearbeitung verändert das Verhalten eines Agents. Dadurch steht sie eher dem Code als der Prosa nahe und sollte entsprechend entworfen, abgegrenzt und getestet werden.

Fähigkeiten sind keine Dokumentation

Die übliche erste Reaktion beim Erstellen einer LLM-Fähigkeit besteht darin, mehr zu schreiben: die Architektur zu erklären, Beispiele hinzuzufügen, Randfälle zu beschreiben und Hintergrundinformationen einzubeziehen, damit das Modell versteht, warum die Dinge so funktionieren. Diese Reaktion ist in der Regel falsch.

Eine Fähigkeit ist kein Handbuch für Entwickler, die Ihr System lernen. Es handelt sich um Kontext, der in einen Agenten eingegeben wird, der gerade versucht, eine Aufgabe zu erledigen. Dieser Unterschied prägt das gesamte Design. Die wichtige Frage ist nicht, wie man das System dem Modell erklärt, sondern was der Agent wissen muss, um die nächste Entscheidung richtig zu treffen.

Von dieser Perspektive aus werden mehrere Entscheidungen einfacher:

• Verfassen Sie Anleitungen als Verfahren.
• Machen Sie die Aktivierungsbedingungen konkret.
• Laden Sie Informationen schrittweise hoch.
• Bringen Sie deterministische Aufgaben in Skripte.
• Prüfen Sie Fähigkeiten an echten Aufgaben.

Nur prozedurales Wissen

Moderne Programmieragenten bewältigen bereits eine erstaunliche Menge an allgemeinen Aspekten der Softwareentwicklung. Sie kennen Git und npm und verstehen Angular, React, TypeScript, SQL, REST-APIs, Testframeworks sowie CI-Konfigurationen. Eine Fähigkeit, die lediglich das Wiederholt, trägt fast nichts bei:

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Es verbraucht Kontext, ohne dem Modell etwas beizubringen, was es fehlt. Die wertvollen Fähigkeiten umfassen Kenntnisse, die speziell auf Ihre Umgebung zutreffen:

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Hier hat der Agent etwas gelernt, was er nicht zuverlässig aus Angulos öffentlicher Dokumentation schließen konnte – nämlich wie die Arbeit in einem bestimmten Repository ablaufen sollte. Dafür sind Fähigkeiten nützlich.

Das Agent Skills-Format organisiert dies als Verzeichnis, das ein SKILL.md sowie optional Skripte und Ressourcen enthält. Metadaten stehen zur Verfügung, um Inhalte zu finden, und die vollständigen Anweisungen sowie unterstützende Dateien werden nur dann geladen, wenn sie benötigt werden. Das Dateiformat ist nicht der entscheidende Punkt – entscheidend ist vielmehr die Grenze zwischen den allgemeinen Fähigkeiten des Modells und dem Wissen, das die Umgebung bereitstellen muss.

Kontext ist ein „Budget“

Alles, was einem Agenten gegeben wird, kostet Kontext. Toolbeschreibungen, MCP-Tool-Schemata, Anweisungen zum Repository, Konversationshistorien sowie Fähigkeitsbeschreibungen verbrauchen ihn alle, und der Inhalt einer aktivierten Fähigkeit verbraucht noch mehr. Die Frage ist daher nicht nur, ob bestimmte Informationen nützlich sind, sondern auch, ob sie für die anstehende Aufgabe nützlich sind.

Nehmen wir an, diese Fähigkeiten sind installiert:

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Wenn die Aufgabe darin besteht, einen fehlerhaften Angular-Unit-Test zu beheben, hat der Agent keinen Grund, sich mit dem Release-Prozess oder den Debugging-Schritten für PostgreSQL auszukennen. Deshalb ist die Erkundung fast genauso wichtig wie der Inhalt. Vergleichen Sie zwei Beschreibungen: Diese hier lässt sich äußerst einfach auslösen:

---
name: testing
description: Helps run tests in our repository.
---

Diese ist weitaus präziser:

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

Die zweite Beschreibung geht über die bloße Angabe der Fähigkeit hinaus. Sie legt eine Routing-Grenze fest, die irrelevante Anweisungen aus dem Arbeitskontext ausschließt. Ein Vortrag über das Design von Fähigkeiten für LLM-Agenten macht diesen Punkt deutlich: Skill-Metadaten sind keine administrativen Verzierungen. Unpräzise Aktivierungsregeln führen dazu, dass nützliche Anweisungen in falsche Aufgaben gelangen, während zu enge Regeln verhindern, dass die Fähigkeit überhaupt gefunden wird.

Progressive Offenlegung ist besser als ein riesiges SKILL.md

Ein häufiger Fehler besteht darin, SKILL.md zu einer kleinen internen Wiki zu entwickeln. Es beginnt mit zwanzig Zeilen, dann fügen jemandem Deployment-Schritte hinzu, anschließend Fehlerbehebung, Beispiele und Konfigurationsoptionen. Nach drei Monaten muss der Agent 1.500 Zeilen lesen, um eine einzige Datei zu ändern.

Strukturieren Sie es stattdessen wie Software:

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md enthält dann nur die Routing-Logik:

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

Detaillierte Testanleitungen werden nur dann im Kontext bereitgestellt, wenn eine Aufgabe das Testen beinhaltet. Anthropic bezeichnet dies als schrittweises Offenbaren: Der Agent lädt zunächst Metadaten herunter, liest den Haupttext, sobald die jeweilige Fähigkeit relevant erscheint, und öffnet referenzierte Dateien erst später – und nur dann, wenn es notwendig ist. Ziel ist es nicht, möglichst viel Wissen bereitzustellen, sondern das richtige Wissen zum richtigen Zeitpunkt zu liefern.

Lassen Sie Skripte das durchsetzen, was sie durchsetzen können

Eine weitere Grenze hilft dabei: Anleitungen dienen Entscheidungen, während Skripte für deterministische Aufgaben verwendet werden. Stellen Sie sich eine Fähigkeit vor, die Folgendes besagt:

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Ein Agent kann dies durchführen, aber nur indem er wiederholt Verzeichnisse überprüft, Dateien interpretiert, entscheidet, was als archiviert gilt, den Status verfolgt und vermutlich viele Toolaufrufe vornimmt. Wenn eine Operation genau beschrieben werden kann, sollte sie nur einmal geschrieben werden:

node scripts/check-angular-versions.mjs

Die Funktion gibt anschließend einfach an, wann sie ausgeführt werden soll und was mit dem Ergebnis zu tun ist:

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

Dies ist in mehrfacher Hinsicht besser. Der Script kann unitgetestet werden und verhält sich jedes Mal gleich. Er erfordert weniger Entscheidungen des Modells sowie oft weniger Aufrufe von Tools. Und wenn etwas fehlschlägt, kann man den Fehler reproduzieren, ohne von einem LLM zu verlangen, seine Überlegungen erneut durchzuführen.

Nichts davon bedeutet, Agenten durch Scripts zu ersetzen. Es geht darum, die richtige Abstraktion zu wählen. Verwenden Sie das Modell für Urteile, beispielsweise um zu entscheiden, welche Projekte von einem architektonischen Wandel betroffen sein könnten. Verwenden Sie Code für präzise Algorithmen, wie zum Beispiel die Auflistung der Projekte, die ein bestimmtes Paket importieren. Der Agent koordiniert beides – und diese Kombination ist besser als die Kodierung eines gesamten Workflows in Englisch.

Tools und Fähigkeiten lösen unterschiedliche Probleme

Ein Tool gibt einem Agenten eine Aktion, während eine Fähigkeit lehrt, wann und wie Aktionen verwendet werden sollen. Ein Kommandozeilen-Tool könnte beispielsweise eine Möglichkeit bieten, betroffene Projekte zu berechnen:

tr project affected --base main

Das Tool bietet die Möglichkeit. Die entsprechende Fähigkeit liefert das Wissen der Organisation:

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

Die CLI hat keine Ahnung, warum fünf betroffene Anwendungen verdächtig erscheinen sollten, und die Skill muss nicht wissen, wie Abhängigkeitsverfolgung funktioniert. Das ist eine klare Trennlinie. Derselbe Ansatz gilt, wenn die Funktionalität über ein Shell-Befehl, eine Web-API, einen MCP-Server oder jede andere Schnittstelle bereitgestellt wird: Verstecken Sie Richtlinien nicht in Low-Level-Tools, es sei denn, sie gehören dorthin, und schreiben Sie deterministische Algorithmen nicht als Prosa, es sei denn, es ist unbedingt notwendig.

Mehr Skills sind nicht automatisch besser

Ein verlockender Ansatz bei der Entwicklung von Agenten ist es, nützlich aussehende Skills zu sammeln, sie alle zu installieren und anzunehmen, der Agent sei dadurch leistungsfähiger geworden. Die Erfahrungen deuten jedoch darauf hin, dass man weitaus selektiver vorgehen sollte.

SkillsBench umfasst 86 Aufgaben aus 11 Bereichen. Laut der ersten Version der entsprechenden Studie führten sorgfältig ausgewählte Fähigkeiten zu einer durchschnittlichen Steigerung der Bestehensraten um 16,2 Prozentpunkte, wobei es große Unterschiede zwischen den Bereichen gab. In der Softwareentwicklung verbesserte sich die Rate nur um 4,5 Punkte, und bei 16 von 84 Aufgaben verschlechterten sich die Ergebnisse nach Hinzufügen der Fähigkeiten. Von den selbst generierten Fähigkeiten, die von den Modellen selbst erstellt wurden, gab es keinen durchschnittlichen Vorteil.

SWE-Skills-Bench untersuchte 49 öffentlich verfügbare Fähigkeiten bei echten Softwareentwicklungsaufgaben. Bei 39 davon kam es zu keiner Verbesserung der Bestehensraten, und der durchschnittliche Vorteil betrug lediglich 1,2 Punkte. Einige hochspezialisierte Fähigkeiten, insgesamt sieben, verbesserten die Ergebnisse um bis zu 30 Punkte. Weitere drei Fähigkeiten verschlechterten die Ergebnisse um bis zu 10 Punkte, da ihre Anleitung auf eine andere Version abzielte als die im Projekt verwendete.

Das passt zu dem, was die Architektur vorhersagen würde. Eine allgemeine Fähigkeit konkurriert mit dem, was das Modell bereits weiß, während eine sehr spezifische Fähigkeit genau den fehlenden Sachverhalt liefern kann:

When our generated API clients change, regenerate schemas before running typecheck.

Das hat Wert. Das hier hat viel weniger:

Always think carefully before modifying APIs.

Die Faustregel: Erstelle keine Fähigkeit nur, weil eine Aufgabe existiert. Erstelle sie, wenn es prozedurales Wissen gibt, das der Agent ständig übersieht.

Fähigkeiten benötigen Tests

Dies könnte der größte konzeptionelle Wandel sein. Da Änderungen in SKILL.md das Verhalten verändern, ähneln die Folgen Codeänderungen:

• Führt man eine Anweisung weg, könnte ein Agent eine erforderliche Überprüfung überspringen.
• Erweitert man die Beschreibung, könnte die Fähigkeit bei unzusammenhängender Arbeit aktiviert werden.
• Fügt man ein umfangreiches Referenzdokument hinzu, könnte der Tokenverbrauch steigen, ohne bessere Ergebnisse zu liefern.
• Schreibt man einen Ablauf um, könnten die Erfolgsraten sinken.

Teste sie daher. Für eine Fähigkeit, die Angular-Migrationen steuert, könnte ein Bewertungssatz beispielsweise eine Aufgabe wie folgt enthalten:

Upgrade application A from Angular 20 to Angular 21.

mit solchen Erwartungen:

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Eine zweite Aufgabe:

Upgrade a shared library consumed by applications A and B.

mit eigenen Erwartungen:

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

Und ein dritter Punkt:

Modify a React application in the same monorepo.

wobei das erwartete Ergebnis das Fehlen einer Aktivierung ist:

Expected:
- Angular migration skill is NOT activated

Jener letzte Fall zählt genauso viel wie jede erfolgreiche Ausführung, daher sollten beide Richtungen getestet werden: Die Fähigkeit sollte hier aktiviert werden und dort nicht. Ein Tool namens SkillGrade baut auf dieser Idee auf. Definieren Sie Aufgaben, führen Sie den Agenten wiederholt aus und bewerten Sie anschließend jede Ausführung mithilfe präziser Überprüfungen, einer durch ein LLM angewandten Bewertungskriterienliste für die aufgezeichnete Sitzung oder beidem zusammen. Sie können dieses Prinzip auch ohne dieses Tool anwenden. Der Schlüssel besteht darin, eine Fähigkeit als etwas zu betrachten, das sich verschlechtern kann. Ändern Sie eine Fähigkeit, ohne sagen zu können, ob die neue Version besser ist als die alte, dann bearbeiten Sie Logik in der Produktion, ohne sie getestet zu haben.

Beginnen Sie mit Fehlern, nicht mit einem Markt für Fähigkeiten

Der einfachste Weg, nutzlose Fähigkeiten zu erstellen, besteht darin, zu fragen, welche Fähigkeiten ein Programmieragent haben sollte. Dabei erhalten Sie eine Liste mit Themen wie Testing, Debugging, Code-Review, Dokumentation, Architektur, Git-Arbeitsabläufen, Barrierefreiheit, Sicherheit sowie weiteren zwanzig Themen, die das Modell bereits recht gut versteht.

Ein besseres Ausgangspunkt ist die eigene Historie des Agents. Suchen Sie nach wiederholten Fehlern. Vielleicht macht der Agent Folgendes:

• läuft den gesamten Testumfang in einem riesigen Monorepo aus anstelle sich auf das betroffene Projekt zu konzentrieren
• verletzt weiterhin die Abhängigkeitsgrenzen im Repository
• wählt den technisch korrekten Migrationsweg, übersieht aber einen internen Kompatibilitätsschritt
• bearbeitet generierte Dateien anstelle der Schemata, die sie erzeugen
• verbringt fünf Minuten damit, jedes Mal, wenn ein Service fehlschlägt, denselben Debugging-Prozess erneut durchzuführen

Das sind Anzeichen für fehlende Fähigkeiten. Der Lebenszyklus verläuft wie folgt: wiederholten Fehler beobachten, das fehlende prozedurale Wissen identifizieren, die kleinste nützliche Fähigkeit formulieren, deterministische Schritte in Skripte übertragen, repräsentative Bewertungsaufgaben erstellen, messen und anschließend die Fähigkeit beibehalten, verbessern oder löschen. Die Verbesserung führt wieder zurück zur Neuformulierung.

Achten Sie auf die letzte Option, denn das Löschen ist durchaus legitim. Eine Fähigkeit, die das Verhalten nicht verbessert, ist nicht harmlos – sie fügt Kontext hinzu, erhöht die Wartungskosten und bringt eine weitere Anweisung mit sich, die später möglicherweise zu Konflikten führen kann.

Die eigentliche Abstraktion ist der kontrollierte Kontext

Menschen beschreiben Fähigkeiten oft als Mittel, um Agenten zu erweitern. Das stimmt zwar, verdeckt aber ein interessanteres ingenieurtechnisches Problem: Informationen an einen Agenten zu liefern ist einfach – doch zu entscheiden, welche Informationen bei welcher Ausführung relevant werden, ist der schwierige Teil.

Eine gut gestaltete Agentenumgebung sieht weniger wie ein einziger riesiger Prompt aus und eher wie ein Softwaresystem mit Schichten. Immer vorhanden sind allgemeines Modellwissen sowie kleine globale Anweisungen. Nur dann werden hinzugezogen, wenn eine Aufgabe sie benötigt: fachspezifische Fähigkeiten, bedingungsweise geladene Referenzen, deterministische Werkzeuge sowie der Kontext des Laufzeit-Repositorys. Jede Schicht hat ihre eigene Aufgabe. Wenn diese Verantwortlichkeiten verschwimmen, wächst der Kontext übermäßig an, bis das Verhalten schwer nachvollziehbar wird. Wenn man sie trennt, werden die Fähigkeiten angenehm langweilig – was gut ist.

Eine gute Fähigkeit ist kein auffälliger Prompt. Es handelt sich dabei um ein kompaktes Stück prozeduralen Wissens, das in der richtigen Situation zum Einsatz kommt, dort, wo möglich, auf deterministische Werkzeuge zurückgreift und gegen die Fehler überprüft wird, die es verhindern soll.