## Was ist SKILL.md? SKILL.md ist eine einzelne Markdown-Datei — typischerweise ausgeliefert unter `/skill.md` — die einem KI-Agenten erklärt, wie er deinen Dienst nutzt. Die Datei beginnt mit YAML-Frontmatter, das zwei Felder deklariert, `name` und `description`, gefolgt von freiem Markdown, das die Endpoints, das Auth-Modell und die Request-Formate dokumentiert, die der Agent zum Handeln braucht. Die Spezifikation ist unter [agentskills.io](https://agentskills.io/specification) veröffentlicht und wurde als herstellerübergreifende Konvention von Anthropics Claude Code, OpenAI Codex, Cursor, GitHub Copilot und Microsofts Agent Framework übernommen. Eine SKILL.md-Datei ist das kleinstmögliche Artefakt, mit dem ein Agent von „Ich habe diese Website gefunden" zu „Ich weiß, wie ich sie aufrufe" kommt. ## Warum SKILL.md wichtig ist LLM-Agenten haben dieselben Onboarding-Kosten wie Menschen: herauszufinden, wofür ein unbekannter Dienst da ist und wie man ihn korrekt aufruft. Für Menschen schreibst du einen Quickstart-Guide; für Agenten schreibst du eine SKILL.md. Das Frontmatter-Feld `name` gibt dem Agenten einen stabilen Bezeichner, den er intern registrieren kann; die `description` erscheint in Tool-Listen und im Planner des Agenten; der Body ist das Playbook. Die Alternative — ein Agent liest deine komplette Doku-Site, dein OpenAPI-Schema und deine Homepage, um dieselben Informationen zu rekonstruieren — ist langsam, teuer und verlustbehaftet. SKILL.md reduziert das Onboarding auf einen einzigen Fetch und ein paar hundert Tokens. Für Websites, die wollen, dass Agenten sie *tatsächlich nutzen* (nicht nur entdecken), ist SKILL.md die Datei mit dem größten Hebel, die du veröffentlichen kannst. ## Wie SKILL.md funktioniert Es gibt keinen Protokoll-Handshake. Ein Agent ruft `/skill.md` ab, parst das YAML-Frontmatter nach `name` und `description`, validiert den Namen gegen die Regex der Spezifikation und liest den Markdown-Body als Anleitung. Eine minimale gültige SKILL.md: ```markdown --- name: scan-url description: Scan any URL for AI agent readiness and return a 0-100 score. Use when a user asks how agent-ready a site is or wants to compare protocol support across sites. --- # Agent Readiness Scan Use `GET /api/v1/scan?url={url}` for the agent-friendly JSON response. ## Endpoints - `GET /api/v1/scan?url={url}` — flat JSON for agents - `GET /api/scan?url={url}` — full HTML report (for humans) - `GET /api/badge?url={url}` — SVG badge ## Auth None. All endpoints are free. ## Example `curl https://agentgrade.com/api/v1/scan?url=https://example.com` ``` Das ist die gesamte Oberfläche. Agenten, die diese Datei finden, wissen genug, um deinen Dienst beim ersten Versuch korrekt aufzurufen. ## SKILL.md vs. andere Agent-Readability-Dateien | Datei | Wer sie ausliefert | Was sie beantwortet | Format | |---|---|---|---| | **SKILL.md** | Der Dienst | *Wie nutze ich diesen Dienst?* | Markdown + Frontmatter | | **[OpenAPI](/kb/de/openapi)** | Der Dienst | *Welche Endpoints existieren und wie ist das Schema?* | JSON/YAML | | **[MCP](/kb/de/mcp)-Manifest** | Der MCP-Server | *Welche Tools stellt dieser Server über JSON-RPC bereit?* | JSON-RPC | | **`ai-plugin.json`** | Der Dienst | *Plugin-Metadaten für das ChatGPT-Plugin-Format* (Legacy) | JSON | | **[llms.txt](/kb/de/llms-txt)** | Der Dienst | *Was ist diese Website, in Prosa?* | Markdown | SKILL.md ist die „Playbook"-Schicht; OpenAPI ist die „Schema"-Schicht. Beide ergänzen sich: SKILL.md sagt dem Agenten, welche Endpoints er wann aufrufen soll; OpenAPI liefert das formale Parameter-Schema. Agenten, die beides finden, sind strikt besser dran als Agenten, die nur eines finden. `ai-plugin.json` ist älter als SKILL.md und war an das ursprüngliche ChatGPT-Plugin-Format gebunden, das OpenAI inzwischen eingestellt hat. SKILL.md ist der moderne, herstellerübergreifende Nachfolger. ## Frontmatter-Validierung Die agentskills.io-Spezifikation ist bei zwei Feldern streng: - **`name`** — 1 bis 64 Zeichen, kleingeschrieben alphanumerisch mit einzelnen Bindestrichen. Muss `^[a-z0-9]+(-[a-z0-9]+)*$` matchen. Keine führenden, abschließenden oder aufeinanderfolgenden Bindestriche. Gut: `scan-url`, `book-flight`, `order-status`. Schlecht: `ScanUrl`, `-scan`, `scan--url`, `scan_url`. - **`description`** — 1 bis 1024 Zeichen. Beginne mit dem Verb, das der Agent ausführen soll („Scan a URL...", „Book a flight from..."). Die Description erscheint in Tool-Pickern und im Planner-Reasoning — schreibe sie für einen Agenten, der eine Blitzentscheidung trifft. Agenten und Scanner, die der Spezifikation folgen, lehnen Dateien mit fehlerhaftem Frontmatter ab — deine Datei wird für sie faktisch unsichtbar. ## Wer SKILL.md übernommen hat Die Spezifikation entwickelte sich über 2025 von einer Single-Vendor-Konvention zu einem interoperablen Standard: - **Claude Code** ([docs.claude.com/en/docs/claude-code/skills](https://docs.claude.com/en/docs/claude-code/skills)) — Anthropics Coding-Agent lädt SKILL.md-Dateien aus lokalen Verzeichnissen und nutzt sie, um Tool-Zugriff einzugrenzen. - **OpenAI Codex** — Hat dasselbe Format für Agent-Skill-Definitionen übernommen. - **Cursor** — Liest SKILL.md aus Projekt-Workspaces für Inline-Agent-Anweisungen. - **GitHub Copilot** — Respektiert dieselbe Frontmatter-Konvention für Agent-Anweisungen auf Repository-Ebene. - **Microsoft Agent Framework** — Herstellerübergreifende Implementierungen folgen der agentskills.io-Spezifikation. Da das Format nur Markdown mit YAML-Frontmatter ist, sind die Adoptionskosten nahezu null: Jeder Agent, der bereits Markdown parst, kann es lesen; jede Website, die bereits Doku veröffentlicht, kann es schreiben. ## So fügst du SKILL.md zu deiner Website hinzu 1. **Wähle den Namen.** Eine Verb-Nomen-Phrase, kleingeschrieben mit Bindestrichen, unter 64 Zeichen. Sie sollte dem entsprechen, was der Agent mit deinem Dienst „tun" soll. `book-flight` ist gut; `flights` ist zu vage. 2. **Schreibe die Description.** Zwei Sätze. Satz 1: was der Agent erreicht. Satz 2: wann er sie nutzen soll (die Trigger-Phrase oder der Kontext). 3. **Schreibe den Body.** Endpoints mit HTTP-Verben, Auth-Modell, ein copy-paste-fähiges curl-Beispiel. Halte alles unter einer Bildschirmseite — knapp schlägt erschöpfend. 4. **Liefere unter `/skill.md` aus.** Statische Datei. `Content-Type: text/markdown`. 5. **Verlinke aus llms.txt oder `/.well-known/`.** Optional, aber empfohlen — gibt Agenten, die zuerst deine llms.txt finden, einen Pfad zur Skill-Datei. Eine Website mit gültiger SKILL.md und einer [OpenAPI](/kb/de/openapi)-Spezifikation ist gut gerüstet für jeden Agenten, der ohne Vorwissen ankommt. ## Häufige Fehler, die Scanner melden - **Fehlende Frontmatter-Trennzeichen** — die Datei beginnt nicht mit `---`, der YAML-Block wird nicht erkannt. - **Ungültiger `name`** — Großbuchstaben, Unterstriche oder führende/abschließende Bindestriche. Der häufigste Fehler. - **Description zu kurz** — unter 1 Zeichen (leer) oder so kurz, dass der Agent kein Signal hat. Ziele auf 80-200 Zeichen. - **Description zu lang** — über 1024 Zeichen. Verschiebe Details in den Body. - **Falscher Pfad** — ausgeliefert unter `/skills.md` (Plural), `/.well-known/skill.md` oder `/skill/index.md`. Die Spezifikation verlangt `/skill.md` im Dokument-Root. - **Falscher Content-Type** — ausgeliefert als `text/html`, weil ein CMS Markdown automatisch rendert. Liefere rohes `text/markdown` oder `text/plain` aus. ## Häufig gestellte Fragen **Ist SKILL.md dasselbe wie Anthropics „Claude Skills"?** Das On-Disk-Format ist dasselbe. „Claude Skills" ist Anthropics Produktname für das Feature, das SKILL.md-Dateien konsumiert; das Dateiformat selbst ist die herstellerübergreifende agentskills.io-Spezifikation. **Brauche ich SKILL.md und OpenAPI?** Veröffentliche beides, wenn du eine API hast. SKILL.md beantwortet „Wie nutze ich das?" in Prosa; OpenAPI beantwortet „Wie ist das exakte Schema?" formal. Agenten nutzen OpenAPI, um Requests zu validieren, und SKILL.md, um zu entscheiden, ob sie den Dienst überhaupt aufrufen. **Was hat `/skills.json` abgelöst?** `/skills.json` war ein frühes, selbstgebautes Manifest-Format, das jedem Standard vorausging. Es wurde von SKILL.md für die „How to use"-Schicht und von OpenAPIs `x-payment-info` (siehe [OpenAPI](/kb/de/openapi)) für die Deklaration bezahlter Endpoints abgelöst. AgentGrade bewertet `/skills.json` nicht mehr. **Wo sollte die SKILL.md-Datei liegen?** `/skill.md` im Dokument-Root. Manche Agenten proben zusätzlich `/.well-known/skill.md` als Fallback — beides zu veröffentlichen schadet nicht. **Kann eine Website mehrere SKILL.md-Dateien haben?** Die Konvention ist eine `/skill.md` pro Origin. Dienste mit mehreren klar getrennten Oberflächen (Suche vs. Checkout vs. Support) beschreiben typischerweise jede als Abschnitt in einer Datei oder teilen sie in Sub-Services auf Subdomains auf. **Ersetzt SKILL.md [MCP](/kb/de/mcp)?** Nein — sie beantworten unterschiedliche Fragen. SKILL.md erklärt einem Agenten, wie er deinen HTTP-Dienst über bestehende Endpoints nutzt. MCP definiert ein JSON-RPC-Interface, bei dem der Agent deinen Server als Tool über eine persistente Verbindung aufruft. Eine Website kann beides veröffentlichen. **Bestraft AgentGrade Websites, die SKILL.md ohne OpenAPI veröffentlichen?** Nein. SKILL.md ist für sich genommen ein positives Signal. OpenAPI ist ein separater Check. **Lesen Agenten diese Datei wirklich?** Claude Code, Codex, Cursor und Copilot lesen SKILL.md-Dateien heute in ihren Workspaces. Browsing-Agenten, die deine Website zum ersten Mal entdecken, proben zunehmend `/skill.md` als Teil des Discovery-Handshakes, neben `/llms.txt` und `/openapi.json`. ## Reifegrad der Spezifikation **Herstellerübergreifender Standard.** Definiert unter [agentskills.io](https://agentskills.io/specification). Übernommen von Claude Code, OpenAI Codex, Cursor, GitHub Copilot und Microsoft Agent Framework. In aktiver Entwicklung; die kanonische Implementierung ist gut dokumentiert. ## Mehr erfahren - [agentskills.io](https://agentskills.io/specification) — die Spezifikation - [Claude Code skills documentation](https://docs.claude.com/en/docs/claude-code/skills) — Anthropics Adoption - [OpenAPI](/kb/de/openapi) — die ergänzende Schema-Schicht - [MCP](/kb/de/mcp) — Alternative für JSON-RPC-Tool-Server - [Agent Readiness](/agent-readiness) — wie SKILL.md ins größere Bild passt