Zum Hauptinhalt springen

​
Ü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:
  1. Als Dateisystem-Artefakte definiert: Erstellt als SKILL.md-Dateien in spezifischen Verzeichnissen (.claude/skills/)
  2. Aus dem Dateisystem geladen: Skills werden aus Dateisystem-Speicherorten geladen, die von settingSources (TypeScript) oder setting_sources (Python) gesteuert werden
  3. 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
  4. Modell-aufgerufen: Claude wählt autonom basierend auf dem Kontext, wann sie verwendet werden
  5. Gefiltert über die skills-Option: Erkannte Skills sind standardmäßig aktiviert. Übergeben Sie eine Liste von Skill-Namen, "all" oder [], um zu steuern, welche in der Sitzung verfügbar sind
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.
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. Wenn Sie settingSources explizit festlegen, schließen Sie 'user' oder 'project' ein, um die Skill-Erkennung beizubehalten, oder verwenden Sie die plugins-Option, um Skills aus einem bestimmten Pfad zu laden.

​
Verwendung von Skills mit dem SDK

Legen Sie die skills-Option auf query() fest, um zu steuern, welche Skills der Sitzung zur Verfügung stehen. Wenn weggelassen, sind erkannte Skills aktiviert und das Skill-Tool ist verfügbar, was dem CLI-Verhalten entspricht. Übergeben Sie "all", um jeden erkannten Skill zu aktivieren, eine Liste von Skill-Namen, um nur diese zu aktivieren, oder [], um alle zu deaktivieren. Wenn Sie skills festlegen, fügt das SDK das Skill-Tool automatisch zu allowedTools hinzu. Wenn Sie auch eine explizite tools-Liste übergeben, nehmen Sie "Skill" in diese Liste auf, 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. 
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
        skills="all",  # Enable 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())
Um nur bestimmte Skills zu aktivieren, übergeben Sie ihre Namen. Namen entsprechen dem name-Feld in SKILL.md oder dem Skill-Verzeichnisnamen. Verwenden Sie plugin:skill für von Plugins bereitgestellte Skills. 
options = ClaudeAgentOptions(skills=["pdf", "docx"])
Die skills-Option ist ein Kontextfilter, kein Sandbox. Nicht aufgelistete Skills sind für das Modell verborgen und werden vom Skill-Tool abgelehnt, aber ihre Dateien bleiben auf der Festplatte und sind über Read und Bash erreichbar.

​
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 description-Feld bestimmt, wann Claude Ihren Skill aufruft. Beispiel-Verzeichnisstruktur: 
.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:

​
Tool-Einschränkungen

Das allowed-tools-Frontmatter-Feld in SKILL.md wird nur unterstützt, wenn Sie Claude Code CLI direkt verwenden. Es gilt nicht bei Verwendung von Skills über das SDK.Bei Verwendung des SDK steuern Sie den Tool-Zugriff über die Hauptoption allowedTools in Ihrer Query-Konfiguration.
Um den Tool-Zugriff für Skills in SDK-Anwendungen zu steuern, verwenden Sie allowedTools, um bestimmte Tools vorab zu genehmigen. Ohne einen canUseTool-Callback wird alles, was nicht in der Liste enthalten ist, verweigert:
Import-Anweisungen aus dem ersten Beispiel werden in den folgenden Code-Snippets angenommen.
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
)

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

​
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
    skills="all",
)

async for message in query(prompt="What Skills are available?", options=options):
    print(message)
Claude listet die verfügbaren Skills basierend auf Ihrem aktuellen Arbeitsverzeichnis und installierten Plugins auf.

​
Testen von Skills

Testen Sie Skills, indem Sie Fragen stellen, die ihren Beschreibungen entsprechen: 
options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["Read", "Bash"],
)

async for message in query(prompt="Extract text from invoice.pdf", options=options):
    print(message)
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 durch die user- und project-Einstellungsquellen erkannt. Wenn Sie settingSources/setting_sources explizit festlegen und diese Quellen weglassen, werden Skills nicht geladen: 
# 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",
)
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",
)
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 die skills-Option: Wenn Sie eine skills-Liste übergeben haben, bestätigen Sie, dass der Name des Skills enthalten ist. Das Übergeben von [] deaktiviert alle Skills. Ü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

​
SDK-Ressourcen