Agent Skills im SDK
Erweitern Sie Claude mit spezialisierten Fähigkeiten mithilfe von Agent Skills im Claude Agent 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 Dateisystem-Speicherorten geladen, die von
settingSources(TypeScript) odersetting_sources(Python) gesteuert werden - 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 basierend auf dem Kontext, wann sie verwendet werden
- 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.
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())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
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"])
const options = { 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, wennsetting_sources"project"enthält - Benutzer-Skills (
~/.claude/skills/): Persönliche Skills über alle Projekte hinweg - geladen, wennsetting_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:
- Agent Skills in Claude Code: Vollständige Anleitung mit Beispielen
- Agent Skills Best Practices: Authoring-Richtlinien und Namenskonventionen
Tool-Einschränkungen
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:
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)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(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)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(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)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(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",
)
// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["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",
)
// 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 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
- Agent Skills in Claude Code: Vollständiger Skills-Leitfaden mit Erstellung, Beispielen und Fehlerbehebung
- Agent Skills Overview: Konzeptionelle Übersicht, Vorteile und Architektur
- Agent Skills Best Practices: Authoring-Richtlinien für effektive Skills
- Agent Skills Cookbook: Beispiel-Skills und Vorlagen
SDK-Ressourcen
- Subagents im SDK: Ähnliche dateisystem-basierte Agenten mit programmatischen Optionen
- Slash Commands im SDK: Benutzer-aufgerufene Befehle
- SDK-Übersicht: Allgemeine SDK-Konzepte
- TypeScript SDK-Referenz: Vollständige API-Dokumentation
- Python SDK-Referenz: Vollständige API-Dokumentation