Skip to main content
Agent Skills erweitern Claude um spezialisierte Fähigkeiten, die Claude aufruft, wenn relevant. Skills werden als SKILL.md-Dateien verpackt, die Anweisungen, Beschreibungen und optionale unterstützende Ressourcen enthalten. Diese Seite behandelt auch Befehle in Agent SDK-Sitzungen. Umfassende Informationen zu Skills, einschließlich Vorteile, Architektur und Authoring-Richtlinien, finden Sie in der Agent Skills-Übersicht.

Wie Skills mit dem Agent SDK funktionieren

Bei Verwendung des Claude Agent SDK sind Skills:
  • Als Dateisystem-Artefakte definiert: Sie erstellen jeden Skill als SKILL.md-Datei in seinem eigenen Verzeichnis, z. B. .claude/skills/<name>/SKILL.md
  • Aus dem Dateisystem geladen: Das SDK lädt Skills aus Dateisystem-Speicherorten, die von settingSources (TypeScript) oder setting_sources (Python) gesteuert werden
  • Automatisch erkannt: Sobald Dateisystem-Einstellungen geladen sind, erkennt das SDK Skill-Metadaten beim Start aus Benutzer- und Projektverzeichnissen und lädt den vollständigen Inhalt, wenn Claude den Skill aufruft
  • Modell-aufgerufen: Claude wählt autonom basierend auf dem Kontext, wann sie verwendet werden
  • Benutzer-aufgerufen: Sie versenden einen Skill direkt, indem Sie /<name> in einer Eingabeaufforderung senden. Siehe Befehle in Agent SDK-Sitzungen
  • Über die skills-Option begrenzt: Erkannte Skills sind standardmäßig aktiviert. Übergeben Sie eine Liste von Skill-Namen, "all" oder [], um zu steuern, welche Skills Claude aufrufen kann
Im Gegensatz zu Subagenten, die Sie in der agents-Option definieren können, erstellen Sie Skills als Dateien auf der Festplatte. Das SDK bietet keine programmatische API zum Registrieren von Skills.
Skills werden durch die Dateisystem-Einstellungsquellen erkannt. Mit Standard-query()-Optionen lädt das SDK Benutzer- und Projektquellen, sodass Skills in ~/.claude/skills/, <cwd>/.claude/skills/ und .claude/skills/ in jedem übergeordneten Verzeichnis von <cwd> bis zur Repository-Root verfügbar sind. Die Projektquelle deckt auch <dir>/.claude/skills/ in jedem Verzeichnis ab, das Sie über additionalDirectories (TypeScript) oder add_dirs (Python) übergeben, da das SDK diese Verzeichnisse an Claude Code als --add-dir übergibt. Wenn Sie settingSources explizit festlegen, schließen Sie 'project' ein, um Projekt- und hinzugefügte Verzeichnis-Skills beizubehalten, und 'user', um Ihre persönlichen Skills beizubehalten, oder verwenden Sie die plugins-Option, um Skills aus einem bestimmten Pfad zu laden.

Skills mit dem Agent SDK verwenden

Legen Sie die skills-Option auf query() fest, um zu steuern, welche Skills Claude in der Sitzung aufrufen kann. Wenn weggelassen, sind erkannte Skills aktiviert und das Skill-Tool ist verfügbar, was dem CLI-Verhalten entspricht. Übergeben Sie "all", um Claude jeden erkannten Skill aufrufen zu lassen, eine Liste von Skill-Namen, um nur diese zu erlauben, oder [], um Claude keinen aufrufen zu lassen. Um Claude beispielsweise nur zwei benannte Skills aufrufen zu lassen:

Skills in einer Sitzung einrichten

Wenn Sie skills festlegen, fügt das SDK das Skill-Tool automatisch zu allowedTools hinzu. Wenn Sie auch eine explizite tools-Liste übergeben, schließen Sie "Skill" in diese Liste ein, damit Claude Skills aufrufen kann. Nach der Konfiguration erkennt Claude automatisch Skills aus dem Dateisystem und ruft sie auf, wenn sie für die Anfrage des Benutzers relevant sind. Das folgende Beispiel aktiviert jeden erkannten Skill in einer Sitzung und genehmigt die Tools vorab, die Skills häufig benötigen. Das Beispiel setzt cwd auf das aktuelle Arbeitsverzeichnis des Prozesses, daher führen Sie es in einem Projekt aus, das ein .claude/skills/-Verzeichnis im aktuellen Verzeichnis oder einem übergeordneten Verzeichnis bis zur Repository-Root hat:

Bestätigen Sie, dass Skills geladen wurden

Nahe am Anfang des Streams gibt das SDK eine Systemmeldung mit dem Subtyp init aus. Überprüfen Sie sein skills-Array, um zu bestätigen, dass Ihre Skills geladen wurden, bevor Claude mit der Arbeit beginnt. Das Array enthält die benutzer-aufgerufenen Skills, die Sie definiert haben, zusammen mit gebündelten Skills, die in Claude Code enthalten sind. Das Array listet nur benutzer-aufgerufene Skills auf. Ein Skill mit user-invocable: false in seinem Frontmatter wird geladen und bleibt für Claude verfügbar, erscheint aber nicht im Array. Das Array listet die gleichen Skills auf, unabhängig davon, ob sie sich in Ihrer skills-Liste befinden oder nicht.

Nur bestimmte Skills erlauben

Um Claude nur bestimmte Skills aufrufen zu lassen, übergeben Sie ihre Namen in der skills-Liste. Namen entsprechen dem name-Feld in SKILL.md oder dem Skill-Verzeichnisnamen. Verwenden Sie plugin:skill für von Plugins bereitgestellte Skills. Die Liste akzeptiert nur exakte Skill-Namen. Wenn ein Eintrag nicht als exakter Name funktionieren kann, lehnt query() die Liste ab, bevor die Sitzung beginnt. Siehe Fehler bei ungültigem Skill-Namen für die Namenregeln und den Fehler, den jedes SDK auslöst. Das Modell sieht nicht aufgelistete Skills nicht und das Skill-Tool lehnt sie ab, während ihre Dateien auf der Festplatte bleiben und über Read und Bash erreichbar bleiben. Das Einschränken der Liste schränkt nicht Versand nach Name ein. Um Claude jeden erkannten Skill aufrufen zu lassen, übergeben Sie skills: "all" anstelle eines Platzhalters.

Befehle in Agent SDK-Sitzungen

Dieser Abschnitt ist die Befehlsdokumentation des SDK. Ein Befehl ist alles, was Sie ausführen, indem Sie /<name> in einer Eingabeaufforderung senden. Einträge auf der Befehlsoberfläche unterscheiden sich darin, was sie unterstützt:
  • Integrierte Befehle: Führen Logik aus, die in den Claude Code-Prozess codiert ist, den das SDK ausführt, zum Beispiel /compact
  • Gebündelte Skills: Eingabeaufforderungs-Artefakte, die mit Claude Code geliefert werden, zum Beispiel /code-review
  • Ihre Skills: Eingabeaufforderungs-Artefakte, die Sie erstellen, jeweils ein Verzeichnis mit einer SKILL.md-Datei. Der Name einer vom Benutzer aufzurufenden Skill wird automatisch zur Oberfläche hinzugefügt, sodass das Versenden Ihres eigenen /security-check und das Ausführen eines integrierten Befehls auf die gleiche Weise funktionieren
  • Benutzerdefinierte Befehlsdateien: eine ältere Artefaktform mit dem gleichen Verhalten, flache Markdown-Dateien in .claude/commands/, deren Dateinamen zu Befehlsnamen werden. Skills sind ihr empfohlener Nachfolger
Standardmäßig können sowohl Sie als auch Claude jede Skill aufrufen. Sie können jeden Pfad durch die Frontmatter der Skill einschränken. Für eine Definition der beiden Begriffe siehe die Einträge Befehl und Skill im Glossar. Siehe Befehle in Claude Code für alle integrierten Befehle und Claude mit Skills erweitern für den vollständigen Leitfaden zu beiden Artefaktformen.

Verfügbare Befehle entdecken

Sie können Befehle versenden, die ohne ein interaktives Terminal durch das SDK funktionieren. Die system/init-Nachricht listet die in Ihrer Sitzung verfügbaren in ihrem slash_commands-Feld auf. Befehle, die ein interaktives Terminal benötigen, wie /theme und /terminal-setup, erscheinen nicht in der Liste. Greifen Sie auf das Feld zu, wenn Ihre Sitzung startet:
Die gedruckte Liste mischt integrierte Befehle, gebündelte Skills, Ihre vom Benutzer aufzurufenden Skills und .claude/commands/-Dateien:
Eine Skill mit user-invocable: false in ihrer Frontmatter erscheint nicht in dieser Liste oder im skills-Array von Bestätigen Sie, dass Skills geladen sind. Sitzungen, die MCP-Server konfigurieren, können auch MCP-Eingabeaufforderungen als Befehle verfügbar machen.

Befehle nach Name versenden

Senden Sie einen Befehl, indem Sie ihn in Ihre Eingabeaufforderungszeichenfolge einbeziehen, auf die gleiche Weise wie Sie normalen Text senden. Das Versenden hängt nicht von der skills-Option ab. Das Senden von /<name> führt eine vom Benutzer aufzurufende Skill aus, auch wenn Ihre skills-Liste sie auslässt. Befehle, die auf Gesprächsverlauf wirken, wie /compact, benötigen vorherige Nachrichten, um damit zu arbeiten.
Ein Befehl kann das maxTurns / max_turns-Limit wie jede andere Eingabeaufforderung treffen und die Abfrage mit einem Fehlerergebnis statt success beenden. Für den Fehlerergebnis-Vertrag siehe Behandeln Sie das Ergebnis. Wenn Ihr Befehl das Limit treffen könnte, wickeln Sie die Schleife in einen try/catch in TypeScript oder try/except in Python ein, wie in Einzelne Nachrichteneingabe gezeigt, oder setzen Sie maxTurns hoch genug, damit die Arbeit abgeschlossen wird.

Verlauf mit /compact komprimieren

Der /compact-Befehl reduziert die Größe Ihres Gesprächsverlaufs, indem er ältere Nachrichten zusammenfasst und dabei wichtigen Kontext bewahrt. Die Komprimierung benötigt ein bestehendes Gespräch mit genug vorherigen Nachrichten zum Zusammenfassen. Dieses Beispiel hat zuerst ein Gespräch, dann komprimiert es und liest die compact_boundary-Systemnachricht, die das Ergebnis meldet:
Eine compact_boundary-Nachricht kommt nur an, wenn die Komprimierung ausgeführt wurde. Wenn es nichts zu zusammenfassen gibt, meldet /compact stattdessen den Grund, ohne einen Fehler auszulösen. Die Ausführung endet immer noch mit einem success-Ergebnis und ohne compact_boundary-Nachricht, und der Ergebnistext trägt den Grund, zum Beispiel Not enough messages to compact. nach einem einzelnen kurzen Austausch. Ein frischer One-Shot-query()-Aufruf startet mit leerem Kontext, daher verwenden Sie dieses Muster in einer Sitzung mit vorherigen Durchläufen, zum Beispiel im Streaming-Eingabemodus oder beim Fortsetzen einer Sitzung.

Kontext mit /clear zurücksetzen

Der /clear-Befehl setzt das Gespräch auf einen leeren Kontext zurück, sodass nachfolgende Eingabeaufforderungen ohne vorherigen Gesprächsverlauf starten. Das vorherige Gespräch bleibt auf der Festplatte. Sie können zu diesem Gespräch zurückkehren, indem Sie seine Sitzungs-ID an die resume-Option übergeben. /clear ist nützlich im Streaming-Eingabemodus, wo Sie mehrere Eingabeaufforderungen über eine einzelne Verbindung senden. Für One-Shot-query()-Aufrufe startet jeder Aufruf bereits mit leerem Kontext, daher hat das Senden von /clear keine praktische Auswirkung. Starten Sie stattdessen eine neue query().

Skills erstellen

Erstellen Sie jeden Skill als Verzeichnis mit einer SKILL.md-Datei mit YAML-Frontmatter und Markdown-Inhalt. Das description-Feld bestimmt, wann Claude Ihren Skill aufruft. Beispiel-Verzeichnisstruktur:

Wählen Sie eine Erkennungsebene

Speichern Sie Skills auf einer der beiden häufigsten Erkennungsebenen:
  • Projekt-Skills: .claude/skills/, nur im aktuellen Projekt verfügbar
  • Persönliche Skills: ~/.claude/skills/, über alle Ihre Projekte hinweg verfügbar
Wenn Sie vorhandene benutzerdefinierte Befehlsdateien in .claude/commands/ haben, funktionieren sie weiterhin. Eine Befehlsdatei unter .claude/commands/deploy.md erstellt /deploy und funktioniert auf die gleiche Weise wie ein Skill unter .claude/skills/deploy/SKILL.md. Wenn eine Befehlsdatei und ein Skill einen Namen teilen, siehe Lösen Sie Skills auf, die einen Namen teilen für welcher ausgeführt wird. Das SDK lädt .claude/commands/ und ~/.claude/commands/-Dateien aus den gleichen zwei Bereichen wie Skills. Siehe Claude mit Skills erweitern für den vollständigen Leitfaden zu beiden Artefaktformen.

Erstellen und versenden Sie Ihren ersten Skill

Um den vollständigen Ablauf zu sehen, erstellen Sie .claude/skills/security-check/SKILL.md:
Sobald die Datei vorhanden ist, ist der Skill über das SDK verfügbar. Claude ruft ihn auf, wenn eine Anfrage seiner Beschreibung entspricht, und Sie können ihn direkt versenden:
Ein erfolgreicher Lauf endet mit einem success-Ergebnis, dessen Text die Scan-Ergebnisse trägt. Gegen eine kleine Express-App mit eingestreuten Problemen beginnt der Ergebnis-Text:
Der Name des Skills erscheint auch im slash_commands-Array der Init-Meldung.
Claude Code enthält gebündelte code-review- und verify-Skills. Wenn Sie eine .claude/commands/-Datei nach einem von ihnen benennen, z. B. .claude/commands/code-review.md, schattet die Datei den gebündelten Skill und slash_commands listet den Namen einmal auf.

Tools für Skills vorab genehmigen

Für Projekt- und persönliche Skills wendet Claude Code das allowed-tools-Frontmatter-Feld in SDK-Sitzungen an. Sie können Tools für diese Skills auch über die allowedTools-Option (allowed_tools in Python) in Ihrer Abfragekonfiguration vorab genehmigen. Skills synchronisiert von claude.ai folgen ihren eigenen Frontmatter-Regeln.
Skills laufen mit den Tools der Sitzung. Das folgende Beispiel genehmigt Read, Grep und Glob mit allowedTools (allowed_tools in Python) vorab, sodass Claude Dateien inspizieren kann, während der security-check-Skill ausgeführt wird, ohne auf Genehmigung zu warten:
Im Stream erscheint der Skill-Aufruf als Skill-Tool-Verwendung, gefolgt von Read-Aufrufen auf den Projektdateien. Der Lauf endet mit einem success-Ergebnis, dessen Text die Ergebnisse trägt. Die Liste genehmigt die benannten Tools vorab, anstatt die anderen einzuschränken. Für den vollständigen Berechtigungsfluss, einschließlich Berechtigungsmodi und des canUseTool-Callbacks, siehe Berechtigungen.

Fehlerbehebung

Skills nicht gefunden

Überprüfen Sie die settingSources-Konfiguration: Das SDK erkennt Skills durch die user- und project-Einstellungsquellen. Wenn Sie settingSources/setting_sources explizit festlegen und diese Quellen auslassen, lädt das SDK Skills nicht:
Welche Skill-Verzeichnisse jede Quelle lädt, siehe die Dateisystem-Quellen-Tabelle. Weitere Details zu settingSources/setting_sources finden Sie in der TypeScript SDK-Referenz oder Python SDK-Referenz. Überprüfen Sie das Arbeitsverzeichnis: Das SDK lädt Skills aus .claude/skills/ in der cwd-Option und in jedem übergeordneten Verzeichnis bis zur Repository-Root. Stellen Sie sicher, dass cwd auf ein Verzeichnis verweist, das .claude/skills/ enthält oder darunter liegt, innerhalb desselben Repositorys:
Siehe Skills mit dem Agent SDK verwenden für das vollständige Muster. Überprüfen Sie den Dateisystem-Speicherort:

Skill wird nicht verwendet

Überprüfen Sie die skills-Option: Wenn Sie eine skills-Liste übergeben haben, bestätigen Sie, dass der Name des Skills enthalten ist. Wenn Claude versucht, einen nicht aufgelisteten Skill aufzurufen, gibt das Skill-Tool Skill <name> is not in this session's skills allowlist zurück. Fügen Sie den Namen zu Ihrer Liste hinzu, oder versenden Sie den Skill direkt, indem Sie /<name> in einer Eingabeaufforderung senden, was ohne Auflistung funktioniert. Überprüfen Sie die Beschreibung: Stellen Sie sicher, dass sie spezifisch ist und relevante Schlüsselwörter enthält. Siehe Agent Skills Best Practices für Anleitung zum Schreiben effektiver Beschreibungen.

Fehler bei ungültigem Skill-Namen

Wenn ein Name in Ihrer skills-Liste nicht als exakter Skill-Name funktionieren kann, lehnt query() die Liste ab, bevor der Claude Code-Prozess gestartet wird. Namen, die die Ablehnung auslösen, umfassen:
  • Ein leerer Name
  • Ein Name mit Klammern, Kommas oder Steuerzeichen
  • Ein Name mit Leerzeichen aufgefüllt
  • Eine Platzhalterform wie ein bloßes * oder ein :*-Suffix
Jedes SDK zeigt die Ablehnung unterschiedlich an:
Das TypeScript SDK wirft einen Error, der die Regel angibt, die der Eintrag brach. Zum Beispiel wirft skills: ["docs:*"]:
Ein leerer Name meldet Skill names must be non-empty strings.Vor TypeScript Agent SDK 0.3.221 führte das SDK diese Überprüfung nicht durch.

Zusätzliche Fehlerbehebung

Für allgemeine Skills-Fehlerbehebung, wie YAML-Syntax-Fehler und Debugging, siehe den Claude Code Skills-Fehlerbehebungsabschnitt.

Nächste Schritte

Der Claude Code Skills-Leitfaden behandelt das Authoring ausführlich. Seine Anleitung gilt für SDK-Sitzungen. Beginnen Sie mit diesen Abschnitten: