Das Missing Manual für Agent Skills

Viele Agentenprojekte scheitern nicht daran, dass das Modell zu schwach ist.

Sie scheitern daran, dass der Agent nicht weiss, wann er welches Wissen benutzen soll, wie er arbeiten soll und welche Teile seiner Anleitung wirklich Verhalten steuern.

Das klingt klein. Es ist aber eine der wichtigsten Architekturfragen in agentischen Systemen.

Matt Pocock beschreibt dieses Problem in seinem Video "The Missing Manual: How to Write Great AI Skills" als eine Art Skill Hell: Skills wachsen, wiederholen sich, laden zu viel Kontext, steuern zu wenig Verhalten und machen Agenten am Ende nicht verlaesslicher, sondern schwerer berechenbar.

Die relevante ag3nt.id-Lesart ist: Skills sind nicht Dokumentation fuer Menschen. Sie sind Betriebsoberflaeche fuer Agenten.

Ein Skill ist kein Wissensspeicher

Der naheliegende Fehler ist, Skills wie kleine Wikis zu behandeln.

Man schreibt alles hinein, was spaeter vielleicht nuetzlich sein koennte: Regeln, Beispiele, Randfaelle, Referenzen, Erinnerungen, Ausnahmen, Wunschverhalten, Sicherheitsnotizen. Das fuehlt sich gruendlich an. Fuer einen Agenten ist es oft Ballast.

Ein guter Skill ist nicht der Ort, an dem alles steht.

Ein guter Skill ist der Ort, der den Agenten in die richtige Handlung bringt.

Das ist ein anderer Massstab. Nicht: "Ist die Information vollstaendig?" Sondern: "Aendert diese Information das Verhalten im richtigen Moment?"

Diese Frage entscheidet, ob ein Skill ein Werkzeug ist oder nur Kontextnebel.

Trigger: Wer entscheidet, dass ein Skill gilt?

Der erste Architekturpunkt ist der Trigger.

Ein Skill kann vom Nutzer explizit aufgerufen werden. Oder das Modell entscheidet selbst, ob der Skill zum aktuellen Kontext passt.

Beides hat Kosten.

Ein nutzeraktivierter Skill ist vorhersagbarer. Er belastet den Nutzer aber mit der Entscheidung: Welcher Skill ist jetzt der richtige?

Ein modellaktivierter Skill wirkt eleganter. Er verschiebt die Entscheidung zum Agenten. Das spart kognitive Last fuer den Nutzer, erhoeht aber Kontextlast und Risiko: Der Agent kann einen passenden Skill uebersehen oder einen unpassenden laden.

Damit wird Trigger-Design zu einer Produktfrage.

Nicht jeder Skill sollte automatisch im Suchraum des Modells liegen. Manche Skills sind besser als klare Befehle. Andere muessen model-invoked sein, weil Nutzer gar nicht wissen koennen, dass sie gebraucht werden.

Die Disziplin besteht darin, diese Entscheidung bewusst zu treffen.

Structure: SKILL.md klein halten

Der zweite Punkt ist Struktur.

Pococks Empfehlung ist einfach und stark: Trenne Steps von Reference.

Der Hauptskill sollte den Ablauf fuehren. Er muss sagen, welche Schritte der Agent ausfuehrt, worauf er achten soll und wann er tieferes Material laden muss.

Referenzmaterial gehoert dahinter.

Das ist mehr als Ordnungsliebe. Es ist Context Engineering.

Wenn jede Verzweigung, jede Ausnahme und jeder Spezialfall direkt in der Hauptdatei steht, muss der Agent alles gleichzeitig tragen. Das macht ihn teurer, langsamer und oft schlechter. Der Skill wird dann zur ueberladenen Checkliste, nicht zur Fuehrung.

Ein besseres Muster:

• SKILL.md enthaelt den Kernablauf.
• Spezifische Varianten liegen in separaten Referenzen.
• Der Agent laedt diese Referenzen erst, wenn der konkrete Fall es verlangt.
• Der Hauptskill bleibt klein genug, um wirklich steuernd zu wirken.

Damit wird ein Skill modular. Nicht, weil Modularitaet huebsch ist, sondern weil Agenten mit begrenztem Aufmerksamkeitsbudget arbeiten.

Steering: Verhalten braucht fuehrende Begriffe

Der dritte Punkt ist Steering.

Viele Skill-Dateien beschreiben Wunschverhalten, ohne den Agenten wirklich zu lenken. Sie sagen sinngemaess: "Mach es gut, gruendlich und sinnvoll." Das klingt vernuenftig, ist aber zu weich.

Agenten reagieren stark auf wiedererkennbare Leitbegriffe.

Solche Begriffe komprimieren Bedeutung. Sie geben dem Modell einen stabilen Griff fuer Verhalten: erst Kontext sammeln, dann entscheiden; erst Quelle pruefen, dann schreiben; erst Scope begrenzen, dann implementieren.

Das ist kein magisches Prompting. Es ist Betriebssemantik.

Wenn ein Team dieselben Begriffe konsistent benutzt, entsteht eine kleine gemeinsame Sprache zwischen Mensch, Agent und System. Der Agent muss nicht jedes Mal neu erraten, was "gruendlich", "sicher" oder "fertig" bedeutet. Die Begriffe werden zu Verhaltenstriggern.

Noch wichtiger: Komplexe Ablaeufe muessen nicht immer komplett sichtbar sein.

Wenn ein Agent zu frueh zum naechsten Schritt springt, kann es sinnvoll sein, zukuenftige Schritte hinter separaten Skills oder Referenzen zu verstecken. Der Agent bekommt dann erst den naechsten Kontext, wenn die aktuelle Phase abgeschlossen ist.

Das ist Prozessdesign fuer Denkmaschinen.

Pruning: Loeschen ist Architekturarbeit

Der vierte Punkt ist Pruning.

Skills altern.

Sie sammeln Sediment: alte Regeln, doppelte Warnungen, Sonderfaelle, die niemand mehr braucht, Abschnitte, die gut klingen, aber kein Verhalten aendern.

Genau hier wird Loeschen zur ernsthaften Agentenarbeit.

Pococks "Deletion Test" ist dafuer ein guter Massstab: Wenn ein Abschnitt entfernt wird und sich das Agentenverhalten nicht verschlechtert, war der Abschnitt wahrscheinlich ein No-op.

Das ist unangenehm, weil No-ops oft wie Verantwortung aussehen.

Aber fuer Agenten ist nutzloser Text nicht neutral. Er verbraucht Kontext. Er konkurriert mit wichtigen Regeln. Er macht Entscheidungen diffuser.

Ein gepflegter Skill ist deshalb nicht der laengste Skill. Es ist der Skill, bei dem jeder Absatz eine Aufgabe hat.

Die ag3nt.id-Lesart

Agent Skills sind die neue mittlere Schicht zwischen Modell und Betrieb.

Sie sitzen zwischen:

• roher Modellfaehigkeit
• Unternehmenskontext
• Tool-Zugriff
• Governance
• Ausfuehrungslogik
• menschlicher Erwartung

Wer Skills gut schreibt, baut nicht nur bessere Prompts. Er baut eine wiederverwendbare Operations-Schicht fuer Agenten.

Das ist besonders wichtig, sobald Agenten nicht nur antworten, sondern arbeiten: Repos anfassen, Tickets triagieren, Daten auswerten, Dokumente erstellen, Systeme bedienen, Entscheidungen vorbereiten.

Dann reicht "gib dem Modell mehr Kontext" nicht mehr.

Der Kontext muss eine Form haben.

Trigger, Structure, Steering und Pruning sind dafuer ein brauchbares Raster:

• Trigger entscheidet, wann ein Skill ueberhaupt in den Lauf kommt.
• Structure entscheidet, wie viel Kontext sofort sichtbar ist.
• Steering entscheidet, welches Verhalten stabil wiederholt wird.
• Pruning entscheidet, ob der Skill mit der Zeit besser oder schwerer wird.

Fazit

Die naechste Agentenphase wird nicht nur durch bessere Modelle gewonnen.

Sie wird durch bessere Arbeitsoberflaechen fuer Modelle gewonnen.

Gute Skills machen Agenten nicht allwissend. Sie machen sie fuehrbar, pruefbar und wartbar. Genau darin liegt ihr Wert.

Ein Skill ist fertig, wenn er nicht mehr beeindruckend viel erklaert, sondern verlaesslich das richtige Verhalten ausloest.

Quelle: The Missing Manual: How to Write Great AI Skills von Matt Pocock / AI Engineer.