Agent Skills im SDK

Übersicht

Agent Skills erweitern Claude um spezialisierte Fähigkeiten, die Claude autonom aufruft, wenn relevant. Skills werden als SKILL.md-Dateien verpackt, die Anweisungen, Beschreibungen und optionale unterstützende Ressourcen enthalten.

Umfassende Informationen zu Skills, einschließlich Vorteile, Architektur und Authoring-Richtlinien, finden Sie in der Agent Skills-Übersicht.

Wie Skills mit dem SDK funktionieren

Bei Verwendung des Claude Agent SDK sind Skills:

Als Dateisystem-Artefakte definiert: Erstellt als SKILL.md-Dateien in spezifischen Verzeichnissen (.claude/skills/)
Aus dem Dateisystem geladen: Skills werden aus konfigurierten Dateisystem-Speicherorten geladen. Sie müssen settingSources (TypeScript) oder setting_sources (Python) angeben, um Skills aus dem Dateisystem zu laden
Automatisch erkannt: Sobald Dateisystem-Einstellungen geladen sind, werden Skill-Metadaten beim Start aus Benutzer- und Projektverzeichnissen erkannt; vollständiger Inhalt wird geladen, wenn ausgelöst
Modell-aufgerufen: Claude wählt autonom aus, wann sie basierend auf dem Kontext verwendet werden sollen
Aktiviert über allowed_tools: Fügen Sie "Skill" zu Ihren allowed_tools hinzu, um Skills zu aktivieren

Im Gegensatz zu Subagenten (die programmatisch definiert werden können) müssen Skills als Dateisystem-Artefakte erstellt werden. Das SDK bietet keine programmatische API zum Registrieren von Skills.

Standardverhalten: Standardmäßig lädt das SDK keine Dateisystem-Einstellungen. Um Skills zu verwenden, müssen Sie explizit settingSources: ['user', 'project'] (TypeScript) oder setting_sources=["user", "project"] (Python) in Ihren Optionen konfigurieren.

Verwendung von Skills mit dem SDK

Um Skills mit dem SDK zu verwenden, müssen Sie:

"Skill" in Ihre allowed_tools-Konfiguration einbeziehen
settingSources/setting_sources konfigurieren, um Skills aus dem Dateisystem zu laden

Nach der Konfiguration erkennt Claude automatisch Skills aus den angegebenen Verzeichnissen und ruft sie auf, wenn sie für die Anfrage des Benutzers relevant sind.

Skill-Speicherorte

Skills werden aus Dateisystem-Verzeichnissen basierend auf Ihrer settingSources/setting_sources-Konfiguration geladen:

Projekt-Skills (.claude/skills/): Mit Ihrem Team über git geteilt - geladen, wenn setting_sources "project" enthält
Benutzer-Skills (~/.claude/skills/): Persönliche Skills über alle Projekte hinweg - geladen, wenn setting_sources "user" enthält
Plugin-Skills: Mit installierten Claude Code-Plugins gebündelt

Erstellen von Skills

Skills werden als Verzeichnisse definiert, die eine SKILL.md-Datei mit YAML-Frontmatter und Markdown-Inhalt enthalten. Das Feld description bestimmt, wann Claude Ihren Skill aufruft.

Beispielverzeichnisstruktur:

.claude/skills/processing-pdfs/
└── SKILL.md

Vollständige Anleitung zum Erstellen von Skills, einschließlich SKILL.md-Struktur, mehrdatei-Skills und Beispiele, finden Sie unter:

Agent Skills in Claude Code: Vollständige Anleitung mit Beispielen
Agent Skills Best Practices: Authoring-Richtlinien und Namenskonventionen

Tool-Einschränkungen

Das Frontmatter-Feld allowed-tools in SKILL.md wird nur unterstützt, wenn Sie Claude Code CLI direkt verwenden. Es gilt nicht, wenn Sie Skills über das SDK verwenden.

Bei Verwendung des SDK steuern Sie den Tool-Zugriff über die Hauptoption allowedTools in Ihrer Query-Konfiguration.

Um Tools für Skills in SDK-Anwendungen einzuschränken, verwenden Sie die Option allowedTools:

Import-Anweisungen aus dem ersten Beispiel werden in den folgenden Code-Snippets angenommen.

Verfügbare Skills entdecken

Um zu sehen, welche Skills in Ihrer SDK-Anwendung verfügbar sind, fragen Sie einfach Claude:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude wird die verfügbaren Skills basierend auf Ihrem aktuellen Arbeitsverzeichnis und installierten Plugins auflisten.

Testen von Skills

Testen Sie Skills, indem Sie Fragen stellen, die ihren Beschreibungen entsprechen:

Claude ruft automatisch den relevanten Skill auf, wenn die Beschreibung Ihrer Anfrage entspricht.

Fehlerbehebung

Skills nicht gefunden

Überprüfen Sie die settingSources-Konfiguration: Skills werden nur geladen, wenn Sie explizit settingSources/setting_sources konfigurieren. Dies ist das häufigste Problem:

# Falsch - Skills werden nicht geladen
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Richtig - Skills werden geladen
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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 relativ zur Option cwd. Stellen Sie sicher, dass sie auf ein Verzeichnis verweist, das .claude/skills/ enthält:

# Stellen Sie sicher, dass Ihr cwd auf das Verzeichnis verweist, das .claude/skills/ enthält
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Siehe den Abschnitt "Verwendung von Skills mit dem SDK" oben 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, dass das Skill-Tool aktiviert ist: Bestätigen Sie, dass "Skill" in Ihren allowedTools enthalten ist.

Ü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.

Zusätzliche Fehlerbehebung

Für allgemeine Skills-Fehlerbehebung (YAML-Syntax, Debugging usw.) siehe den Claude Code Skills-Fehlerbehebungsabschnitt.

Zugehörige Dokumentation

Skills-Leitfäden

Agent Skills in Claude Code: Vollständiger Skills-Leitfaden mit Erstellung, Beispielen und Fehlerbehebung
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

SDK-Ressourcen

Subagenten im SDK: Ähnliche dateisystem-basierte Agenten mit programmatischen Optionen
Slash-Befehle im SDK: Vom Benutzer aufgerufene Befehle
SDK-Übersicht: Allgemeine SDK-Konzepte
TypeScript SDK-Referenz: Vollständige API-Dokumentation
Python SDK-Referenz: Vollständige API-Dokumentation

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # Project with .claude/skills/
        setting_sources=["user", "project"],  # Load Skills from filesystem
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

    async for message in query(
        prompt="Help me process this PDF document",
        options=options
    ):
        print(message)

asyncio.run(main())

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(message)

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)