Skills für AI-Agenten: Wiederkehrende Aufgaben einmal richtig aufsetzen

Du beschreibst deinem Coding-Agenten ein Feature, er legt los, und zwanzig Minuten später steht etwas da, das funktioniert – nur eben nicht ganz so, wie du es dir vorgestellt hattest. Ein Detail fehlt, eine Konvention wurde ignoriert, ein Sonderfall gar nicht bedacht. Also erklärst du nach. Beim nächsten Feature erklärst du dasselbe noch einmal.

Genau an dieser Stelle setzen Skills an. Ein Skill ist nichts weiter als eine Textdatei, in der du einmal sauber beschreibst, wie eine bestimmte Art von Aufgabe bei dir abzulaufen hat. Der Agent liest sie, wenn sie relevant ist, und arbeitet danach.

Folge 007 von Kontext.FM dreht sich genau darum: Trutz hat sich einen eigenen Satz Skills für den Entwicklungsprozess bei AMALYTIX gebaut, Kai nutzt Skills für Dinge, die mit Code überhaupt nichts zu tun haben. Dieser Artikel fasst zusammen, was dabei herauskam – und wie du selbst anfängst.

Das Problem: Alles auf einmal, in einer Session

Ein Agent liefert immer ab. Er sagt nie „das habe ich nicht verstanden“ oder „das kann ich nicht“. Er setzt um, was du ihm gesagt hast. Wenn deine Anforderung unklar ist, ist das Ergebnis entsprechend unklar – und das merkst du oft erst am Ende.

Dazu kommt ein zweites Problem: das Kontextfenster. Moderne Modelle verarbeiten bis zu einer Million Tokens, aber je voller der Kontext wird, desto unzuverlässiger wird der Bezug auf das, was ganz am Anfang besprochen wurde. Eine Anforderung aus Minute drei ist nach zwei Stunden Implementierung nicht mehr gleich präsent. In der Praxis heißt das: Ein Feature komplett „one-shotten“ zu wollen, funktioniert bei allem, was über eine überschaubare Änderung hinausgeht, eher schlecht.

Beide Probleme haben dieselbe Lösung: den Prozess in Phasen zerlegen, jede Phase mit einem klaren Artefakt abschließen, und jede Phase in einer frischen Session starten – mit dem Artefakt der Vorstufe als Einstieg. Skills sind das Werkzeug, mit dem du diese Phasen festschreibst.

Was ein Skill technisch ist

Ein Skill ist ein Ordner mit einer Datei namens SKILL.md. Ganz oben stehen ein paar Zeilen YAML-Frontmatter, darunter die eigentliche Anleitung in Markdown:

---
name: explore
description: Verfeinert eine grobe Feature-Idee zu einem
  vollständigen Anforderungsdokument. Nutzen, wenn eine neue
  Idee spezifiziert werden soll, bevor geplant wird.
---

Der Nutzer hat eine grobe Idee im Kopf, die noch nicht zu Ende
gedacht ist. Deine Aufgabe ist es, sie zu schärfen – nicht,
sie umzusetzen.

1. Verschaffe dir einen Überblick: Welche Bereiche der App sind
   betroffen? Gibt es vergleichbare Features?
2. Stelle Rückfragen zu allem, was die Umsetzung grundlegend
   verändern würde – vor allem zu Edge Cases aus Nutzersicht.
   Frage nicht jedes Detail ab. Wo eine Entscheidung später
   leicht änderbar ist, triff eine sinnvolle Annahme und
   dokumentiere sie.
3. Schreibe das Ergebnis nach `ax-spec/<feature>/prd.md`.

Schreibe keinen Code. Beschreibe keine technische Umsetzung.

Mehr ist es im Kern nicht. Die entscheidende Zeile ist die description: Sie steht dauerhaft im Kontext des Agenten, während der eigentliche Inhalt erst geladen wird, wenn der Skill zum Einsatz kommt. Der Agent entscheidet anhand dieser Beschreibung selbst, ob ein Skill zur aktuellen Aufgabe passt.

Das ist der Punkt, der Skills von einem gespeicherten Prompt unterscheidet: Du musst sie nicht aufrufen. Du kannst – in Claude Code tippst du /explore, und der Ordnername wird zum Kommando. Du kannst aber genauso gut einfach schreiben, was du willst, und der Agent greift zum passenden Skill. Kai beschreibt das im Podcast an einem Beispiel aus dem Vertrieb: Er tippt „bereite Termin mit Firma X und Person Y zum Thema Z vor“, und Claude findet von selbst den Skill „Akquise-Termin vorbereiten“.

Im Ordner kann neben der SKILL.md noch mehr liegen: Vorlagen, Beispiel-Outputs, Referenzdokumente, ausführbare Skripte. Du verweist in der SKILL.md darauf, und der Agent lädt sie, wenn er sie braucht.

explore/
├── SKILL.md          # Hauptanleitung (erforderlich)
├── prd-template.md   # Vorlage für das Anforderungsdokument
└── beispiele/
    └── gutes-prd.md  # Referenz für das erwartete Format

Claude Code folgt dabei dem offenen Agent-Skills-Standard, der auch von anderen Werkzeugen unterstützt wird. Die volle Feldliste steht in der Claude-Code-Dokumentation zu Skills.

Projekt oder global: Wo ein Skill liegen sollte

Skills können an zwei für dich relevanten Stellen liegen:

Ort	Pfad	Gilt für
Persönlich	~/.claude/skills/<name>/SKILL.md	alle deine Projekte
Projekt	.claude/skills/<name>/SKILL.md	nur dieses Projekt

Die Faustregel ergibt sich fast von selbst: Ein Skill, der die Eigenheiten eines bestimmten Projekts kennt, gehört ins Projekt – und damit auch ins Repository, wo das ganze Team ihn nutzt. Genau das macht Trutz mit seinen Entwicklungs-Skills: Sie beschreiben den AMALYTIX-Prozess und wären anderswo wertlos.

Etwas, das überall gleich funktioniert – ein bestimmtes Ausgabeformat, eine Recherchemethode, dein Schreibstil – gehört in den persönlichen Ordner.

Der wichtigste Effekt der Projekt-Variante: Du kannst dort Wissen hinterlegen, das der Agent sonst jedes Mal von dir hören müsste. Bei AMALYTIX zum Beispiel gilt, dass jedes neue Feature nicht nur in der Benutzeroberfläche verfügbar sein muss, sondern auch für den eingebauten Agenten. Steht das im Skill, muss es niemand mehr dazusagen.

Die Skill-Kette: von der Idee zum fertigen Feature

Der interessante Teil ist nicht der einzelne Skill, sondern die Verkettung. Jede Phase produziert eine Datei, und diese Datei ist der einzige Kontext, den die nächste Phase erbt. Alles andere – die Sackgassen, die verworfenen Ansätze, das Hin und Her – bleibt zurück.

Phase 1: Explore – die Idee ausformulieren

Der erste Skill macht noch nichts Technisches. Er nimmt deine vage Idee und stellt so lange Rückfragen, bis daraus eine belastbare Anforderung geworden ist. Was soll aus Nutzersicht passieren? Was passiert in den Randfällen? Was passiert ausdrücklich nicht?

Das klingt nach einer Kleinigkeit, ist aber der Schritt mit dem größten Hebel. Vieles davon hast du implizit im Kopf – der Agent hat es nicht. Und: Er kann das Ausformulieren besser als du, wenn du ihn lässt. Trutz nutzt für diese Phase manchmal ein Transkriptionstool und redet einfach unstrukturiert ins Mikrofon; das Strukturieren übernimmt der Agent.

Die Idee des ausdauernden Nachfragens stammt vom „Grill me“-Ansatz aus den Skills von Matt Pocock. Wichtig ist die Dosierung: Ein Skill, der vier Stunden lang jedes Detail abfragt, ist genauso unbrauchbar wie einer, der gar nichts fragt. Schreib in den Skill hinein, wo die Grenze liegt – wichtige Dinge fragen, für den Rest eine gute Annahme treffen.

Ergebnis: prd.md – das Anforderungsdokument.

Phase 2: Plan – die technische Umsetzung zerlegen

Neue Session, leerer Kontext. Der Plan-Skill bekommt das prd.md und übersetzt es in technische Schritte: Datenmodell, Backend, Frontend, Migrationen. Daraus entstehen eine To-do-Liste und einzelne Task-Beschreibungen.

Der Zuschnitt der Tasks ist entscheidend. Jede Task-Datei sollte für sich stehen und alle Informationen enthalten, die für ihre Umsetzung nötig sind – denn sie wird gleich isoliert abgearbeitet.

Ergebnis: plan.md, todo.md, tasks/01-….md, tasks/02-….md, …

Phase 3: Tasks – Schritt für Schritt umsetzen

Jede Task läuft in einer eigenen frischen Session. Der Agent liest die Task-Beschreibung, bei Bedarf auch prd.md und plan.md, und setzt um.

Damit die Kette nicht auseinanderfällt, braucht der Skill zwei Pflichten am Ende jeder Task:

• Logbuch schreiben. Der Agent notiert in der Task-Datei, was er tatsächlich gebaut hat – nicht, was geplant war. Das ist der Unterschied, der die nächste Task rettet, wenn während der Umsetzung von der Planung abgewichen wurde.
• To-do-Liste aktualisieren. Damit ist der Stand jederzeit ohne Session-Historie ablesbar.

Dazu kommt eine Datei für offene Punkte – nenn sie open-items.md. Dort landet alles, wo der Agent eine Annahme getroffen hat oder wo eigentlich eine Produktentscheidung nötig wäre. So musst du nicht bei jeder Kleinigkeit gefragt werden, verlierst die Entscheidungen aber auch nicht aus dem Blick.

Praktischer Nebeneffekt der Aufteilung: Du kannst pro Phase unterschiedlich starke Modelle einsetzen. Für Architektur und Planung ein starkes Modell, für die Abarbeitung klar umrissener Tasks ein schnelleres. In Claude Code lässt sich das direkt im Frontmatter eines Skills über die Felder model und effort festlegen.

Ergebnis: funktionierender Code plus aktualisierte Task-Dateien.

Phase 4: Code Review – die zweite Meinung

Auch mit sauberem Planungsprozess läuft nicht alles glatt. Der Review-Schritt findet echte Bugs, die sonst im Produktivbetrieb aufgeschlagen wären.

Zwei Dinge machen ihn wirksam:

Ein zweites Modell. Trutz lässt parallel zu Claude Code auch Codex über die Änderungen schauen und konsolidiert anschließend die Beobachtungen. Zwei unterschiedliche Modelle finden unterschiedliche Dinge.

Mehrere Subagenten. Agenten arbeiten nicht deterministisch – jeder Durchlauf nimmt einen anderen Weg durch den Code. Fünf Subagenten mit derselben Aufgabe liefern fünf unterschiedliche Fundlisten. Du kannst zehn Reviews laufen lassen, und es kommt immer noch Neues dazu.

Damit stellt sich die eigentliche Frage: Wann hörst du auf? Dafür gibt es keine saubere Antwort. Irgendwann sind die Funde nur noch theoretische Edge Cases, bei denen du entscheiden musst, ob sie den Aufwand wert sind.

Ein Detail, das sich bewährt hat: Schreib in die code-review.md auch hinein, warum etwas geändert wurde. Sonst dreht der nächste Review-Durchlauf eine Entscheidung wieder zurück, weil er sie ohne Begründung anders bewertet. Mit Begründung kann er sie entweder stehen lassen oder gezielt widerlegen.

Ergebnis: code-review.md mit Funden, Fixes und Begründungen.

Phase 5: Dokumentation und Deployment

Zum Schluss die Dinge, die man gerne vergisst. Ein Deployment-Skill schreibt auf, was für das Livegehen nötig ist: Migrationen, neue Dienste, Konfigurationswerte, Reihenfolge. Ein Dokumentations-Skill pflegt die interne Doku nach.

Und dann kommt der Teil, der oft komplett liegen bleibt: die Außenkommunikation. Ein Skill, der aus dem Feature ein Kunden-Update formuliert. Ein Skill, der auf Basis eures Templates eine Landingpage baut – inklusive Screenshots, die der Agent sich per Playwright selbst zieht.

Eine Ordnerkonvention hält die Kette zusammen

Damit Skill 3 findet, was Skill 1 geschrieben hat, braucht es eine feste Ablage. Leg sie einmal zentral fest und verweise aus jedem Skill darauf:

ax-spec/
└── <feature-name>/
    ├── prd.md              # Phase 1: Anforderungen
    ├── plan.md             # Phase 2: technischer Plan
    ├── ui.md               # Phase 2: UI-Entwurf
    ├── todo.md             # laufender Stand
    ├── open-items.md       # Annahmen und offene Entscheidungen
    ├── code-review.md      # Phase 4: Funde und Begründungen
    ├── deployment.md       # Phase 5: Livegang
    └── tasks/
        ├── 01-datenmodell.md
        └── 02-api-endpunkt.md

Du gibst dem Agenten beim Start einer Phase den Feature-Namen mit, und er weiß, wo alles liegt. Existiert der Ordner noch nicht, legt der erste Skill ihn an.

Skills funktionieren genauso ohne Code

Der Entwicklungsprozess ist nur ein Beispiel. Das Muster – wiederkehrende Aufgabe, festes Ausgabeformat, feste Quellen – gilt überall.

Kais Beispiel aus der Praxis: die Vorbereitung von Akquise-Terminen. Der Skill beschreibt Schritt für Schritt, was zu tun ist, ungefähr so, wie man es einer neuen Kollegin erklären würde:

1. Firmenwebsite aufrufen, „Über uns“ und Team-Seiten auswerten: Größe, Mitarbeiterzahl, Ausrichtung.
2. News-Bereich der Website prüfen.
3. Allgemeine Websuche zum Unternehmen und zur Ansprechperson.
4. Abgleich mit den eigenen Produkten: Wo ist die Überschneidung am größten?
5. Ergebnis als HTML-One-Pager in einem festgelegten Aufbau.

Neben der SKILL.md liegt eine produkte.md mit dem aktuellen Portfolio, damit der Agent den Abgleich überhaupt machen kann. Solche Kontextdateien sind der Hebel, der einen generischen Rechercheauftrag in eine spezifische Vorbereitung verwandelt.

Der Zeitgewinn ist erheblich: Was vorher eine halbe bis ganze Stunde gebunden hat, läuft in wenigen Minuten – und zwar in einer Tiefe, die von Hand kaum leistbar war, weil niemand eine komplette Website plus Newsquellen für einen einzelnen Termin durchgeht.

Ein zweites Muster lohnt sich fast noch mehr, weil es so klein ist: ein Skill, der nur ein Ausgabeformat definiert. „Fass mir das in einem HTML-One-Pager zusammen“ ist ein Satz, den man ständig sagt – und danach jedes Mal erklärt, was das eigentlich heißen soll. Schreib einmal auf, was ein One-Pager bei dir enthält, wie er aufgebaut ist, welche Elemente immer dazugehören. Danach reicht der eine Satz.

Eine Einschränkung ist ehrlicherweise zu nennen: Der Agent kommt nur an das, worauf er Zugriff hat. Deine Mails gehören ohne entsprechende Anbindung nicht dazu. Und LinkedIn lässt Agenten ungern auf seine Seiten – da ist wenig zu holen. Was du dem Agenten mitgeben willst, hängst du entweder als Datei an den Skill oder verweist ihn auf eine öffentlich erreichbare Quelle.

Wie du deinen ersten Skill baust

Lass den Agenten den Skill schreiben. Das ist der mit Abstand nützlichste Tipp und wird oft übersehen. Beschreibe dem Agenten, was der Skill leisten soll, gib ihm zwei, drei bestehende Skills als Vorbild, und sag ihm, welche Aspekte davon du übernehmen willst. Das Ergebnis ist meist präziser formuliert, als du es aus dem Stand hinbekommen hättest.

Schau dir an, was andere gemacht haben. OpenSpec verfolgt einen spezifikationsgetriebenen Ansatz, Matt Pococks Skills sind eine der meistgenutzten Sammlungen überhaupt. Nimm sie als Ideengeber, nicht als fertige Lösung – wahrscheinlich passt keiner davon exakt zu deinem Projekt. Genau das ist der Grund, eigene zu bauen.

Gib nach dem ersten Durchlauf Feedback. Hier hat der Agent die Datei nicht gefunden. Da hat er einen Schritt übersprungen, obwohl er im Skill steht. Diese Beobachtungen fließen zurück in die SKILL.md, und der nächste Durchlauf läuft spürbar besser. Ein Skill ist kein Dokument, das man einmal schreibt – er wird über ein paar Iterationen gut.

Halte den Text kurz. Sobald ein Skill geladen ist, bleibt sein Inhalt über die weiteren Turns im Kontext. Jede Zeile kostet also dauerhaft. Schreib, was zu tun ist, statt lang zu begründen, warum.

Definiere klare Artefakte. Ein Skill, der mit „und dann machst du weiter“ endet, ist keine Phase. Ein Skill, der mit „schreibe das Ergebnis nach prd.md“ endet, ist eine.

Nutze eine frische Session pro Phase. Das ist keine Eigenschaft der Skills, sondern deine Disziplin. Sie ist aber der Grund, warum die Kette überhaupt funktioniert.

Ergänze Tools, wenn es sich lohnt. Ein Skill kann Skripte mitbringen, die der Agent ausführt – ein Validierungsskript, ein Generator, ein Screenshot-Tool. Für den Anfang brauchst du das nicht: Reiner Markdown-Text bringt schon den Großteil des Nutzens.

Häufige Fragen

Was ist der Unterschied zwischen einem Skill und einem gespeicherten Prompt?

Funktional wenig – ein Skill ist am Ende auch nur ein Prompt. Der Unterschied liegt im Drumherum: Der Agent kann ihn anhand der description selbst auswählen, er lädt ihn erst bei Bedarf statt dauerhaft, er kann Zusatzdateien mitbringen, und du kannst ihn versionieren und mit dem Team teilen.

Was gehört in die CLAUDE.md und was in einen Skill?

Faustregel: Fakten in die CLAUDE.md, Prozesse in einen Skill. Die CLAUDE.md wird in jeder Session geladen und sollte deshalb schlank bleiben – Tech-Stack, Befehle, Konventionen. Sobald ein Abschnitt darin zu einer mehrstufigen Anleitung wird, ist er ein Skill-Kandidat. Sein Inhalt kostet dann nur dann Kontext, wenn er tatsächlich gebraucht wird.

Kann ich Skills auch im Chat nutzen, nicht nur im Coding-Agenten?

Ja. Das Konzept ist nicht an das Terminal gebunden; in der Desktop-App und im Web funktionieren Skills genauso. Für viele Alltagsaufgaben ist das sogar der naheliegendere Einstieg – Recherche, Terminvorbereitung, wiederkehrende Auswertungen.

Was passiert, wenn der Agent einen Skill nutzt, obwohl er nicht passt?

Kommt vor. Die automatische Auswahl trifft gelegentlich daneben. In der Praxis überwiegt der Nutzen deutlich, und wenn es stört, kannst du gegensteuern: eine schärfere description schreiben, oder die automatische Auswahl per disable-model-invocation: true ganz abschalten, sodass der Skill nur noch auf deinen expliziten Aufruf hin läuft.

Brauche ich für jede Kleinigkeit einen Skill?

Nein. Ein einzelner Bugfix, eine kleine Anpassung, eine einmalige Frage – das promptest du einfach runter. Der Aufwand lohnt sich ab dem Punkt, an dem eine Aufgabe wiederkehrt und du ein bestimmtes Ergebnis erwartest.

Muss ich die Ergebnisse zwischen den Phasen wirklich lesen?

Ja, und das ist der anstrengende Teil. Die Versuchung, „passt schon, weiter“ zu sagen, ist groß. Aber genau an den Zwischenschritten entscheidet sich, ob am Ende das herauskommt, was du wolltest. Ein Anforderungsdokument zu korrigieren kostet zwei Minuten; einen fertig implementierten falschen Ansatz zu korrigieren kostet einen halben Tag.

Fazit

Skills sind kein neues Modell und kein zusätzliches Werkzeug. Sie sind der Mechanismus, mit dem du einen generischen Agenten auf deine Arbeitsweise zuschneidest, ohne irgendetwas nachtrainieren zu müssen. Du kannst ein Modell nicht dazu bringen, aus deinen Gewohnheiten zu lernen – aber du kannst diese Gewohnheiten aufschreiben.

Der praktische Einstieg ist klein: Nimm eine Aufgabe, die du in den letzten Wochen mehr als dreimal gemacht hast. Beschreibe dem Agenten, wie sie ablaufen soll und was am Ende dabei herauskommen muss. Lass ihn daraus eine SKILL.md schreiben. Nutze sie einmal, gib Feedback, und nutze sie wieder.

Der eigentliche Gewinn zeigt sich beim zweiten Mal – wenn du merkst, dass du nichts mehr erklären musst.

Folge 007 von Kontext.FM hörst du direkt auf der Episodenseite, samt Video und vollständigem Transkript. Wenn du danach noch beim Setup stehst: Die Vibe-Coding-Setup-Anleitung zeigt, wie du Terminal, Runtime und Coding-Agent auf dem Mac einrichtest, und die Einführung in Git sorgt dafür, dass du zu jedem Zwischenstand zurückkommst, den ein Agent verändert hat.