Die unbequeme Wahrheit über Agent Skills

Im Dezember 2025 veröffentlichte Anthropic Agent Skills als offenen Standard. Microsoft, Cursor und andere haben ihn übernommen. Es gibt jetzt eine Spezifikation auf agentskills.io, eine Verzeichnisstruktur, YAML-Frontmatter-Anforderungen und ein ganzes Ökosystem.

Aber bevor wir uns in Frameworks und Spezifikationen vertiefen, lassen Sie uns verstehen, was Skills eigentlich sind.

Was Anthropic sagt, dass Skills sind

Aus der offiziellen Dokumentation:

Agent Skills sind modulare Fähigkeiten, die Claudes Funktionalität erweitern. Jedes Skill verpackt Anweisungen, Metadaten und optionale Ressourcen (Skripte, Vorlagen), die Claude automatisch verwendet, wenn relevant.

Die Schlüsselerkenntnis aus Anthropics Engineering-Blog: Skills sind wiederverwendbare, dateisystembasierte Ressourcen, die Claude Fachwissen verleihen. Statt jedes Gespräch das Gleiche zu erklären, schreiben Sie es einmal als Skill.

Das Problem, das Skills lösen

Ohne Skills:

• Sie erklären Verfahren jede Session neu
• Der Kontext füllt sich mit wiederholten Anweisungen
• Keine Konsistenz über Gespräche hinweg

Mit Skills:

• Anweisungen einmal schreiben
• Nur bei Bedarf laden
• Konsistentes Verhalten über Sessions hinweg

Das ist der Pitch. Und es macht Sinn.

Die offizielle Struktur

Anthropics Spezifikation erfordert eine bestimmte Struktur:

.claude/skills/youtube-transcribe/
├── SKILL.md              # Erforderlich
├── scripts/
│   └── transcript.sh     # Optional
└── references/
    └── api-docs.md       # Optional

Die SKILL.md-Datei benötigt YAML-Frontmatter:

---
name: youtube-transcribe
description: Transkribiere YouTube-Videos zu Text. Verwende, wenn der Benutzer ein Transkript aus einer YouTube-URL extrahieren möchte.
---

# YouTube-Transkription

Um ein Video zu transkribieren:
1. Führe aus: `scripts/transcript.sh "<youtube-url>"`
2. Ausgabe wird gespeichert in: `transcripts/<video-id>.txt`

Progressive Offenlegung

Anthropic hat Skills um drei Ladeebenen herum konzipiert:

Die Idee: Laden Sie nur das, was Sie brauchen, wenn Sie es brauchen. Kippen Sie nicht alles in jedes Gespräch.

Dies ist wirklich intelligente Architektur für Kontextverwaltung.

Jetzt die unbequeme Wahrheit

Hier ist das, was die Spezifikation nicht hervorhebt:

Skills sind nur Text.

Das YAML-Frontmatter? Wird als Text zum Prompt geparst. Die Verzeichnisstruktur? Eine Konvention zur Organisation. Die "progressive Offenlegung"? Claude liest Dateien von der Festplatte.

Wenn Sie den Framework entfernen, ist ein Skill:

• Eine Beschreibung (damit Claude weiß, wann er es verwendet)
• Anweisungen (wie man die Sache macht)
• Vielleicht ein Skript (zum Ausführen)

Das ist alles.

Was das praktisch bedeutet

Betrachten Sie diese beiden Ansätze:

Ansatz A: Formelles Skill

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transkribiere YouTube-Videos zu Textdateien
---

# YouTube-Transkription
Führe aus: bun scripts/youtube-transcript.sh "<url>"

Ansatz B: Einfacher Leitfaden

guides/how-to-transcribe-youtube.md

# Wie man YouTube-Videos transkribiert
Führe aus: bun scripts/youtube-transcript.sh "<url>"

Für Claude sind diese nahezu identisch. Beide sind Textdateien mit Anweisungen. Beide können durch Suche gefunden werden. Beide sagen Claude, was zu tun ist.

Der Unterschied:

• Ansatz A: Frontmatter wird beim Start vorgeladen (~100 Token)
• Ansatz B: Claude sucht, wenn es die Information braucht

Ist das Vorladenwert der Beschreibung den Struktur-Overhead? Manchmal ja, manchmal nein.

Wenn die Struktur hilft

Die Anthropic-Struktur hilft wirklich, wenn:

Sie haben viele Skills und brauchen Auffindbarkeit

Wenn Sie 50 Fähigkeiten haben, lässt das Vorladenvon Beschreibungen Claude wissen, dass sie existieren, ohne alle 50 Dateien zu lesen. Die Metadaten fungieren als Index.

Sie wollen Slash-Befehls-Aufruf

Skills werden zu /youtube-transcribe-Befehlen. Benutzer können sie direkt aufrufen. Das ist ein echter UX-Vorteil.

Sie brauchen Werkzeugbeschränkungen

Das allowed-tools-Feld beschränkt, was ein Skill tun kann. Sicherheitsvorteil für sensible Operationen.

Sie verteilen Skills an andere

Der offene Standard bedeutet, dass Skills über Claude Code, Cursor, VS Code funktionieren. Portabilität ist wichtig.

Wenn einfache Leitfäden gewinnen

Aber oft funktionieren einfache Markdown-Leitfäden genauso gut:

Einmalige Verfahren

# Bereitstellung in Produktion
1. Tests ausführen: `bun test`
2. Erstellen: `bun run build`
3. Bereitstellen: `./deploy.sh production`

Muss dies ein formelles Skill sein? Wahrscheinlich nicht. Es ist ein Leitfaden. Claude findet es bei Bedarf.

Projektspezifisches Wissen

# Unsere Markenstimme
- Professionell, aber zugänglich
- Kein Jargon, wenn nicht erklärt
- Beispiele statt Abstraktionen

Dies ist Kontext, keine Fähigkeit. Eine Markdown-Datei in docs/ ist in Ordnung.

Schnelle Referenzen

# API-Anmeldedaten
- Google Analytics: Eigenschaft 478766521
- Mailgun: Überprüfe .env für MAILGUN_API_KEY
- Sentry: Projekt teamday-cc

Indexinformation. Braucht keine progressive Offenlegung.

Das Spektrum

Skills existieren auf einem Spektrum von trivial bis umfassend:

One-Liner (brauchen vielleicht keine formellen Skills)

Email-Benachrichtigungen: bun scripts/mailgun.send.js --to="x" --subject="y"

Schnelle Referenzen (borderline)

# Google Analytics
Verwende die mcp__google-analytics-Tools.
Eigenschafts-ID: 478766521
Häufige Abfragen: Seitenaufrufe, Sitzungen, Top-Seiten

Schritt-für-Schritt-Leitfäden (formelles Skill macht Sinn)

# Füge YouTube-Video zum Newsfeed hinzu

1. Transkript abrufen
2. Metadaten mit curl extrahieren (nicht WebFetch!)
3. Feed-Post erstellen
4. Embeddings aktualisieren
5. Entitäten extrahieren
6. Übersetzungen auslösen

Umfassende Workflows (definitiv ein Skill)

Mehrstufige Verfahren mit Skripten, Validierung, Fehlerbehandlung. Das Newsfeed-Skill, das wir verwenden, hat über 250 Zeilen mit Unterdokumenten für spezifische Aufgaben.

Je komplexer die Fähigkeit, desto mehr zahlt sich die formelle Struktur aus.

Das Dateisystem ist dein Freund

Hier ist das, was der Anthropic Engineering-Blog hervorhebt und was oft übersehen wird:

Claude hat Dateisystemzugriff. Skripte werden über Bash ausgeführt. Referenzdateien existieren auf der Festplatte. Sie können effektiv unbegrenzte Referenzmaterialien bündeln.

Claude kann:

• Nach Dateien suchen: grep -r "transcribe" docs/
• Lesen, was gefunden wird: Read: docs/how-to-transcribe.md
• Skripte ausführen: bash scripts/transcribe.sh

Progressive Entdeckung erfordert nicht das Skill-Framework. Es erfordert gute Dateiorganisation und eine KI, die weiß, wie man sucht.

Das Skill-Framework formalisiert dies mit Metadaten. Aber der zugrunde liegende Mechanismus ist nur Dateisystemnavigation.

Kontext ist alles

Die wirkliche Einsicht aus Anthropics Design: Kontextfenster sind begrenzt.

Claudes Systemprompt in Claude Code hat angeblich 72 KB. Das sind ~18.000 Token, bevor Sie überhaupt anfangen zu arbeiten. Jede Skill-Beschreibung erhöht dies.

Das Progressive-Disclosure-Design beantwortet dies:

• Nur Metadaten beim Start (klein)
• Vollständige Anweisungen bei Auslösung (mittel)
• Skripte/Referenzen bei Bedarf (unbegrenzt, nicht im Kontext)

Aber Sie erhalten den gleichen Vorteil von:

• Minimalem Systemprompt
• Claude sucht Dokumente bei Bedarf
• Liest nur das Relevante

Das Prinzip ist wichtiger als die Implementierung.

Was wirklich zählt

Nach dem Aufbau von Dutzenden von KI-Workflows haben wir gelernt:

1. Klare Anweisungen schlagen clevere Struktur

# Generiere Blog-Cover

Wir verwenden FAL AI. Bilder werden in public/images/ gespeichert.

Führe aus:
bun scripts/generate-image.ts "prompt" name.webp

Gute Prompts:
- Stil einschließen ("minimalistische Illustration")
- Subjekt einschließen ("KI-Agenten zusammenarbeitend")
- Stimmung einschließen ("professionell, technologieorientiert")

Claude folgt diesem, egal ob es ein formelles Skill oder eine Dokumentdatei ist.

2. Auffindbarkeit ist real

Wenn Claude Ihre Anweisungen nicht finden kann, spielt Struktur keine Rolle. Egal ob durch Skill-Beschreibungen oder gute Dateinamen, machen Sie Dinge findbar.

• ✅ guides/how-to-transcribe-youtube.md
• ✅ Skill mit klarer Beschreibung
• ❌ notes/misc/stuff-v2-final.md

3. Skripte lösen Komplexität

Wenn Anweisungen komplex werden, schreiben Sie ein Skript:

# Statt 20 Zeilen Anweisungen:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

Das Skript kapselt Komplexität. Das Skill dokumentiert nur, wie man es aufruft.

4. Auf der Grundlage von Fehlern iterieren

Wenn Claude etwas falsch macht:

• Unkklare Anweisung? → Verbessere den Text
• Fehlende Information? → Füge sie hinzu
• Kann es nicht finden? → Bessere Benennung oder zur Skill-Indexphinzufügen

Fügen Sie keine defensiven Regeln hinzu. Behebe das eigentliche Problem.

Die Quintessenz

Anthropic hat ein durchdachtes System zur Organisation von KI-Fähigkeiten gebaut. Progressive Disclosure ist clever. Der offene Standard ermöglicht Portabilität. Slash-Befehle verbessern die UX.

Aber hier ist die unbequeme Wahrheit:

Skills sind nur Textanweisungen, die Claude aus Dateien liest.

Das Framework fügt hinzu:

• Vorgeladene Beschreibungen (Index)
• Slash-Befehls-Aufruf
• Werkzeugbeschränkungen
• Plattformübergreifende Portabilität

Dies sind echte Vorteile für komplexe Setups mit vielen Fähigkeiten.

Aber für alltägliche Arbeit:

• Eine gut benannte Markdown-Datei funktioniert
• Claude kann suchen und Dinge finden
• Klare Anweisungen zählen mehr als Struktur
• Das Dateisystem ist bereits ein Entdeckungssystem

Nicht über-engineeren. Beginnen Sie mit einfachen Leitfäden. Fügen Sie formelle Skill-Struktur hinzu, wenn die Vorteile den Overhead rechtfertigen.

Schreiben Sie klar. Organisieren Sie sinnvoll. Lassen Sie Claude seine Arbeit machen.

Bei TeamDay verwenden wir beide Ansätze. Formelle Skills für komplexe Workflows wie Newsfeed-Management. Einfache Leitfäden für einmalige Verfahren. Der Schlüssel ist, das Werkzeug der Aufgabe anzupassen.