Dunkles Browserfenster mit grünem SKILL.md Schriftzug und Rakete für Agent Skills

Was ist SKILL.md?

Eine SKILL.md ist die zentrale Datei eines Agent Skills: eine Markdown Datei mit YAML Frontmatter im Kopf und Anweisungen im Body, die einem KI Coding Agent beibringt, eine bestimmte Aufgabe nach festen Konventionen auszuführen. Ein Skill ist technisch nichts anderes als ein Ordner, der genau eine SKILL.md als Einstiegspunkt enthält, optional ergänzt um Skripte und Referenzdateien.

Das Format stammt ursprünglich von Anthropic für Claude Code und wurde als offener Standard veröffentlicht. Heute lesen zahlreiche Agenten dieselbe Datei: Claude Code, OpenCode, der Codex CLI von OpenAI, die Gemini CLI von Google, GitHub Copilot und Cursor. Eine einmal geschriebene SKILL.md ist damit portabel und funktioniert toolübergreifend, solange sie sich an den Kern des Standards hält.

Der Clou liegt im Prinzip der Progressive Disclosure: Der Agent lädt zuerst nur Name und Beschreibung aus dem Frontmatter in seinen Kontext. Erst wenn eine Aufgabe zur Beschreibung passt, zieht er den vollständigen Body nach, und gebündelte Ressourcen erst dann, wenn er sie wirklich braucht. So bleibt das Kontextfenster schlank, auch wenn dutzende Skills verfügbar sind.

Inhalt

Warum NCA dein Partner für SKILL.md ist

Never Code Alone arbeitet täglich mit Claude Code und OpenCode und schreibt eigene SKILL.md Dateien für wiederkehrende Aufgaben. Das KI-gestützte Content Marketing auf nevercodealone.de läuft selbst über Skills, die Konventionen, Block-Strukturen und Qualitätsregeln dauerhaft im Agenten verankern. Wir kennen den Standard also nicht aus der Theorie, sondern aus dem eigenen Produktivbetrieb.

Für Teams, die Skills sauber aufsetzen wollen, verbinden wir das mit unserem Vibe Coding Consulting und konkreten Vibe Coding Best Practices. Wir helfen beim Schreiben triggersicherer Beschreibungen, bei der Einordnung des Agent Skills Ökosystems und der Installation über Skills.sh, und ordnen Skills gegenüber Claude Code Plugins für deinen konkreten Workflow ein.

Lass uns sprechen

Finde das passende Angebot für dein Projekt

🤖

Hey! Ich bin CodeBot. Lass uns herausfinden, wie wir dein Projekt zum Fliegen bringen.

Was soll entstehen?

Anatomie einer SKILL.md: Frontmatter, Body und Ressourcen

Eine SKILL.md besteht aus zwei Teilen. Oben steht das YAML Frontmatter mit Metadaten, darunter folgt der Markdown Body mit den eigentlichen Anweisungen. Der Standard schreibt im Frontmatter nur zwei Felder zwingend vor:

name: ein eindeutiger Bezeichner, klein geschrieben, Wörter mit Bindestrich getrennt, etwa nca-content-pipeline.
description: eine klare Beschreibung, was der Skill tut und wann der Agent ihn nutzen soll. Dieses Feld steuert das dynamische Laden und Triggern.

Der Body unter dem Frontmatter enthält die Anweisungen, die der Agent befolgt, sobald der Skill aktiv ist: Schritte, Beispiele, Konventionen. Optional liegen neben der SKILL.md drei Verzeichnisse: scripts für ausführbaren Code wie Bash Skripte, references für Dokumente, die erst bei Bedarf geladen werden, und assets für Dateien, die im Output landen, etwa Templates, Icons oder Fonts.

So sieht das minimale Grundgerüst aus, an dem sich auch das offizielle Template von Anthropic orientiert:

Code:

          ---
name: nca-content-pipeline
description: Erstellt SEO optimierte Glossar Seiten fuer das NCA CMS. Nutze diesen Skill bei neuen Seiten unter glossare oder vibe-coding.
---

# NCA Content Pipeline

Du erstellst strukturierte Glossar Eintraege nach festem Blockaufbau.

## Schritte
- Existenz pruefen, dann Konzept, dann Draft anlegen
- Bloecke in fester Reihenfolge setzen

## Guidelines
- Echte Umlaute, keine Unicode Escapes
- Keine CTAs im Fliesstext

Progressive Disclosure: die drei Ebenen des Ladens

Warum lädt ein Agent nicht einfach alle Skills komplett? Weil jedes Token im Kontextfenster Geld kostet und die Qualität sinkt, je voller der Kontext ist. Der Standard löst das mit gestuftem Laden: Metadaten immer, der Body bei Bedarf, schwere Ressourcen erst, wenn sie gebraucht werden. Dadurch kann ein Agent dutzende Skills bereithalten und trotzdem schlank bleiben.

Ebene	Was geladen wird	Wann
Ebene 1: Metadaten	name und description aus dem Frontmatter	Immer, beim Start im Systemkontext
Ebene 2: Body	Die vollständigen Anweisungen der SKILL.md	Sobald eine Aufgabe zur description passt
Ebene 3: Ressourcen	Skripte, Referenzdateien, Assets	Nur bei Bedarf zur Laufzeit

Die description als Trigger schreiben

Das wichtigste Feld einer SKILL.md ist die description. Sie entscheidet, ob der Agent den Skill überhaupt heranzieht. Da nur Name und Beschreibung dauerhaft im Kontext liegen, ist die description der einzige Anhaltspunkt für die Frage: Passt dieser Skill zur aktuellen Aufgabe?

In der Praxis neigen Agenten zum Untertriggern, sie übersehen passende Skills also eher, als dass sie sie zu oft laden. Deshalb gehört in die description beides hinein: was der Skill tut und vor allem wann er genutzt werden soll. Konkrete Auslöser, Dateitypen und Formulierungen wirken besser als abstrakte Beschreibungen. Eine ruhig etwas fordernd formulierte Beschreibung trifft zuverlässiger.

Schwach formuliert: ein Skill zum Bauen von Dashboards. Stark formuliert: ein Skill zum Bauen von Dashboards, der immer dann genutzt wird, wenn von Dashboards, Datenvisualisierung oder internen Kennzahlen die Rede ist, auch ohne dass das Wort Dashboard explizit fällt. Dieselbe Sorgfalt, die gutes Vibe Coding Prompting auszeichnet, gilt für jede description.

Alle Angaben, wann ein Skill greift, gehören in die description, nicht in den Body. Der Body wird erst gelesen, wenn der Skill bereits ausgewählt wurde. Wer die Trigger im Body versteckt, wundert sich, warum der Agent den Skill nie aktiviert.

SKILL.md, CLAUDE.md und Plugins: die Abgrenzung

Wer mit Claude Code arbeitet, stößt schnell auf mehrere Konfigurationsdateien. Sie lösen unterschiedliche Probleme und ergänzen sich.

CLAUDE.md und AGENTS.md sind projektweite Kontextdateien. Sie gelten für das gesamte Repository und sind dauerhaft präsent, etwa für Tech Stack, Coding Konventionen oder Sicherheitsregeln. Wie man sie schärft, zeigt das Vorgehen rund um Exact Coding mit den Karpathy Prinzipien.
SKILL.md ist aufgabenspezifisch. Ein Skill wird nur dann geladen, wenn eine konkrete Aufgabe zu seiner description passt, und bringt für genau diese Aufgabe Schritte und Ressourcen mit.
Plugins sind die Verteil und Erweiterungsebene. Ein Plugin kann Commands, Agents, Hooks, MCP Server und auch Skills bündeln. Details dazu im Eintrag zu Claude Code Plugins und zum dezentralen Claude Code Plugin Marketplace.

Faustregel: Was immer gelten soll, gehört in die CLAUDE.md. Was nur für eine bestimmte Aufgabe zählt, wird ein Skill. Und wenn mehrere zusammengehörige Erweiterungen verteilt werden sollen, bündelt sie ein Plugin. Spec Driven Ansätze wie OpenSpec lassen sich mit Skills sauber kombinieren.

Offener Standard und Portabilität über Tools hinweg

Die Agent Skills Spezifikation ist ein offener Standard, veröffentlicht unter agentskills.io. Anthropics Referenzimplementierung samt Beispiel-Skills liegt unter MIT Lizenz im Repository anthropics/skills auf GitHub. Der Standard ist bewusst minimal gehalten: Er definiert gerade genug Struktur, damit Skills auffindbar und portabel sind, ohne vorzuschreiben, was ein Agent damit tut.

Das zahlt sich bei der Portabilität aus. Eine SKILL.md, die beim Kern bleibt, also Frontmatter plus Markdown Anweisungen, läuft über viele Werkzeuge hinweg. Bei NCA setzen wir im Tagesgeschäft auf Claude Code und OpenCode. Daneben unterstützen weitere Agenten das Format: Der Codex CLI von OpenAI, die Gemini CLI von Google, GitHub Copilot und Cursor sind geeignet, wenn ein Team bereits damit arbeitet. Welcher Agent zu deinem Setup passt, ordnen wir im Beratungsprojekt ein.

Installiert werden Skills projektlokal oder global. Plattformen wie Skills.sh machen erprobte Skill-Pakete per Befehl verfügbar, das breitere Agent Skills Ökosystem bündelt Verzeichnis und CLI. Wer eigene Skills für Claude Code und OpenCode baut, kann sie ins Git einchecken und teamweit teilen.

Organized collections of files that package composable procedural knowledge for agents.

Barry Zhang, Mitentwickler Agent Skills, Anthropic – AI Engineering Code Summit (8. Dezember 2025)

Agent Skills: Offenes Ökosystem für KI Coding Agents

Agent Skills 2026: Vercels Ökosystem für KI Coding Agents. Modulare Skill Packages für Claude Code, OpenCode, Cursor und 18 weitere Agents. Mit npx skills CLI.

Mehr erfahren

SKILL.md in der Praxis bei Never Code Alone

Die Inhalte auf nevercodealone.de entstehen über eine SKILL.md gesteuerte Pipeline. Ein Skill kennt unsere Block-Reihenfolge, die Regeln für echte Umlaute, die interne Verlinkung und die Snippet-Zuordnung. Statt diese Vorgaben bei jeder Seite neu zu prompten, liegen sie dauerhaft im Agenten. Das ist gelebtes Skill-Wissen für Claude Code und OpenCode.

In NCA-Projekten sehen wir regelmäßig zwei Fehlerquellen. Erstens eine zu vage description, sodass der Agent den Skill nicht aktiviert. Zweitens ein überladener Body, der alles in eine Datei presst, statt schwere Details in references auszulagern. Beides lässt sich mit sauberer Progressive Disclosure und gutem Prompting beheben.

Wir begleiten Teams beim Aufbau eigener Skills, von der Struktur über triggersichere Beschreibungen bis zur Integration in parallele Coding Sessions und lokale Modelle mit Ollama. Den roten Faden liefert unser Vibe Coding Consulting, eingebettet in erprobte Best Practices für KI-gestützte Entwicklung.

CYPRESS.IO Ambassador und IT Consultant für QA Engenieering und Qualität in PHP Projekten.

NCA Vibe Coding Consulting

Roland Golla ist Entwickler aus Leidenschaft – seit über 20 Jahren. Er hat hunderte Projekte begleitet, von Legacy-Refactoring bis KI-Integration. Bei Vibe Coding verbindet er das Beste aus beiden Welten: Die Geschwindigkeit von KI-generiertem Code mit der Qualität professioneller Softwareentwicklung. Kein Bullshit, keine Agentur-Floskeln – direkte Hilfe von jemandem, der selbst täglich im Code steckt.

E-Mail Kontakt

Häufige Fragen zu SKILL.md

Die wichtigsten Fragen und Antworten rund um das SKILL.md Format, von Aufbau und Frontmatter über Progressive Disclosure bis zur Abgrenzung gegenüber CLAUDE.md und Plugins.

Was ist eine SKILL.md 2026?

Eine SKILL.md ist die zentrale Datei eines Agent Skills. Sie kombiniert YAML Frontmatter mit Metadaten und einen Markdown Body mit Anweisungen, die einem KI Coding Agent beibringen, eine Aufgabe konsistent zu erledigen. Ein Skill ist technisch ein Ordner mit genau dieser Datei als Einstiegspunkt, optional ergänzt um Skripte und Referenzen.

Welche Felder sind in einer SKILL.md 2026 Pflicht?

Der Standard verlangt im Frontmatter nur zwei Felder: name als eindeutigen Bezeichner in Kleinbuchstaben mit Bindestrichen, und description als klare Beschreibung von Zweck und Einsatzkontext. Alle weiteren Angaben sind optional. Der Markdown Body unter dem Frontmatter enthält die eigentlichen Anweisungen, die der Agent befolgt, sobald der Skill aktiv ist.

Wie schreibe ich 2026 eine gute description?

Nenne klar, was der Skill tut, und vor allem, wann er genutzt werden soll. Konkrete Auslöser, Dateitypen und Formulierungen wirken besser als abstrakte Sätze. Da Agenten eher zum Untertriggern neigen, darf die Beschreibung ruhig etwas fordernd sein. So aktiviert der Agent den Skill zuverlässig, auch wenn das Stichwort nicht wörtlich fällt.

Was bedeutet Progressive Disclosure bei SKILL.md 2026?

Progressive Disclosure beschreibt das gestufte Laden. Zuerst liegen nur name und description im Kontext. Erst wenn eine Aufgabe passt, lädt der Agent den vollständigen Body. Schwere Ressourcen wie Skripte oder Referenzen kommen erst bei Bedarf dazu. So bleiben dutzende Skills verfügbar, ohne das Kontextfenster zu fluten.

Welche Tools unterstützen SKILL.md 2026?

Das Format stammt von Anthropic für Claude Code und ist heute ein offener Standard. Neben Claude Code und OpenCode lesen unter anderem der Codex CLI von OpenAI, die Gemini CLI von Google, GitHub Copilot und Cursor dieselbe Datei. Eine SKILL.md, die beim Kern bleibt, läuft damit toolübergreifend.

Was ist der Unterschied zwischen SKILL.md und CLAUDE.md?

Die CLAUDE.md ist eine projektweite Kontextdatei, die dauerhaft für das gesamte Repository gilt, etwa für Tech Stack und Konventionen. Eine SKILL.md ist aufgabenspezifisch und wird nur geladen, wenn eine Aufgabe zu ihrer description passt. Faustregel: Was immer gelten soll, gehört in die CLAUDE.md, was nur für eine Aufgabe zählt, wird ein Skill.

Wie installiere ich einen Skill?

Skills lassen sich projektlokal oder global ablegen. Projektlokale Skills gelten nur im aktuellen Repository und werden meist ins Git eingecheckt. Globale Skills wirken über alle Projekte hinweg. Verzeichnisse wie Skills.sh machen erprobte Skill-Pakete per Befehl verfügbar. Nach der Installation lädt der Agent den Skill automatisch, sobald eine Aufgabe passt.

Brauche ich scripts und references in jedem Skill?

Nein. Pflicht ist nur die SKILL.md selbst. Die Verzeichnisse scripts, references und assets sind optional. Skripte eignen sich für deterministische Schritte, references für ausführliche Dokumente, die erst bei Bedarf geladen werden, und assets für Dateien im Output wie Templates. Viele nützliche Skills bestehen nur aus einer einzigen SKILL.md.

Ist SKILL.md nur für Claude nutzbar?

Nein. Das Format wurde von Anthropic als offener Standard veröffentlicht und ist unter agentskills.io spezifiziert. Es ist bewusst minimal gehalten, damit Skills auffindbar und portabel bleiben. Dieselbe Datei funktioniert über eine wachsende Zahl von Agenten hinweg, solange sie sich an den Kern des Standards hält.

Wie lang sollte eine SKILL.md sein?

So kurz wie möglich, so lang wie nötig. Der Body sollte fokussiert bleiben und Details über references auslagern, statt alles in eine riesige Datei zu pressen. Ein überladener Body kostet bei jedem Aufruf Kontext und verschlechtert die Ergebnisse. Klare Struktur mit Verweisen auf vertiefende Dateien ist die bessere Wahl.

Wie unterscheiden sich Skills und Plugins?

Ein Skill ist eine Wissens und Anweisungseinheit für eine Aufgabe. Ein Plugin ist die Verteil und Erweiterungsebene und kann Commands, Agents, Hooks, MCP Server und auch Skills bündeln. Wer mehrere zusammengehörige Erweiterungen verteilen will, packt sie in ein Plugin. Der einzelne Skill bleibt davon unabhängig nutzbar.

Wie versioniere ich Skills sinnvoll?

Da Skills meist im Git liegen, profitieren sie von normaler Versionskontrolle. Klare Versionsstände und dokumentierte Änderungen erleichtern Rollbacks, wenn ein Skill unerwartet wirkt. Für Teams empfiehlt sich ein interner Review, bevor ein Skill breit ausgerollt wird, damit Quelle, Skripte und Abhängigkeiten geprüft sind.

A/B Testing mit KI – Automatisiertes Testing für Entwickler 2026