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 weiß, 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 verlässlicher, sondern schwerer berechenbar.

Die relevante ag3nt.id-Lesart ist: Skills sind nicht Dokumentation für Menschen. Sie sind Betriebsoberfläche für Agenten.

Ein Skill ist kein Wissensspeicher

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

Man schreibt alles hinein, was später vielleicht nützlich sein könnte: Regeln, Beispiele, Randfälle, Referenzen, Erinnerungen, Ausnahmen, Wunschverhalten, Sicherheitsnotizen. Das fühlt sich gründlich an. Für 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 Maßstab. Nicht: "Ist die Information vollständig?" Sondern: "Ändert 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 für den Nutzer, erhöht aber Kontextlast und Risiko: Der Agent kann einen passenden Skill übersehen 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 müssen model-invoked sein, weil Nutzer gar nicht wissen können, 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 führen. Er muss sagen, welche Schritte der Agent ausführt, worauf er achten soll und wann er tieferes Material laden muss.

Referenzmaterial gehört 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 überladenen Checkliste, nicht zur Führung.

Ein besseres Muster:

• SKILL.md enthält den Kernablauf.
• Spezifische Varianten liegen in separaten Referenzen.
• Der Agent lädt 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 Modularität hübsch ist, sondern weil Agenten mit begrenztem Aufmerksamkeitsbudget arbeiten.

Steering: Verhalten braucht führende Begriffe

Der dritte Punkt ist Steering.

Viele Skill-Dateien beschreiben Wunschverhalten, ohne den Agenten wirklich zu lenken. Sie sagen sinngemäß: "Mach es gut, gründlich und sinnvoll." Das klingt vernünftig, ist aber zu weich.

Agenten reagieren stark auf wiedererkennbare Leitbegriffe.

Solche Begriffe komprimieren Bedeutung. Sie geben dem Modell einen stabilen Griff für Verhalten: erst Kontext sammeln, dann entscheiden; erst Quelle prüfen, 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 "gründlich", "sicher" oder "fertig" bedeutet. Die Begriffe werden zu Verhaltenstriggern.

Noch wichtiger: Komplexe Abläufe müssen nicht immer komplett sichtbar sein.

Wenn ein Agent zu früh zum nächsten Schritt springt, kann es sinnvoll sein, zukünftige Schritte hinter separaten Skills oder Referenzen zu verstecken. Der Agent bekommt dann erst den nächsten Kontext, wenn die aktuelle Phase abgeschlossen ist.

Das ist Prozessdesign für Denkmaschinen.

Pruning: Löschen ist Architekturarbeit

Der vierte Punkt ist Pruning.

Skills altern.

Sie sammeln Sediment: alte Regeln, doppelte Warnungen, Sonderfälle, die niemand mehr braucht, Abschnitte, die gut klingen, aber kein Verhalten ändern.

Genau hier wird Löschen zur ernsthaften Agentenarbeit.

Pococks "Deletion Test" ist dafür ein guter Maßstab: 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 für 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 längste 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 Modellfähigkeit
• Unternehmenskontext
• Tool-Zugriff
• Governance
• Ausführungslogik
• menschlicher Erwartung

Wer Skills gut schreibt, baut nicht nur bessere Prompts. Er baut eine wiederverwendbare Operations-Schicht für 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 dafür ein brauchbares Raster:

• Trigger entscheidet, wann ein Skill überhaupt 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 nächste Agentenphase wird nicht nur durch bessere Modelle gewonnen.

Sie wird durch bessere Arbeitsoberflächen für Modelle gewonnen.

Gute Skills machen Agenten nicht allwissend. Sie machen sie führbar, prüfbar und wartbar. Genau darin liegt ihr Wert.

Ein Skill ist fertig, wenn er nicht mehr beeindruckend viel erklärt, sondern verlässlich das richtige Verhalten auslöst.

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