Skills auslagern – wie meine Agenten schlank bleiben, wenn das Projektwissen wächst

In Post 16 habe ich am Ende eine Tür offen gelassen. Der Abschnitt hieß „Optional: Agenten mit Skills erweitern", war knapp vier Absätze lang, und ich habe ihn bewusst dort abgebrochen, weil es beim Anlegen von Agenten erst einmal um die Rolle geht – nicht um das Spezialwissen.

Diesen Post schreibe ich, weil aus dem „optional" inzwischen ein fester Bestandteil meines Setups geworden ist. Nicht, weil ein neuer Standard veröffentlicht wurde, sondern weil mich meine eigenen Agenten-Dateien dazu gezwungen haben.

Der Auslöser war unspektakulär: Mein Solution-Architect-Agent aus Post 12 war nach ein paar Monaten Projektarbeit kein sauber geschnittener Agent mehr, sondern eine Halde. Bei jedem Durchlauf, in dem etwas nicht passte, habe ich eine Regel nachgezogen – wie ein Sequenzdiagramm aufgebaut sein soll, welche Abschnitte ein Lösungskonzept braucht, wie ich Content-Datumsformate behandelt haben will, warum er die v3-API des Content-Layers nutzen muss und nicht die v2-Syntax. Jede einzelne dieser Regeln war berechtigt. Zusammen ergaben sie eine Rollenbeschreibung, die niemand mehr überblickt hat – ich nicht und der Agent offensichtlich auch nicht, denn genau die Regeln aus der Mitte der Datei wurden am zuverlässigsten ignoriert.

Zwei Dinge vorweg, damit der Rahmen klar ist:

Erstens: Skills lösen ein Kontextproblem, kein Qualitätsproblem. Sie machen einen Agenten nicht klüger und keinen generierten Code korrekter. Sie sorgen nur dafür, dass das richtige Wissen zum richtigen Zeitpunkt im Kontext liegt – und der Rest eben nicht. Das ist weniger, als der Hype verspricht, und mehr, als es klingt.

Zweitens: Das ist ein Dateiformat, kein Paradigmenwechsel. Ein Skill ist eine Markdown-Datei mit ein bisschen YAML davor. Wer davon eine neue Ära erwartet, wird enttäuscht. Wer die Idee dahinter unterschätzt, schleppt weiter Prompt-Monster mit sich herum.

Wie aus einem Agenten ein Prompt-Monster wird

Das Muster ist immer dasselbe, und ich halte es für den Normalfall, nicht für meinen persönlichen Fehler: Ein Agent startet schlank und gut geschnitten. Dann trifft er auf die Realität eines konkreten Projekts. Er macht etwas falsch, man ergänzt eine Regel. Er macht etwas anderes falsch, man ergänzt die nächste. Nach zwanzig Iterationen ist die Rollenbeschreibung ein Sediment aus Korrekturen – und das Problem daran ist nicht die Dateigröße, sondern was mit diesem Text im Modell passiert.

Denn ein Systemprompt ist kein Regelwerk, das abgearbeitet wird. Er ist Kontext, der mit allem anderen um Aufmerksamkeit konkurriert. Die Chroma-Untersuchung „Context Rot: How Increasing Input Tokens Impacts LLM Performance" hat das über 18 aktuelle Modelle hinweg gemessen: Mit wachsender Eingabelänge sinkt die Zuverlässigkeit nicht linear und schon lange bevor das Kontextfenster ausgeschöpft ist. Das große Kontextfenster auf dem Datenblatt sagt eben nichts darüber aus, wie gut ein Modell über die volle Länge zuhört.

Der praktische Effekt hat einen Namen: Instruction Drift. Anweisungen, die weit oben im Kontext stehen, werden mit zunehmender Gesprächslänge unzuverlässiger befolgt. Genau das habe ich beobachtet – Regel drei aus meiner Agenten-Datei saß, Regel siebzehn war ein Vorschlag.

Wie viel Kontext allein durch mitgeschlepptes Werkzeugwissen entsteht, hat Anthropic in „Code execution with MCP" an einem Beispiel durchgerechnet: Ein Workflow, der alle Tool-Definitionen und Zwischenergebnisse in den Kontext lud, brauchte rund 150.000 Token; dieselbe Aufgabe mit bedarfsgesteuertem Nachladen kam mit etwa 2.000 aus. Das sind 98,7 Prozent weniger – für dasselbe Ergebnis. Die Zahl bezieht sich auf MCP-Tools und nicht auf Skills, aber das zugrunde liegende Prinzip ist identisch: Das Teuerste am Kontext ist das, was man mitschleppt, ohne es zu brauchen.

Ich hatte in Post 17 schon geschrieben, dass MCPs den Token-Verbrauch spürbar erhöhen. Das hier ist dieselbe Rechnung von der anderen Seite – nur, dass es diesmal nicht die externen Daten sind, die ins Fenster wandern, sondern mein eigenes Projektwissen.

Was ein Skill technisch wirklich ist

Die gute Nachricht: Das Konzept ist erfreulich unspektakulär. Ein Skill ist ein Ordner mit einer SKILL.md – YAML-Frontmatter für die Metadaten, Markdown für die Anleitung. Optional liegen daneben Skripte, Referenzdokumente oder Vorlagen. Kein Framework, keine API, keine Registry-Pflicht.

Anthropic hat das Format im Oktober 2025 zunächst für Claude eingeführt und in „Equipping agents for the real world with Agent Skills" beschrieben – zwei Monate später, im Dezember 2025, folgte die Freigabe als offener Standard samt Spezifikation unter agentskills.io. Der Grund, warum ich es überhaupt ernst nehme, ist genau diese Öffnung: Dieselbe Skill-Datei funktioniert heute unter anderem in Claude Code, GitHub Copilot und VS Code, Cursor, OpenAI Codex, Gemini CLI, JetBrains Junie und OpenCode. Für mein Setup aus Post 16 – Claude Code und GitHub Copilot parallel – ist das der eigentliche Gewinn: Ich pflege das Projektwissen einmal, nicht zweimal in zwei Dialekten.

So sieht einer meiner Skills aus – genau die Sequenzdiagramm-Regel, die vorher in der Agenten-Datei stand:

---
name: usecase-sequenzdiagramm
description: Erstellt Mermaid-Sequenzdiagramme für Use-Case-Dokumente unter docs/usecases/. Nutzen, wenn ein Use Case dokumentiert, ergänzt oder überarbeitet wird.
---

# Sequenzdiagramm für Use-Case-Dokumente

## Ablauf
1. Hauptablauf des Use Case in nummerierte Schritte zerlegen.
2. Pro Schritt genau einen Pfeil zwischen zwei Teilnehmern zeichnen.
3. Alternativflüsse als `alt`/`else`-Block, Fehlerfälle als `opt`-Block.
4. Diagramm unterhalb des Hauptablaufs einfügen, nie davor.

## Verbindliche Konventionen
- Teilnehmer immer in dieser Reihenfolge: Nutzer, UI, Composable, Content-Layer.
- Deutsche Beschriftungen, kein Denglisch ("Lädt Beitrag", nicht "Loads Post").
- Keine Implementierungsdetails auf den Pfeilen – fachliche Schritte, keine Methodennamen.

## Anti-Patterns
- Kein Diagramm ohne vorher definierten Hauptablauf.
- Keine Teilnehmer, die im Use-Case-Text nicht vorkommen.

Der entscheidende Mechanismus dahinter heißt Progressive Disclosure und läuft in drei Stufen ab:

Beim Start des Agenten landen ausschließlich Name und Beschreibung jedes Skills im Kontext – gerade genug, damit das Modell weiß, dass es das Werkzeug gibt. Erst wenn eine Aufgabe zur Beschreibung passt, wird die vollständige SKILL.md geladen. Referenzdateien und Skripte kommen noch eine Stufe später dazu, nur falls die Anleitung sie tatsächlich braucht.

Das ist im Kern dasselbe Prinzip, das ich in dieser Serie ohnehin permanent verfolge: Der Agent bekommt nicht alles auf einmal, sondern das, was für den aktuellen Schritt zählt. Bei den Realisierungsplan-Schritten aus Post 13 portioniere ich die Arbeit, hier portioniere ich das Wissen.

Agent, Skill, Regel-Datei, MCP – wer macht eigentlich was?

Diese Frage habe ich mir länger stellen müssen, als ich zugeben möchte. Inzwischen wurde in der Serie eine ganze Reihe von Mechanismen aufgebaut, die alle irgendwie „dem Agenten etwas beibringen" – und wenn man sie nicht sauber trennt, landet dieselbe Regel am Ende an drei Stellen. Für mich sortiert sich das so:

Die Trennlinie, die mir in der Praxis am meisten hilft, verläuft zwischen den letzten beiden Zeilen: Ein Skill liefert Wissen, ein MCP liefert Daten. Wie ein Sequenzdiagramm aufgebaut sein soll, ändert sich vielleicht zweimal im Jahr und gehört versioniert ins Repository – das ist ein Skill. Welche Felder eine Appwrite-Collection gerade hat, ändert sich beim nächsten Deployment und muss zur Laufzeit abgefragt werden – das ist ein MCP.

Und die Trennlinie zwischen Agent und Skill ist die zwischen Identität und Prozedur. Der Business Analyst bleibt der Business Analyst, egal ob er gerade ein Sequenzdiagramm zeichnet oder Akzeptanzkriterien formuliert. Die Anleitung für das Diagramm braucht aber auch der Solution Architect – und spätestens da gehört sie nicht mehr in eine Rollenbeschreibung, sondern daneben.

Meine Regeln fürs Schneiden

Der schwierige Teil an Skills ist nicht die Syntax, sondern die Frage, was überhaupt einer werden soll. Vier Regeln haben sich bei mir herauskristallisiert.

Erst beim zweiten Mal. Ich lege keinen Skill an, weil ein Wissen theoretisch wiederverwendbar wäre. Ich lege ihn an, wenn ich dieselbe Anweisung zum zweiten Mal in eine zweite Agenten-Datei kopiere. Das ist exakt die DRY-Schwelle, die ich auch im Code anwende – vorher ist es keine Abstraktion, sondern Vorratshaltung.

Die Beschreibung ist die eigentliche Schnittstelle. Das habe ich unterschätzt. In Stufe 1 sieht das Modell nichts als name und description – die Beschreibung ist also das Einzige, worauf die Entscheidung „laden oder nicht" beruht. Eine vage Beschreibung wie „hilft bei Diagrammen" wird nie zuverlässig getroffen. Ich schreibe deshalb immer explizit dazu, wann der Skill zu nutzen ist, nicht nur, was er kann. Ein Skill, den niemand findet, ist ein Skill, den es nicht gibt.

Prozedur statt Prosa. Meine ersten Skills waren erklärende Texte – und die haben schlecht funktioniert. Was funktioniert, sind nummerierte Schritte, harte Konventionen und ein Abschnitt mit Anti-Patterns. Dieselbe Erkenntnis wie beim Realisierungsplan aus Post 13: Ein Agent führt eine Prozedur zuverlässiger aus, als er eine Erklärung interpretiert.

Skills gehören ins Repository. Sie liegen bei mir versioniert neben dem Code, nicht in einer globalen Konfiguration auf meinem Rechner. Damit sind sie im Diff sichtbar, sie gelten für jeden – auch für einen Agenten in der CI – und sie sterben mit dem Projekt, statt in meiner Werkzeugkiste zu verrotten.

Ganz nebenbei liefern Bibliotheken das inzwischen selbst mit. FormKit positioniert sich mittlerweile ausdrücklich als „form framework for coding agents" und richtet mit einem einzigen Befehl – npx formkit skill – den passenden Skill für Claude Code, Codex, Cursor, Cline, Gemini oder OpenCode ein, inklusive Framework-Erkennung. Für die Bibliotheken, die das anbieten, ist das der schnellste Weg zu einem Agenten, der die API nicht halluziniert, sondern kennt.

Der Gegenwind: Skills sind nicht die Antwort auf alles

Und jetzt der Teil, den ich beim Recherchieren am interessantesten fand – weil er meiner eigenen Begeisterung widerspricht.

Justin Schroeder, der Kopf hinter FormKit, argumentiert in seinem Talk „The Future Is Domain-Specific Agents" nämlich gerade nicht dafür, einen Agenten mit Skills auszustatten. Er stellt zwei Architekturen gegenüber: Den einen Agenten, dessen Kontext man mit Tools, Skills und MCP-Servern immer weiter aufbläht – Inheritance – gegen viele kleine, spezialisierte Sub-Agenten, die von einem Orchestrator koordiniert werden – Composition. Für die zweite Variante nennt er Token-Effizienzgewinne von über 80 Prozent, die Möglichkeit, deutlich kleinere und billigere Modelle einzusetzen, und harte Fähigkeitsgrenzen als Sicherheitsvorteil. Seine Prognose: Domänenspezifische Agenten werden bis Ende 2026 zum Normalfall, 2027 wird das Jahr der Multi-Agenten-Orchestrierung – getrieben von steigenden Token-Kosten.

In dieser Lesart sind Skills also Teil des Problems und nicht die Lösung.

Ich halte den Widerspruch für auflösbar, und zwar so: Wer nur einen Agenten hat und ihn mit dreißig Skills zum Universalgenie machen will, verlagert das Problem lediglich eine Ebene tiefer. Denn die Beschreibungen aller dreißig Skills liegen bei jedem Start im Kontext – und die Auswahlentscheidung wird mit jedem weiteren Eintrag unschärfer. Progressive Disclosure verschiebt die Grenze nach oben, sie schafft sie nicht ab.

Das eigentliche Muster ist also: erst schneiden, dann auslagern. Genau deshalb passt es für mich zusammen – mein Setup aus Post 12 bis Post 14 ist bereits die Komposition, die Schroeder meint: fünf spezialisierte Rollen mit klaren Grenzen statt eines Alleskönners. Die Skills sitzen innerhalb dieser Aufteilung und lösen dort ein anderes Problem – nämlich, dass sich Spezialwissen über mehrere dieser Rollen hinweg wiederholt. Wären meine Agenten nicht sauber geschnitten, würden Skills diesen Fehler nicht heilen, sondern nur bequemer machen.

Ein ehrlicher Punkt: Was Skills nicht lösen

Skills machen aus einem probabilistischen Modell kein deterministisches System. Das klingt banal, ist aber die Grenze, die ich am häufigsten überschätzt gesehen habe.

Ein Skill ist eine Anweisung, keine Garantie. Ob er geladen wird, entscheidet das Modell anhand einer Textbeschreibung. Ob die geladene Anleitung dann Schritt für Schritt befolgt wird, entscheidet dasselbe Modell. Es gibt keinen Compiler, der einen Skill-Verstoß meldet. Damit gilt hier exakt das, was ich in Post 19 über den Unterschied zwischen Leitplanken und Absichtserklärungen geschrieben habe: Verlässlich wird eine Regel erst, wenn sie deterministisch geprüft wird – durch Typen, Linter, Tests, eine CI-Stufe.

Und der zweite ehrliche Punkt: Skills lösen nichts von dem, worum es in dieser Serie eigentlich geht. Sie ersetzen keinen Use Case, kein Lösungskonzept und keinen Human-in-the-Loop-Checkpoint. Ein perfekt ausgestatteter Agent, der die falsche Anforderung umsetzt, baut lediglich sehr konventionskonformen Unsinn.

Fazit

Skills haben für mich ein Problem gelöst, das ich lange für ein Naturgesetz gehalten habe: dass Agenten-Dateien mit der Projektlaufzeit zwangsläufig zu Halden werden. Das müssen sie nicht. Die Rolle bleibt klein und stabil, das Spezialwissen wandert nach draußen und wird bei Bedarf geholt – und wenn ich eine Konvention ändere, fasse ich eine Datei an statt fünf Rollenbeschreibungen.

Was ich mir dabei nicht einrede: Das ist eine Aufräum- und Wartbarkeitsverbesserung, keine Qualitätsrevolution. Meine Agenten sind dadurch nicht klüger geworden, sie sind nur weniger vergesslich. Und der Talk von Justin Schroeder ist eine gesunde Erinnerung daran, dass die Antwort auf einen überladenen Agenten manchmal nicht „bessere Skills" heißt, sondern schlicht „zwei Agenten".

Am Ende ist es dieselbe Frage wie im Code: Wo schneide ich, und was gehört zusammen? Dass diese Frage jetzt auch für Prompts gilt, finde ich eher beruhigend – es ist eine Disziplin, die wir als Entwickler schon können, nur auf einem neuen Material.

Wie handhabt ihr das? Steckt euer Projektwissen in einer großen Regel-Datei, in den Agenten selbst oder schon in ausgelagerten Skills – und habt ihr den Punkt erlebt, an dem eine Agenten-Datei zu groß wurde, um noch zu wirken? Das würde mich ehrlich interessieren.