AgentGrade
EnglishEspañolDeutsch日本語中文
← Wissensdatenbank

Skill-Datei (SKILL.md)

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 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:

---
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

DateiWer sie ausliefertWas sie beantwortetFormat
SKILL.mdDer DienstWie nutze ich diesen Dienst?Markdown + Frontmatter
OpenAPIDer DienstWelche Endpoints existieren und wie ist das Schema?JSON/YAML
MCP-ManifestDer MCP-ServerWelche Tools stellt dieser Server über JSON-RPC bereit?JSON-RPC
ai-plugin.jsonDer DienstPlugin-Metadaten für das ChatGPT-Plugin-Format (Legacy)JSON
llms.txtDer DienstWas 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:

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:

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-Spezifikation ist gut gerüstet für jeden Agenten, der ohne Vorwissen ankommt.

Häufige Fehler, die Scanner melden

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) 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?

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. Übernommen von Claude Code, OpenAI Codex, Cursor, GitHub Copilot und Microsoft Agent Framework. In aktiver Entwicklung; die kanonische Implementierung ist gut dokumentiert.

Mehr erfahren

Verwandt: Was ist KI-Agent-Readiness?