Agent Skills erweitern
Steuern Sie, welche Skills Claude in Claude Agent SDK-Sitzungen aufrufen kann, versenden Sie Befehle nach Name und erstellen Sie Skills, die Ihre Sitzungen entdecken
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) 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
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 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:
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
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:
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(), # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Load skills from filesystem
skills="all", # Let Claude invoke every discovered skill
allowed_tools=["Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: process.cwd(), // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all", // Let Claude invoke every discovered skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
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 spiegelt wider, was die Sitzung erkannt hat, und 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 SDK-Befehlsdokumentation. 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, z. B.
/compact - Gebündelte Skills: Eingabeaufforderungs-Artefakte, die in Claude Code enthalten sind, z. B.
/code-review - Ihre Skills: Eingabeaufforderungs-Artefakte, die Sie erstellen, jeweils ein Verzeichnis mit einer
SKILL.md-Datei. Der Name eines benutzer-aufgerufenen Skills wird automatisch zur Oberfläche hinzugefügt, daher funktioniert das Versenden Ihres eigenen/security-checkund das Ausführen eines integrierten auf die gleiche Weise - 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 Sie und Claude jeden Skill aufrufen. Sie können jeden Pfad durch das Frontmatter des Skills einschränken](/de/skills#control-who-invokes-a-skill). Für eine Definition der beiden Begriffe siehe die Glossar-Einträge Befehl und Skill. Siehe Befehle in Claude Code für jeden integrierten 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 funktionieren, über das SDK. Die system/init-Meldung 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 beginnt:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
print("Available commands:", message.data["slash_commands"])
asyncio.run(main())
Die gedruckte Liste mischt integrierte Befehle, gebündelte Skills, Ihre benutzer-aufgerufenen Skills und .claude/commands/-Dateien:
Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
Ihre benutzer-aufgerufenen Skills erscheinen sowohl in dieser Liste als auch im skills-Array aus Bestätigen Sie, dass Skills geladen wurden. Die slash_commands-Liste fügt die restlichen in Ihrer Sitzung verfügbaren Befehle hinzu. Ein Skill mit user-invocable: false in seinem Frontmatter erscheint in keinem. 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 Eingabeaufforderungs-Zeichenkette einschließen, 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 einen benutzer-aufgerufenen Skill aus, auch wenn Ihre skills-Liste ihn auslässt. Befehle, die auf Konversationsverlauf wirken, wie /compact, benötigen vorherige Meldungen, um damit zu arbeiten.
Verlauf mit `/compact` komprimieren
Der /compact-Befehl reduziert die Größe Ihres Konversationsverlaufs, indem er ältere Meldungen zusammenfasst und dabei wichtigen Kontext bewahrt. Die Komprimierung benötigt eine bestehende Konversation mit genug vorherigen Meldungen zum Zusammenfassen. Dieses Beispiel hat zuerst eine Konversation, dann komprimiert sie und liest die compact_boundary-Systemmeldung, die das Ergebnis meldet:
import { query } from "@anthropic-ai/claude-agent-sdk";
// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}
// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
async def main():
# Compaction needs existing history, so have a conversation first
try:
async for message in query(
prompt="Explain what this project does",
options=ClaudeAgentOptions(max_turns=2),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as error:
# A single-shot query() raises after yielding an error result,
# so the follow-up query below still runs.
print(f"Session ended with an error: {error}")
# Compact the same conversation
async for message in query(
prompt="/compact",
options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
):
if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
print("Compaction completed")
print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
print("Trigger:", message.data["compact_metadata"]["trigger"])
# Example output:
# Compaction completed
# Pre-compaction tokens: 1842
# Trigger: manual
asyncio.run(main())
Kontext mit `/clear` zurücksetzen
Der /clear-Befehl setzt die Konversation auf einen leeren Kontext zurück, sodass nachfolgende Eingabeaufforderungen keinen vorherigen Konversationsverlauf haben. Die vorherige Konversation bleibt auf der Festplatte. Sie können zu dieser Konversation zurückkehren, indem Sie ihre 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 beginnt jeder Aufruf bereits mit leerem Kontext, daher hat das Senden von /clear keine praktische Auswirkung. Starten Sie stattdessen einen neuen 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:
.claude/skills/security-check/
└── SKILL.md
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:
---
name: security-check
description: Run a security vulnerability scan
---
Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations
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:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
async for message in query(
prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
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:
**Security scan of `app.js` — 4 findings (most severe first):**
1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...
Der Name des Skills erscheint auch im slash_commands-Array der Init-Meldung.
Tools für Skills vorab genehmigen
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:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Check this project for security issues",
options: {
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
console.log(message);
}
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:
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")
# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)
// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};
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:
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Siehe Skills mit dem Agent SDK verwenden für das vollständige Muster.
Überprüfen Sie den Dateisystem-Speicherort:
# Check project skills
ls .claude/skills/*/SKILL.md
# Check personal skills
ls ~/.claude/skills/*/SKILL.md
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:*"]:
Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.
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.
Das Python SDK wirft ValueError, das die Regel angibt, die der Eintrag brach. Zum Beispiel wirft skills=["docs:*"]:
ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.
Ein leerer Name meldet Skill names must be non-empty strings.
Vor Python Agent SDK 0.2.129 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