Das Skills Framework - Von Vibe Coding zu produktionsreifem Agentic Engineering

Im letzten Jahr habe ich meinen Agentic-Development-Stack kontinuierlich verfeinert: Claude Code mit einer sorgfältig gestalteten CLAUDE.md, parallele Worktrees, Agenten-Läufe über Nacht, Cursor für visuelle Arbeiten. Es war enorm produktiv - hat aber auch ein wiederkehrendes Fehlermuster offengelegt.

Wenn die CLAUDE.md wächst, um alles zu kodieren, was der Agent wissen soll, beginnt sie zu aufzublähen. Testing-Konventionen, Sicherheits-Checklisten, Shipping-Prozeduren, Review-Standards - alles in den System-Prompt zu stopfen bedeutet, dass jede einzelne Session die Token-Kosten zahlt, egal ob der Agent eine CSS-Variable refactored oder eine neue Billing-Pipeline entwirft. Und sobald die Datei eine gewisse Größe überschreitet, beginnt die Befolgung durch den Agenten nachzulassen.

Das Skills Framework ist die Lösung. Es ist die Disziplinschicht, von der ich nicht wusste, dass sie mir fehlte. Nachdem ich die letzten Wochen damit verbracht habe, es in meinen Workflow zu integrieren, bin ich überzeugt, dass es der nächste wichtige Standard für alle ist, die ernsthaftes Agentic Engineering betreiben. In diesem Artikel möchte ich erklären, was es ist, warum es wichtig ist, wie es sich mit GitHubs Spec Kit vergleicht und wie ich es in mein eigenes Setup eingebaut habe.

Was sind Agent Skills?

Anthropic hat Agent Skills Ende 2025 als strukturierten Weg eingeführt, um prozedurales Wissen für Claude zu verpacken. Die Kernidee ist verblüffend einfach: Statt alles in einen riesigen Prompt zu quetschen, erstellst du kleine, eigenständige Skill-Verzeichnisse, die der Agent nur bei Bedarf lädt.

Ein Skill ist einfach ein Ordner mit einer SKILL.md-Datei mit YAML-Frontmatter und einem Body, plus optionalen gebündelten Ressourcen:

my-skill/
├── SKILL.md           # The core instructions + frontmatter
├── scripts/           # Executable helpers the agent can run
├── references/        # Deeper docs loaded on demand
└── assets/            # Templates, example files, images

Das SKILL.md-Frontmatter ist das, was das ganze System zum Laufen bringt:

---
name: spec-driven-development
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet.
---

Claude sieht den name und die description jedes installierten Skills beim Session-Start - aber sonst nichts. Erst wenn der Agent entscheidet, dass ein Skill relevant ist, wird der vollständige Body in den Kontext geladen. Diese eine Designentscheidung - Progressive Disclosure - ist es, die das Framework skalierbar macht.

Progressive Disclosure: Der stille Durchbruch

Das Progressive-Disclosure-Modell funktioniert in drei Ebenen:

1. Metadaten (immer geladen) - Nur die Felder name und description, ein paar Tokens pro Skill. Das ist Claudes “Inhaltsverzeichnis.”
2. Anweisungen (bei Auslösung geladen) - Der vollständige Body der SKILL.md, typischerweise unter 500 Zeilen. Wird geladen, wenn der Agent die Aufgabe mit der Skill-Beschreibung abgleicht.
3. Ressourcen (bei Bedarf geladen) - Dateien unter scripts/, references/ und assets/. Können beliebig groß sein, da sie nur in den Kontext gelangen, wenn der Agent sie explizit liest.

Das löst die älteste Spannung im Agent Engineering: Du willst, dass der Agent Zugriff auf alles hat, aber du willst nicht für alles bei jedem Turn bezahlen. Progressive Disclosure sagt: Hab das Handbuch im Raum, aber lies es nicht bei jeder Frage von vorne bis hinten durch.

Das ist auch der Grund, warum Skills still und leise MCP das Wasser abgraben. In der Praxis verschlechtert das Verbinden von mehr als zwei oder drei MCP-Servern mit einem Agenten die Tool-Use-Genauigkeit spürbar - jede Tool-Beschreibung sitzt permanent im Kontext. Skills hingegen lassen dich Dutzende installieren, mit nahezu null Startup-Kosten. MCP und Skills sind nicht direkt Konkurrenten - MCP ist die Plumbing für Tool-Zugriff, Skills sind das prozedurale Gehirn auf dieser Plumbing - aber für Wissenskapselung gewinnen Skills bei der Ergonomie.

Addy Osmanis Agent-Skills: Produktionsreifes Engineering in einer Box

Hier wird es für mich richtig interessant. Addy Osmani - Senior Engineering Director bei Google, der über ein Jahrzehnt Chromes Developer-Experience-Team geleitet hat, Autor von Learning JavaScript Design Patterns und eine der durchdachtesten Stimmen zu KI-gestützter Entwicklung - hat seine eigenen meinungsstarken, produktionsreifen Engineering-Workflows als Open-Source Skills-Bibliothek unter github.com/addyosmani/agent-skills veröffentlicht.

Der Slogan sagt alles: “Production-grade engineering skills for AI coding agents.” Das sind keine Referenzdokumente - es sind Workflows, denen Agenten folgen, und die die Art von Disziplin kodieren, die ein Senior Engineer in Produktionscode einbringt.

Das Repo liefert aktuell rund zwanzig Skills, die auf sechs Lifecycle-Phasen abgebildet sind:

Phase	Repräsentative Skills
Define	spec-driven-development, idea-refine
Plan	planning-and-task-breakdown
Build	incremental-implementation, test-driven-development, frontend-ui-engineering
Verify	debugging-and-error-recovery, Test-Execution-Gates
Review	code-review-and-quality, security-and-hardening, api-and-interface-design
Ship	shipping-and-launch, ci-cd-and-automation, performance-optimization

Es gibt passende Slash-Commands - /agent-skills:spec, /agent-skills:plan, /agent-skills:build, /agent-skills:test, /agent-skills:review, /agent-skills:ship - die dir in jeder Phase direkten Zugriff auf den relevanten Skill geben.

Die SKILL.md-Anatomie, die es zum Laufen bringt

Was ich am wertvollsten finde, ist die konsistente interne Struktur jedes Skills. Am Beispiel von spec-driven-development als Referenzmodell:

• Overview - Ein Absatz: Was dieser Skill erreicht und warum der Agent sich dafür interessieren sollte.
• When to Use - Explizite Auslöser und, genauso wichtig, explizite Anti-Auslöser (“Nicht verwenden für Einzeiler-Fixes oder eindeutige Änderungen”).
• Process - Ein phasenbasierter Workflow mit Gates. Spec-Driven Development führt durch Specify → Plan → Tasks → Implement, mit einem menschlichen Review-Checkpoint zwischen jeder Phase.
• Rationalizations - Mein Lieblingsabschnitt. Das ist eine Liste der Ausreden, die ein Agent (oder ein müder Engineer) erfinden wird, um den Prozess zu überspringen, jeweils gepaart mit einer klaren Gegenrede. Die kanonische Zeile des Spec-Driven Skills lautet: “A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.”
• Red Flags - Warnzeichen, dass der Skill falsch angewendet oder ganz übersprungen wird.
• Verification - Konkrete Nachweise, dass der Skill tatsächlich befolgt wurde. Nicht “sieht richtig aus” - eine Checkliste.

Der Rationalizations-Abschnitt ist die entscheidende Innovation. Jeder Senior Engineer hat erlebt, wie ein Junior Developer (oder man selbst an einem schlechten Tag) Testing wegrationalisiert, ein Review überspringt oder ein Sicherheitsbedenken wegwischt. Skills kodieren nicht nur den richtigen Prozess, sondern auch die Anti-Rationalisierungs-Verteidigung, die den Agenten ehrlich hält. Das ist der Unterschied zwischen einem Dokument und einem Workflow.

Wie es sich mit GitHubs Spec Kit vergleicht

Wenn du diesen Bereich verfolgst, hast du wahrscheinlich von Spec Kit gehört, GitHubs Toolkit für Spec-Driven Development. Oberflächlich gibt es viel Überlappung - bei beiden geht es darum, “Vibe Coding” durch strukturiertes, spezifikationsgetriebenes Engineering zu ersetzen. Aber sie sind tatsächlich komplementär statt konkurrierend.

Dimension	Spec Kit (GitHub)	Agent-Skills (Osmani)
Hauptfokus	Spec-Driven-Development-Lifecycle-Scaffolding	Vollständige Engineering-Workflow-Bibliothek (Spec, Test, Review, Ship)
Auslieferungsformat	Slash-Command-Templates + Projekt-Scaffolding	Progressive-Disclosure-SKILL.md-Verzeichnisse
Prozessabdeckung	Specify → Plan → Tasks → Implement	Sechs Phasen über den gesamten SDLC
Kontextladung	Prompt-Dateien werden vorab injiziert	Bei Bedarf geladen via Metadaten-Matching
Tooling-Oberfläche	CLI (specify), das ein Repo einrichtet	Einfache Verzeichnisse, portabel über Agenten hinweg
Anti-Rationalisierung	Implizit im gated Flow	Expliziter Abschnitt in jedem Skill
Erweiterbarkeit	Template-basiert	Weitere SKILL.md-Dateien schreiben, reinlegen

Interessanterweise können neuere Versionen von Spec Kit jetzt Agent Skills statt Slash-Command-Prompt-Dateien installieren, über einen --ai-skills-Parameter - die beiden konvergieren also. Spec Kit gibt dir einen batteriebeladenen Einstieg für den Spec-Plan-Tasks-Implement-Flow; Agent-Skills gibt dir eine breitere und tiefere Bibliothek für den Rest des Engineering-Lifecycles, progressiv geladen. Ich nutze Spec Kit, um neue Projekte aufzusetzen, und die Agent-Skills-Bibliothek als fortlaufende Disziplinschicht darüber.

Warum das wichtig ist: Die Lücke zwischen Vibe Coding und Engineering

Andrej Karpathy hat Vibe Coding geprägt, um eine spezifische, ehrliche Praxis zu beschreiben: Den Prompt an das Modell geben, akzeptieren was rauskommt, den Diff nicht lesen, iterieren indem man Fehler zurückfüttert. Für Wochenendprojekte und Wegwerf-Prototypen ist es eine echte Superpower. Ich habe Dinge in zwei Stunden gebaut, die zwei Tage sorgfältiges Engineering gebraucht hätten.

Das Problem ist, dass “Vibe Coding” zu einem Sammelbegriff wurde. Leute begannen es für alles zu verwenden, von echtem YOLO-Prompting bis hin zu disziplinierten Agentic Workflows mit Tests, Code Review und menschlicher Architekturaufsicht. Simon Willison versuchte das Territorium mit “Vibe Engineering” zurückzugewinnen - gleiche Begeisterung, aber mit Engineering-Rigor aufgeschraubt. Es hat sich nicht durchgesetzt, hauptsächlich weil das Wort Vibe zu viel lässige Konnotation mitbringt. Wie Karpathy selbst später vorschlug, ist Agentic Engineering der sauberere Rahmen: Der Mensch verantwortet Architektur, Qualität und Korrektheit; der Agent übernimmt die Implementierung.

Osmanis eigene Formulierung finde ich am nützlichsten: Der größte Einzelunterschied zwischen Agentic Engineering und Vibe Coding ist Testing. Mit einer soliden Test-Suite kann ein Agent in einer Schleife iterieren bis alles grün ist, und du hast hohes Vertrauen in das Ergebnis. Ohne eine solche fliegst du nur blind - mit 10-facher Geschwindigkeit.

Das Skills Framework macht Agentic Engineering durchsetzbar. Es ist die strukturelle Schicht, die Absicht (“wir sollten zuerst Specs schreiben”) in Prozess verwandelt (“der /spec-Skill blockiert buchstäblich die Implementierung, bis Phase 1 genehmigt ist”). Es macht den Prozess auch portabel: Dieselben SKILL.md-Dateien funktionieren in Claude Code, Cursor, Gemini CLI, Windsurf und Copilot, weil sie einfach Markdown mit einer Konvention sind.

Die konkreten Vorteile, die ich gemessen habe

Nachdem ich das Skills Framework in den letzten Wochen in meinen Stack integriert habe, hat sich Folgendes wirklich verändert:

1. Meine CLAUDE.md wurde kleiner, nicht größer

Das war die Überraschung. Ich hatte das Aufblähproblem bekämpft, indem ich disziplinierter war bei dem, was in die CLAUDE.md kam. Skills ließen mich ganze Kapitel auslagern: die Sicherheits-Checkliste, die Release-Prozedur, das Performance-Profiling-Playbook, die API-Design-Richtlinien. Sie sind alle noch da, werden noch durchgesetzt - aber sie gelangen nur in den Kontext, wenn ein Skill ausgelöst wird. Meine CLAUDE.md handelt jetzt hauptsächlich von der Projektarchitektur und dem Mandantenmodell, nicht von generischer Engineering-Disziplin. Der Agent ist dadurch spürbar fokussierter.

2. Anti-Rationalisierung funktioniert tatsächlich

Das war die größte qualitative Veränderung. Vor Skills, wenn ein Agent das Schreiben von Tests überspringen wollte, rationalisierte er: “Das ist eine triviale Änderung, Tests wären übertrieben.” Manchmal habe ich es bemerkt, manchmal nicht. Mit dem geladenen test-driven-development-Skill werden diese Rationalisierungen frontal vom Gegenrede-Abschnitt des Skills getroffen. Der Agent streitet mit sich selbst und verliert. Ich habe Nachtläufe gesehen, bei denen der Agent erwog, einen Test zu überspringen, der Skill den Gedanken abfing, und der Lauf trotzdem Tests produzierte.

3. Nachtläufe sind vertrauenswürdiger

Mein Overnight Agent Factory-Workflow ist nur so gut wie die impliziten Quality Gates, die der Agent respektiert, während ich schlafe. Skills machen diese Gates explizit. /ship wird nicht abgeschlossen, sofern security-and-hardening und code-review-and-quality nachweisbar gelaufen sind. Ich wache mit PRs auf, die näher an “merge-fähig” sind, nicht näher an “braucht noch eine Stunde Aufräumarbeit.”

4. Portabel über Agenten hinweg

Wenn ich an einem Frontend in Cursor iteriere und dann zu Claude Code für eine Backend-Aufgabe wechsle, gilt dieselbe Skills-Bibliothek. Gleiche Konventionen, gleiche Verification Gates, gleiche Anti-Rationalisierungen. Kein agenten-spezifisches Prompt-Tuning mehr.

5. Kombinierbar mit Spec Kit

Für Greenfield-Projekte bootstrappe ich mit Spec Kits specify-CLI, dann übernimmt die Agent-Skills-Bibliothek, sobald die erste Spec genehmigt ist. Die beiden Frameworks greifen sauber ineinander.

Wie ich es im Alltag nutze

Wichtig: Skills sind Teil von Claude Codes Plugin-System - du kannst nicht einfach ein Repo in ein beliebiges Verzeichnis klonen und erwarten, dass Claude es findet. Das Plugin-System übernimmt Discovery, Registrierung und die Slash-Command-Verdrahtung.

Installation

Innerhalb einer Claude-Code-Session führst du diese zwei Befehle aus:

# 1. Register Osmani's repo as a plugin marketplace
/plugin marketplace add addyosmani/agent-skills

# 2. Install the plugin from that marketplace
/plugin install agent-skills@addy-agent-skills

Starte Claude Code nach der Installation neu - Skills und Commands werden beim Session-Start entdeckt, sie erscheinen also erst in einer neuen Session.

Troubleshooting: Falls der Marketplace-Clone still fehlschlägt (die Commands tauchen nie auf), ist die häufigste Ursache SSH-Berechtigungen. Behebe es mit:

git config --global url."https://github.com/".insteadOf "git@github.com:"

Dann wiederhole die beiden Befehle oben in einer neuen Session.

Die vollständige Plugin- und Skill-Spezifikation findest du in Anthropics Skills-Dokumentation.

Die Commands verwenden

Nach der Installation registriert das Plugin sieben namespaced Slash-Commands, die auf den Entwicklungs-Lifecycle abgebildet sind. Das agent-skills:-Präfix unterscheidet sie von eingebauten Claude-Code-Commands (wie dem eingebauten /review, das Pull Requests reviewed):

/agent-skills:spec           → write a structured specification (saves to SPEC.md)
/agent-skills:plan           → break the spec into small, verifiable tasks
/agent-skills:build          → implement the next task incrementally (thin vertical slices)
/agent-skills:test           → TDD workflow; for bugs, uses the "Prove-It" pattern (failing test first)
/agent-skills:review         → five-axis code review (correctness, readability, architecture, security, performance)
/agent-skills:code-simplify  → simplify code for clarity without changing behavior
/agent-skills:ship           → pre-launch checklist (quality, security, performance, accessibility, infra, docs)

Hinter diesen Commands stehen 21 Skills, die den gesamten SDLC abdecken - von idea-refine und spec-driven-development über debugging-and-error-recovery bis shipping-and-launch. Skills triggern auch automatisch: Claude sieht ihre Beschreibungen beim Session-Start und lädt die vollständigen Anweisungen, wenn eine Aufgabe passt. Du brauchst nicht immer den Slash-Command; mit der Arbeit an einem neuen Feature zu beginnen, wird natürlich die Spec- und Planning-Skills aufrufen.

Nach der Installation verschlanke deine CLAUDE.md - lagere die generischen Engineering-Disziplin-Abschnitte aus und behalte nur die projektspezifische Architektur. Die Skills tragen jetzt diese Last.

Für interne Skills, die spezifisch für meine Projekte sind - Multi-Tenancy-Enforcement, NutriSpan-Datenmodell-Konventionen, SortFlex-CadQuery-Patterns - schreibe ich eigene SKILL.md-Dateien und verwende Osmanis Struktur als Template. Diese Sechs-Abschnitte-Anatomie (Overview / When to Use / Process / Rationalizations / Red Flags / Verification) ist die richtige Form, auch für domänenspezifische Skills.

Das Fazit

Wenn du immer noch Agentic Workflows mit einer einzigen aufgeblähten CLAUDE.md betreibst, verschenkst du viel Hebel. Das Skills Framework ist kein Trend - es ist eine ehrliche Engineering-Antwort auf ein echtes Skalierungsproblem: Wie gibst du einem Agenten mehr Disziplin, ohne die Kontextkosten zu zahlen, alles bei jedem Turn zu laden?

Anthropics Progressive-Disclosure-Design löst das Ladeproblem. Addy Osmanis Open-Source Skills-Bibliothek gibt dir zwanzig praxiserprobte Workflows für den Einstieg. GitHubs Spec Kit gibt dir den Einstiegspunkt. Kombiniere alle drei und du hast etwas, das sich endlich nach Engineering anfühlt statt nach Prompting.

Für alle, die ernsthaft Software mit Agenten bauen - keine Prototypen, keine Wochenendprojekte, sondern die Dinge, die in einem Jahr in Produktion funktionieren müssen - ist das das Framework, das ich heute einführen würde.

Referenzen

• addyosmani/agent-skills - Addy Osmanis produktionsreife Skills-Bibliothek
• Equipping agents for the real world with Agent Skills - Anthropics Launch-Post
• Agent Skills - Claude API Docs - Offizielle Referenz
• github/spec-kit - GitHubs Spec-Driven-Development-Toolkit
• Agentic Engineering - Addy Osmani - Der breitere Kontext
• How to write a good spec for AI agents - Addy Osmani - Der begleitende Spec-Artikel
• Progressive Disclosure Might Replace MCP - MCPJam - Das Progressive-Disclosure-vs-MCP-Argument