Offizielles Tutorial zu Anthropic Agent Skills: Komplette Notizen zum 6-Lektionen-Kurs

Anthropic hat endlich ein offizielles Tutorial-Video zu Agent Skills veröffentlicht, bestehend aus 6 Lektionen mit einer Gesamtdauer von 22 Minuten. Es deckt den gesamten Lebenszyklus von Skills ab – von der Definition über die Erstellung, Konfiguration von Multi-File-Setups, Abgrenzung zu anderen Funktionen, Freigabe bis hin zur Fehlerbehebung.

Der größte Wert dieses Tutorials liegt nicht nur darin, dir beizubringen, wie man einen Skill schreibt, sondern die Design-Philosophie und die zugrundeliegenden Mechanismen von Skills zu erklären. Viele Probleme, die bei der Nutzung von Skills auftreten, sind auf ein unzureichendes Verständnis dieser Mechanismen zurückzuführen.

Welche Probleme lösen Skills?

Jedes Mal, wenn du Claudes die Codierungsstandards deines Teams erklärst, wiederholst du dich. Bei jedem PR-Review musst du erneut beschreiben, wie du das Feedback organisiert haben möchtest. Bei jeder Commit-Nachricht musst du Claude an dein bevorzugtes Format erinnern.

Skills wurden entwickelt, um diese Wiederholungen zu vermeiden. Ein Skill ist eine Markdown-Datei, die Claude einmal beibringt, wie etwas zu tun ist, und Claude wendet dieses Wissen dann automatisch in relevanten Situationen an.

Genauer gesagt ist ein Agent Skill ein Ordner, der Anweisungen, Skripte und Ressourcen enthält. Claude kann diese automatisch erkennen und nutzen, um Aufgaben genauer und effizienter zu erledigen.

Der Kernmechanismus ist das Feld description. Wenn Claude startet, lädt es die Namen und Beschreibungen aller Skills. Wenn du eine Anfrage stellst, führt Claude einen semantischen Abgleich zwischen deiner Anfrage und den Beschreibungen aller verfügbaren Skills durch, um den passenden zu finden und zu aktivieren. Erst bei der Aktivierung wird der vollständige Skill-Inhalt in den Kontext geladen.

Dies unterscheidet sich grundlegend von claude.md. Der Inhalt von claude.md wird in jedes Gespräch geladen, unabhängig davon, was du tust. Ein Skill wird nur bei Bedarf geladen; deine PR-Review-Checkliste muss nicht während des Debuggens im Kontext sein, sondern erscheint nur, wenn du tatsächlich einen Review anforderst.

Wann solltest du einen Skill verwenden? Wenn du feststellst, dass du Claude immer wieder dasselbe erklären musst, ist das ein Skill, der darauf wartet, entwickelt zu werden.

Erstellen deines ersten Skills von Grund auf

Das Erstellen eines Skills erfordert nur zwei Schritte: Erstellen eines Verzeichnisses und Schreiben einer Datei.

Schritt eins: Erstelle ein Verzeichnis mit dem Namen des Skills unter ~/.claude/skills/. Wenn du es hier platzierst, handelt es sich um einen Skill auf persönlicher Ebene, der projektübergreifend verfügbar ist.

Schritt zwei: Erstelle eine Datei namens SKILL.md im Verzeichnis. Die Datei ist in zwei Teile geteilt, getrennt durch drei Gedankenstriche. Der obere Teil sind YAML-Metadaten, die name und description enthalten. Der untere Teil enthält die spezifischen Anweisungen, die Claude befolgen soll.

Wenn Claude Code startet, durchsucht es vier Speicherorte nach Skills: Unternehmenspfade, persönliches Skills-Verzeichnis, Projekt-Skills-Verzeichnis und installierte Plugins. Es lädt nur den Namen und die Beschreibung jedes Skills, nicht den vollständigen Inhalt.

Wenn du eine Anfrage sendest, vergleicht Claude die Anfrage mit allen Skill-Beschreibungen. Wenn die Absicht übereinstimmt, fragt es dich zuerst, ob du den Skill laden möchtest. Erst nach der Bestätigung liest es die vollständige Datei und führt die Anweisungen aus. Dieser Bestätigungsschritt hält dich darüber informiert, welchen Kontext Claude verwendet.

Wenn Skills mit demselben Namen existieren, ist die Priorität von hoch zu niedrig: Unternehmensebene (managed-settings.json), Persönliche Ebene (~/.claude/skills), Projektebene (project/.claude/skills) und Plugin-Ebene (project/.claude-plugins/skills).

Das bedeutet, dass ein Unternehmen Standards durch Skills auf Unternehmensebene durchsetzen kann, während Einzelpersonen durch Skills mit anderen Namen Anpassungen vornehmen können. Wenn dein Unternehmen einen Code-Review-Skill auf Unternehmensebene hat, kannst du einen persönlichen Skill namens front-end-pr-review erstellen, um diesen zu ergänzen, anstatt ihn zu überschreiben.

Erweiterte Konfiguration: Metadatenfelder und Progressive Disclosure

Basis-Skills benötigen nur name und description, aber mehrere erweiterte Konfigurationen können Skills leistungsfähiger machen.

Das Feld allowed-tools kann einschränken, welche Tools Claude verwenden darf, wenn der Skill aktiv ist. Wenn du beispielsweise einen schreibgeschützten Analyse-Skill hast, kannst du Bearbeitungs-, Schreib- und Bash-Befehle verbieten. Wenn dieses Feld weggelassen wird, hat der Skill keine Einschränkungen und Claude verwendet das normale Berechtigungsmodell.

Das Feld model kann angeben, welche Version des Claude-Modells verwendet werden soll.

Die Art und Weise, wie die description geschrieben wird, bestimmt direkt, ob ein Skill korrekt ausgelöst werden kann. Eine gute Beschreibung sollte zwei Fragen beantworten: Was macht dieser Skill? Wann sollte Claude ihn verwenden? Wenn ein Skill nicht ausgelöst wird, füge weitere Schlüsselwörter hinzu, die mit der Formulierung deiner Anfragen übereinstimmen.

Das wichtigste erweiterte Konzept ist die progressive Offenlegung. Skills teilen sich das Kontextfenster mit deinem Gespräch. Wenn du alles in eine 20.000-zeilige SKILL.md stopfst, wird dies massiv Kontextplatz verbrauchen.

Der richtige Ansatz ist: Platziere die wesentlichen Anweisungen in SKILL.md und detaillierte Referenzmaterialien in separaten Dateien, die Claude nur bei Bedarf liest. Die empfohlene Verzeichnisstruktur für offene Standards ist: ein scripts-Ordner für ausführbaren Code, references für Referenzdokumente und resources für Datendateien wie Bilder und Vorlagen. Verwende Links in SKILL.md, um auf diese Dateien zu verweisen.

Wichtige Regel: SKILL.md sollte 500 Zeilen nicht überschreiten. Wenn doch, sollte es aufgeteilt werden. Skripte können direkt ausgeführt werden, ohne dass ihr Inhalt in den Kontext geladen wird; nur die Ausgabe verbraucht Tokens. Sage Claude also, er soll das Skript ausführen, anstatt es zu lesen. Dies ist besonders nützlich für Umgebungsvalidierung und Datentransformation, da getesteter Skriptcode zuverlässiger ist als Ad-hoc-Generierung.

Unterschiede zwischen Skills und anderen Claude Code-Funktionen

Skills vs. claude.md: claude.md wird immer in jedes Gespräch geladen, für Projektstandards und Regeln, die immer gelten, wie z. B. "Dieses Projekt verwendet TypeScript Strict Mode." Skills werden bei Bedarf geladen, nur wenn Claude eine Anfrage zuordnet.

Skills vs. Sub Agents: Skills fügen dem aktuellen Gespräch Wissen hinzu; sobald sie aktiviert sind, werden die Anweisungen zum bestehenden Kontext hinzugefügt. Sub Agents laufen in einem unabhängigen Kontext, erledigen Aufgaben und reichen Ergebnisse separat ein, vollständig isoliert vom Hauptgespräch.

Skills vs. Hooks: Hooks sind ereignisgesteuert und werden ausgelöst, wenn bestimmte Ereignisse eintreten, z. B. wenn Claude jedes Mal einen Linter ausführt, wenn eine Datei gespeichert wird. Skills sind anforderungsgesteuert und werden basierend auf den Fragen aktiviert, die du stellst.

Skills vs. MCP: MCP stellt externe Tool-Verbindungen bereit, sodass Claude Dienste wie Gmail oder Notion aufrufen kann. Skills bieten Wissen und Arbeitsabläufe und sagen Claude, wie er diese Tools verwenden soll, um bestimmte Aufgaben zu erledigen.

Zusammenfassung in einem Satz: claude.md enthält immer aktive Anweisungen, Skills enthalten automatisch zugeordnetes Fachwissen, Sub Agents führen delegierte Aufgaben in isolierten Kontexten aus, Hooks reagieren auf Ereignisse und MCP verbindet mit externen Tools. Sie können kombiniert werden.

Skills teilen: Von Einzelpersonen zu Teams zu Organisationen

Der Wert von Skills liegt im Teilen. Ein PR-Review-Skill, der nur von dir selbst verwendet wird, ist hilfreich, aber ein im Team geteilter Skill kann Code-Reviews standardisieren und ein konsistentes Erlebnis bieten.

Drei Möglichkeiten zum Teilen:

Erstens das Projektverzeichnis. Committe den Skill in das .claude/skills-Verzeichnis des Code-Repositorys. Jeder, der das Repo klont, erhält diese Skills automatisch ohne zusätzliche Installation. Updates werden beim nächsten Pull erhalten. Dies eignet sich für Team-Codierungsstandards und projektspezifische Arbeitsabläufe.

Zweitens Plugins. Betrachte Plugins als eine Möglichkeit, Skills projektübergreifend zu verteilen. Sobald sie in einem App Store hochgeladen wurden, können andere Benutzer sie herunterladen und installieren. Wenn dein Skill generisch und nicht projektspezifisch ist, ist dies die beste Wahl für Community-Mitglieder.

Drittens Unternehmensbereitstellung. Administratoren pushen Skills über verwaltete Einstellungen an die gesamte Organisation. Skills auf Unternehmensebene haben die höchste Priorität und überschreiben persönliche und Projekt-Skills mit demselben Namen. Dies wird für verbindliche Standards, Sicherheitsanforderungen und Compliance-Workflows verwendet.

Ein wichtiger Hinweis: Sub Agents erben deine Skills nicht automatisch. Wenn du einem Sub-Agent eine Aufgabe delegierst, startet dieser mit einem frischen Kontext. Integrierte Agenten (Explorer, Plan, Verify) können überhaupt nicht auf Skills zugreifen; nur benutzerdefinierte Sub-Agents, die du definierst, können sie verwenden, und sie müssen explizit in agent.md aufgeführt werden.

Um einen benutzerdefinierten Sub-Agent mit Skills zu erstellen, erstelle eine Datei agent.md im Verzeichnis .claude/agents und füge ein Feld skills hinzu, das die erforderlichen Skill-Namen auflistet. Liste nur Skills auf, die für das Ziel des Sub-Agents immer relevant sind, da diese Skills beim Start des Sub-Agents geladen werden.

Fehlerbehebungsleitfaden: Sechs Gründe, warum Skills fehlschlagen, und ihre Lösungen

Probleme mit Skills fallen normalerweise in sechs Kategorien:

1. Skill wird nicht ausgelöst: Der Grund ist fast immer eine schlecht geschriebene description. Claude verwendet semantischen Abgleich; deine Anfrage muss mit der Bedeutung der Beschreibung übereinstimmen. Wenn es nicht genug Überschneidungen gibt, wird es nicht übereinstimmen. Lösung: Vergleiche die Beschreibung mit der Formulierung deiner Anfrage und füge Auslösephrasen hinzu, die Benutzer tatsächlich sagen, wie "hilf mir zu analysieren", "warum ist das langsam" oder "beschleunige es".

1. Skill kann nicht geladen werden: Überprüfe Pfade und Dateinamen. SKILL.md muss sich in einem benannten Verzeichnis befinden, nicht direkt im Skills-Stammverzeichnis. Der Dateiname muss exakt SKILL.md in Großbuchstaben sein. Führe claude --debug aus, um Ladefehler anzuzeigen.

1. Claude verwendet den falschen Skill: Das bedeutet, dass du mehrere Skills mit zu ähnlichen Beschreibungen hast, sodass Claude sie nicht unterscheiden kann. Lösung: Mache jede Beschreibung so spezifisch wie möglich, um Claude zu helfen, zu entscheiden, wann welche verwendet werden soll.

1. Persönlicher Skill wird ignoriert: Ein Skill mit höherer Priorität (z. B. ein Unternehmens-Skill) mit demselben Namen überschreibt ihn möglicherweise. Überprüfe die vier Prioritätsebenen. Lösung: Benenne deinen Skill in einen eindeutigeren Namen um.

1. Plugin installiert, aber Skill nicht sichtbar: Lösche den Cache mit rm ~/.claude/plugins/cache, starte Claude Code neu und installiere es erneut. Wenn es immer noch nicht funktioniert, stimmt möglicherweise die Verzeichnisstruktur des Plugins nicht; verwende das Validierungstool skills-ref validate, um dies zu überprüfen.

1. Skill geladen, schlägt aber während der Ausführung fehl: Wenn der Skill externe Pakete verwendet, stelle sicher, dass diese installiert sind. Füge Abhängigkeitsinformationen zur Beschreibung des Skills hinzu.

Anthropic bietet auch ein Validierungstool namens skills-ref an, um zu überprüfen, ob die Dateistruktur und die YAML-Syntax des Skills korrekt sind. Es wird empfohlen, es über uv zu installieren, da dies die schnellste Methode ist.