Kapitel 23: Agent Skills – Modulares Expertenwissen & "Skills over MCP"

In Kapitel 8 haben wir das Problem der Tool-Überladung ("Tool-Fatigue") besprochen. Wenn ein Modell hunderte Werkzeuge gleichzeitig im Kontext halten muss, steigen Kosten, Latenz und Fehlerrate dramatisch. Die modernste und eleganteste Antwort darauf sind Agent Skills: strukturierte Wissenspakete, die eine standardisierte Anleitung (SKILL.md), optionale Skripte und Referenzdokumente bündeln und nach dem Prinzip der Progressive Disclosure (schrittweisen Offenlegung) erst genau dann in den Kontext geladen werden, wenn das Modell sie wirklich benötigt.

Seit 2025/2026 existiert hierfür ein starkes, zweistufiges Standard-Ökosystem:

1. Das offene Skill-Dateiformat (agentskills.io): Ursprünglich von Anthropic im Herbst 2025 freigegeben, wird das ordnerbasierte Format heute vendorneutral von Claude Code, Google Gemini CLI, OpenAI Codex und modernen Agentic IDEs unterstützt.
2. Die offizielle MCP-Erweiterung "Skills over MCP" (io.modelcontextprotocol/skills): Mit der MCP-Spezifikationsrevision 2026-07-28 und dem am 13. September 2026 finalisierten SEP-2640 wurde die Brücke direkt in das Model Context Protocol geschlagen. MCP-Server können Skills nun nativ deklarieren, über das Protokoll (skills/list) ankündigen und deren Inhalte über standardisierte skill://-Ressourcen an entfernte oder lokale Clients ausliefern.

1. Was ist ein Agent Skill?

Im Kern ist ein Skill ein klar abgegrenzter Ordner, der eine einzige Domäne oder komplexe Aufgabe modular kapselt:

pdf-processing/
├── SKILL.md          # Pflicht: YAML-Frontmatter + Markdown-Anleitung
├── FORMS.md          # Optional: Vertiefung auf Stufe 3 (bei Bedarf)
├── REFERENCE.md      # Optional: API- oder Syntaxreferenz
└── scripts/
    └── fill_form.py  # Optionale ausführbare Hilfsskripte

Die zwei Pflichtfelder der Frontmatter sind name und description:

---
name: pdf-processing
description: Füllt ausfüllbare PDFs aus, extrahiert Tabellen und erzeugt formatkonforme Berichte.
             Einsatz bei jeder Aufgabe mit .pdf-Dateien (Lesen, Ausfüllen, Umwandeln).
---
# PDF Processing

1. Prüfe mit `qpdf --check` die Struktur der Datei…
2. Formulare: verwende das Skript `scripts/fill_form.py` …

Der fundamentale Unterschied: Tool vs. Skill

Ein häufiges Missverständnis von Einsteigern ist die Verwechslung von Tools und Skills. Sie stehen nicht in Konkurrenz, sondern ergänzen sich:

Kurz gesagt: Tools sind das Wie-funktioniere-ich (die Aktionsfläche), Skills sind das Was-weiß-ich (das Domänenwissen). Tools erweitern die Handlungsmöglichkeiten des Modells, Skills leiten es an, diese Handlungen fehlerfrei in der richtigen Reihenfolge durchzuführen.

2. Progressive Disclosure – der Kern des Musters

Das tragende Prinzip von Agent Skills ist Progressive Disclosure (schrittweise Offenlegung). Statt das gesamte Wissen zu Beginn in das Kontextfenster zu werfen, wird der Kontext in drei Stufen nachgeladen:

1. Stufe 1 – Metadaten (immer geladen): Beim Start erfährt das System nur von der Existenz des Skills (name und description). Kostenpunkt: Nur rund 50–100 Token pro Skill. 50 installierte Skills belegen kaum 4.000 Token.
2. Stufe 2 – Anleitung / Workflow (bei Trigger geladen): Erkennt das Modell aus der Benutzeranfrage, dass ein Skill relevant ist, lädt es den Haupttext der SKILL.md. Kostenpunkt: Rund 1.000–4.000 Token – aber ausschließlich für den aktuell bearbeiteten Task.
3. Stufe 3+ – Spezifische Assets & Skripte (nur bei punktuellem Zugriff): Vertiefende Dateien wie FORMS.md oder Skripte aus scripts/ werden nur geladen oder ausgeführt, wenn ein konkreter Einzelschritt dies verlangt. Die Ausgabe eines Skripts gelangt in den Kontext, nicht zwingend das Skript selbst.

3. Zwei Wege der Bereitstellung: Dateisystem vs. "Skills over MCP"

Wie gelangen Skills zum Agenten? Das Ökosystem bietet zwei komplementäre Wege:

                 ┌──────────────────────┐
                 │    Agent / Client    │
                 └──────────┬───────────┘
     ┌──────────────────────┴─────────┐
     ▼                                ▼
     Pfad A: lokal                    Pfad B: MCP-Protokoll
     ~/.agents/skills/<name>/         io.modelcontextprotocol/skills
                                      (SEP-2640)

     ① Startup-Scan                   ① skills/list
     ② read_file(SKILL.md)            ② resources/read(skill://…)
     ③ Ausführung lokal               ③ resources/read(skill://…)

Pfad A: Lokale Dateisystem-Skills (`.agents/skills/`)

Für rein lokale Coding-Assistenten (Claude Code, Gemini CLI, OpenAI Codex) liegen Skills direkt auf der Festplatte:

• Global: ~/.agents/skills/<skill-name>/ (oder herstellerspezifische Pfade wie ~/.claude/skills/)
• Projektbezogen: .agents/skills/<skill-name>/ im Arbeitsverzeichnis.

Der Client scannt die Verzeichnisse beim Start, injiziert die Metadaten in den Systemprompt und liest bei Bedarf mit seinen nativen Datei-Werkzeugen (read_file, cat) nach.

Pfad B: Protokollbasiert via "Skills over MCP" (`io.modelcontextprotocol/skills` / SEP-2640)

Wenn Sie einen MCP-Server betreiben – insbesondere einen Remote-Server über Streamable HTTP – hat der entfernte Client keinen Zugriff auf Ihr lokales Dateisystem. Genau hier greift die Spezifikation SEP-2640:

1. Capability-Aushandlung: Beim Handshake meldet der Server seine Fähigkeit:

   {
     "capabilities": {
       "io.modelcontextprotocol/skills": {}
     }
   }

2. Discovery via skills/list: Der Client fragt ab, welche Skills der Server mitbringt:

   // Request
   { "jsonrpc": "2.0", "id": 1, "method": "skills/list", "params": {} }
   
   // Response
   {
     "jsonrpc": "2.0",
     "id": 1,
     "result": {
       "skills": [
         {
           "name": "pdf-processing",
           "description": "Füllt ausfüllbare PDFs aus und extrahiert Tabellen...",
           "uri": "skill://pdf-processing",
           "files": [
             { "path": "SKILL.md", "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
             { "path": "scripts/fill_form.py", "digest": "sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069" }
           ]
         }
       ]
     }
   }

   Vorteil: Der Client erhält sofort die Stufe 1 (Name + Description) und ein Manifest mit kryptografischen Prüfsummen (Digests) aller Dateien.

3. Content Delivery via MCP-Resources (skill:// URI): Anstatt ein neues Übertragungsverfahren zu erfinden, nutzt SEP-2640 die bestehende Resources-Primitive (resources/read). Sobald das LLM die SKILL.md lesen möchte, fordert der Client sie über das standardisierte skill://-Schema an:

   // Request
   {
     "jsonrpc": "2.0",
     "id": 2,
     "method": "resources/read",
     "params": {
       "uri": "skill://pdf-processing/SKILL.md"
     }
   }
   
   // Response
   {
     "jsonrpc": "2.0",
     "id": 2,
     "result": {
       "contents": [
         {
           "uri": "skill://pdf-processing/SKILL.md",
           "mimeType": "text/markdown",
           "text": "---\nname: pdf-processing\n...\n# PDF Processing Guide\n..."
         }
       ]
     }
   }

Durch die Prüfsummen (Digests) aus Schritt 2 kann der MCP-Host zu 100 % sicherstellen, dass die empfangenen Dateien exakt dem freigegebenen Stand entsprechen.

4. Implementierungsbeispiel in Go

Hier ist ein kompakter Entwurf, wie ein MCP-Server mit dem offiziellen Go-SDK die Extension io.modelcontextprotocol/skills bereitstellt:

package main

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"os"
	"strings"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

type SkillFileManifest struct {
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

type SkillEntry struct {
	Name        string              `json:"name"`
	Description string              `json:"description"`
	URI         string              `json:"uri"`
	Files       []SkillFileManifest `json:"files"`
}

func RegisterSkillsExtension(server *mcp.Server, skillsDir string) {
	// 1. Capability für Skills deklarieren
	server.AddCapability("io.modelcontextprotocol/skills", map[string]any{})

	// 2. Handler für skills/list (Stufe 1 Discovery)
	server.RegisterMethod("skills/list", func(ctx context.Context, req mcp.Request) (any, error) {
		// Liest lokal SKILL.md-Frontmatter & berechnet SHA-256 Hashes
		content, _ := os.ReadFile(skillsDir + "/pdf-processing/SKILL.md")
		hash := sha256.Sum256(content)

		return map[string]any{
			"skills": []SkillEntry{
				{
					Name:        "pdf-processing",
					Description: "Füllt ausfüllbare PDFs aus und extrahiert Tabellen...",
					URI:         "skill://pdf-processing",
					Files: []SkillFileManifest{
						{Path: "SKILL.md", Digest: "sha256:" + hex.EncodeToString(hash[:])},
					},
				},
			},
		}, nil
	})

	// 3. Resource-Handler für das skill:// URI-Schema (Stufe 2 & 3 Delivery)
	server.RegisterResourceHandler("skill", func(ctx context.Context, uri string) (*mcp.ResourceContent, error) {
		// Beispiel-URI: skill://pdf-processing/SKILL.md
		relPath := strings.TrimPrefix(uri, "skill://")
		filePath := fmt.Sprintf("%s/%s", skillsDir, relPath)

		data, err := os.ReadFile(filePath)
		if err != nil {
			return nil, fmt.Errorf("skill-datei nicht gefunden: %w", err)
		}

		return &mcp.ResourceContent{
			URI:      uri,
			MIMEType: "text/markdown",
			Text:     string(data),
		}, nil
	})
}

5. Skills vs. MCP-Tools: Die perfekte Symbiose

Ein Skill liefert in der Praxis das Drehbuch für die Werkzeuge, die der MCP-Server bereits anbietet:

MCP-Server "Document-Suite"
  ├── Tools (Aktionsfläche):
  │     ├── convert_to_pdf(input_path)
  │     ├── extract_tables(pdf_path)
  │     └── sign_document(pdf_path, cert_id)
  │
  └── Skills (Orchestrierung & Domänenwissen):
        └── skill://contract-review/
              ├── SKILL.md   1. Rufe convert_to_pdf auf.
              │              2. Extrahiere Klauseln.
              │              3. Bei Freigabe sign_document.
              └── templates/compliance_checklist.md

Ohne Skill muss der Benutzer oder der Entwickler mühsam im Systemprompt erklären, in welcher Reihenfolge Tools kombiniert werden dürfen. Mit Skills over MCP liefert der Server die Werkzeuge zusammen mit der Bedienungsanleitung aus – ohne den Prompt des Modells permanent zu überfrachten.

6. Architektur-Varianten der Skill-Aktivierung

Wie entscheidet der Agent, wann ein Skill geladen wird? In der Praxis existieren vier Muster:

A. Expliziter Trigger (Slash-Command)

Der Benutzer gibt z. B. /security ein. Der Client lädt die passende SKILL.md sofort ohne LLM-Entscheidung in den Kontext. Null Token-Kosten für die Auswahl, setzt aber Wissen beim Nutzer voraus.

B. Router-Chain (Klassifizierungs-Vorstufe)

Ein kleines, günstiges Modell (z. B. Flash oder Haiku) prüft die Anfrage und weist das Haupt-Modell an: "Nutze Skill security-audit". Verhindert Fehlaktivierungen bei geringen Kosten.

C. Agentische Selbst-Aktivierung (Standard)

Das Modell vergleicht die Benutzeranfrage autonom mit den Skill-Beschreibungen aus Stufe 1 (skills/list bzw. Systemprompt) und löst selbstständig den Abruf der SKILL.md aus. Am flexibelsten, aber stark von präzisen Beschreibungen abhängig.

D. Umgebungs-Trigger (Kontext-Vorfilter)

Der Client scannt die Umgebung vor dem Start: Findet er eine go.mod, schaltet er den Go-Skill aktiv; bei einer package.json den Node-Skill. Reduziert die Stufe-1-Liste drastisch.

7. Metadaten-Qualität: Das Discovery-Problem

Die description ist das Herzstück des Discovery-Prozesses. Da das Modell in Stufe 1 ausschließlich diesen Text liest, entscheidet er allein über Aktivierung oder Ignorieren:

• Schlecht: "Hilft bei Go-Programmierung."
  $\rightarrow$ Zu generisch; das Modell kann den Skill nicht gegen Konkurrenten abgrenzen.
• Gut: "Experte für Go-Backend-Services mit dem Gin-Framework. Spezialisiert auf API-Design, JWT-Authentifizierung und SQL-Optimierung; nutzt chi-mw als Konvention."
  $\rightarrow$ Enthält die Domäne, Trigger-Begriffe und klare Abgrenzungen.

Die 4 goldenen Regeln für Skill-Beschreibungen:

1. Präzises Fachgebiet: Niemals nur "Code-Hilfe" schreiben.
2. Trigger-Begriffe: 3–5 typische Schlüsselwörter aufnehmen, die in relevanten Nutzeranfragen fallen (z. B. Dateiendungen, CLI-Tools, Framework-Namen).
3. Differenzierung: Den Unterschied zu Nachbar-Skills explizit nennen ("Für Go-Web-APIs; für CLI-Tools nutze go-cli").
4. Kompaktheit: Unter ~250 Zeichen bleiben, um die Stufe-1-Tokenlast minimal zu halten.

8. Praxis-Beispiel: Ein vollständiger Security-Audit Skill

Hier ist ein vollständiger, produktionsreifer Skill:

security-audit/
├── SKILL.md
├── templates/report.md
└── scripts/owasp_scan.py

`security-audit/SKILL.md`

---
name: security-audit
description: Auditiert Source-Code auf OWASP Top 10 Befunde (SQLi, XSS, CSRF)
             und dokumentiert sie als Markdown-Bericht. Einsatz bei Code-Reviews
             oder wenn Nutzer "Security" / "Sicherheits-Audit" anfragt.
---
# Security Audit

## Vorbereitung (Scope klären)
1. Kläre bei Bedarf den Zielpfad; nutze `glob_files`, um Kandidaten einzugrenzen.
2. Lade das Berichts-Template aus `templates/report.md`.

## Prüfschritte
1. Suche mit `grep_search` nach unsicheren SQL-Konstrukten:
   `grep -rEn "(SELECT|INSERT).*\+"`
2. Führe das lokale Prüfskript aus:
   `python3 scripts/owasp_scan.py --path .`
3. Gleiche gefundene Warnungen mit der Whitelist in `.audit-whitelist` ab.

## Berichtsausgabe
* Erstelle den Bericht unter `reports/audit-<YYYY-MM-DD>.md`.
* Keine Secrets oder Tokens im Klartext in den Chatverlauf schreiben.

9. Häufige Fehler & Fallstricke

10. Checkliste: Ist mein Skill produktionsreif?

Vor der Freigabe eines Skills im Repo oder auf einem MCP-Server sollten Sie folgende Punkte abhaken:

• Frontmatter valide: name und präzise description (unter 250 Zeichen) vorhanden?
• Progressive Disclosure: SKILL.md schlank gehalten; Detailwissen in Unterdokumente ausgelagert?
• MCP-Kompatibilität: Wenn über MCP ausgeliefert: Capability io.modelcontextprotocol/skills deklariert und skill://-Resources erreichbar?
• Integrität: Prüfsummen (Digests) für jede Datei im Manifest hinterlegt?
• Sicherheit: Keine Secrets, API-Keys oder riskanten curl | bash-Aufrufe in Skripten?
• Testfall: Wurde mit typischen Benutzerprompts verifiziert, dass das LLM Stufe 1 matched und Stufe 2 zuverlässig lädt?

Fazit

Agent Skills lösen das Kernproblem der Tool-Fatigue: Sie trennen die Aktionsfläche (MCP-Tools) vom Verfahrenswissen (Skills). Durch Progressive Disclosure bleibt das Kontextfenster frei von unnötigem Ballast.

Mit der Spezifikation SEP-2640 ("Skills over MCP") ist diese Brücke nun auch protokollarisch geschlossen: MCP-Server liefern nicht mehr nur isolierte JSON-RPC-Werkzeuge, sondern können komplette, remote-fähige Experten-Workflows via skills/list und skill:// an den Agenten übertragen.

← Kapitel 22: Programmiersprachen | Inhaltsverzeichnis | Nächstes Kapitel: Glossar →

Copyright Michael Lechner – 2026-09-27 (Aktualisiert für MCP Revision 2026-07-28 & SEP-2640 Skills over MCP)