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) odersetting_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
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 dieskills-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 Sieskills 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 Subtypinit 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 derskills-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-checkund 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
Verfügbare Befehle entdecken
Sie können Befehle versenden, die ohne ein interaktives Terminal durch das SDK funktionieren. Diesystem/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:
.claude/commands/-Dateien:
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 derskills-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 einerSKILL.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
.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:
success-Ergebnis, dessen Text die Scan-Ergebnisse trägt. Gegen eine kleine Express-App mit eingestreuten Problemen beginnt der Ergebnis-Text:
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.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:
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 dieuser- und project-Einstellungsquellen. Wenn Sie settingSources/setting_sources explizit festlegen und diese Quellen auslassen, lädt das SDK Skills nicht:
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:
Skill wird nicht verwendet
Überprüfen Sie dieskills-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 Ihrerskills-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
- TypeScript
- Python
Das TypeScript SDK wirft einen Ein leerer Name meldet
Error, der die Regel angibt, die der Eintrag brach. Zum Beispiel wirft skills: ["docs:*"]: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:- Frontmatter-Referenz: jedes unterstützte Feld
- Übergeben Sie Argumente an Skills:
$ARGUMENTS,$0,$1und Skill-Stapelung. Die vollständige Substitutions-Tabelle fügt benannte Argumente und die${CLAUDE_*}-Variablen hinzu - Injizieren Sie dynamischen Kontext:
!`command`-Zeilen, die ausgeführt werden, bevor Claude den Skill-Inhalt sieht - Wählen Sie, wo Skills geladen werden: jeder Skill-Speicherort, Plugin-Namensraum und welcher Skill ausgeführt wird, wenn zwei einen Namen teilen
Zugehörige Ressourcen
- Befehle in Claude Code: die vollständige Befehlsoberfläche, einschließlich jedes integrierten
- Agent Skills-Übersicht: konzeptionelle Übersicht, Vorteile und Architektur
- Agent Skills Best Practices: Authoring-Richtlinien für effektive Skills
- Agent Skills Cookbook: Beispiel-Skills und Vorlagen
- Subagenten im SDK: ähnliche dateisystem-basierte Agenten mit programmatischen Optionen
- SDK-Übersicht: allgemeine SDK-Konzepte
- TypeScript SDK-Referenz: vollständige API-Dokumentation
- Python SDK-Referenz: vollständige API-Dokumentation