Agent Skills erweitern Claudes Fähigkeiten durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Diese Anleitung zeigt Ihnen, wie Sie sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwenden.
Für die vollständige API-Referenz einschließlich Request/Response-Schemas und aller Parameter siehe:

Übersicht

Für einen tieferen Einblick in die Architektur und reale Anwendungen von Agent Skills lesen Sie unseren Engineering-Blog: Equipping agents for the real world with Agent Skills.
Skills integrieren sich über das Code-Ausführungs-Tool mit der Messages API. Ob Sie vorgefertigte Skills verwenden, die von Anthropic verwaltet werden, oder benutzerdefinierte Skills, die Sie hochgeladen haben, ist die Integrationsform identisch – beide erfordern Code-Ausführung und verwenden die gleiche container-Struktur.

Skills verwenden

Skills integrieren sich unabhängig von der Quelle identisch in die Messages API. Sie geben Skills im container-Parameter mit einer skill_id, einem type und einer optionalen version an, und sie werden in der Code-Ausführungsumgebung ausgeführt. Sie können Skills aus zwei Quellen verwenden:
AspektAnthropic SkillsBenutzerdefinierte Skills
Type-Wertanthropiccustom
Skill-IDsKurznamen: pptx, xlsx, docx, pdfGeneriert: skill_01AbCdEfGhIjKlMnOpQrStUv
VersionsformatDatumsbasiert: 20251013 oder latestEpoch-Zeitstempel: 1759178010641129 oder latest
VerwaltungVorgefertigt und von Anthropic gepflegtHochladen und Verwalten über Skills API
VerfügbarkeitFür alle Benutzer verfügbarPrivat für Ihren Workspace
Beide Skill-Quellen werden vom List Skills-Endpunkt zurückgegeben (verwenden Sie den source-Parameter zum Filtern). Die Integrationsform und die Ausführungsumgebung sind identisch – der einzige Unterschied ist, woher die Skills stammen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigen Sie:
  1. Anthropic API-Schlüssel aus der Console
  2. Beta-Header:
    • code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
    • skills-2025-10-02 - Aktiviert Skills API
    • files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien zum/vom Container
  3. Code-Ausführungs-Tool in Ihren Anfragen aktiviert

Skills in Messages verwenden

Container-Parameter

Skills werden mit dem container-Parameter in der Messages API angegeben. Sie können bis zu 8 Skills pro Anfrage einschließen. Die Struktur ist für Anthropic und benutzerdefinierte Skills identisch – geben Sie den erforderlichen type und die skill_id an und schließen Sie optional version ein, um an eine bestimmte Version gebunden zu sein:
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create a presentation about renewable energy"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Heruntergeladene generierte Dateien

Wenn Skills Dokumente erstellen (Excel, PowerPoint, PDF, Word), geben sie file_id-Attribute in der Antwort zurück. Sie müssen die Files API verwenden, um diese Dateien herunterzuladen. So funktioniert es:
  1. Skills erstellen Dateien während der Code-Ausführung
  2. Die Antwort enthält file_id für jede erstellte Datei
  3. Verwenden Sie die Files API, um den tatsächlichen Dateiinhalt herunterzuladen
  4. Speichern Sie lokal oder verarbeiten Sie nach Bedarf
Beispiel: Erstellen und Herunterladen einer Excel-Datei
import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create an Excel file with a simple budget spreadsheet"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Step 2: Extract file IDs from the response
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == 'bash_code_execution_tool_result':
            content_item = item.content
            if content_item.type == 'bash_code_execution_result':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")
Zusätzliche Files API-Operationen:
# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
Für vollständige Details zur Files API siehe die Files API-Dokumentation.

Mehrteilige Konversationen

Verwenden Sie denselben Container über mehrere Nachrichten hinweg, indem Sie die Container-ID angeben:
# First request creates container
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Continue conversation with same container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Langfristige Operationen

Skills können Operationen durchführen, die mehrere Durchläufe erfordern. Behandeln Sie pause_turn-Stoppgründe:
messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Handle pause_turn for long operations
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )
Die Antwort kann einen pause_turn-Stoppgrund enthalten, der anzeigt, dass die API eine langfristige Skill-Operation unterbrochen hat. Sie können die Antwort in einer nachfolgenden Anfrage unverändert bereitstellen, um Claude seinen Durchlauf fortsetzen zu lassen, oder Sie können den Inhalt ändern, wenn Sie das Gespräch unterbrechen und zusätzliche Anleitung geben möchten.

Mehrere Skills verwenden

Kombinieren Sie mehrere Skills in einer einzigen Anfrage, um komplexe Workflows zu bewältigen:
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",
                "version": "latest"
            },
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            },
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Analyze sales data and create a presentation"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Laden Sie Ihren benutzerdefinierten Skill hoch, um ihn in Ihrem Workspace verfügbar zu machen. Sie können entweder einen Verzeichnispfad oder einzelne Dateiobjekte hochladen.
import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")
Anforderungen:
  • Muss eine SKILL.md-Datei auf der obersten Ebene enthalten
  • Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
  • Die Gesamtgröße des Uploads muss unter 8 MB liegen
  • YAML-Frontmatter-Anforderungen:
    • name: Maximal 64 Zeichen, nur Kleinbuchstaben/Zahlen/Bindestriche, keine XML-Tags, keine reservierten Wörter (“anthropic”, “claude”)
    • description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags
Für vollständige Request/Response-Schemas siehe die Create Skill API-Referenz.

Skills auflisten

Rufen Sie alle Skills ab, die für Ihren Workspace verfügbar sind, einschließlich vorgefertigter Anthropic Skills und Ihrer benutzerdefinierten Skills. Verwenden Sie den source-Parameter zum Filtern nach Skill-Typ:
# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)
Siehe die List Skills API-Referenz für Paginierungs- und Filteroptionen.

Einen Skill abrufen

Rufen Sie Details zu einem bestimmten Skill ab:
skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Einen Skill löschen

Um einen Skill zu löschen, müssen Sie zuerst alle seine Versionen löschen:
# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
Der Versuch, einen Skill mit vorhandenen Versionen zu löschen, gibt einen 400-Fehler zurück.

Versionierung

Skills unterstützen Versionierung, um Updates sicher zu verwalten: Von Anthropic verwaltete Skills:
  • Versionen verwenden Datumsformat: 20251013
  • Neue Versionen werden als Updates veröffentlicht
  • Geben Sie genaue Versionen für Stabilität an
Benutzerdefinierte Skills:
  • Automatisch generierte Epoch-Zeitstempel: 1759178010641129
  • Verwenden Sie "latest", um immer die neueste Version zu erhalten
  • Erstellen Sie neue Versionen beim Aktualisieren von Skill-Dateien
# Create a new version
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Use specific version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Use latest version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest"
        }]
    },
    messages=[{"role": "user", "content": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)
Siehe die Create Skill Version API-Referenz für vollständige Details.

Wie Skills geladen werden

Wenn Sie Skills in einem Container angeben:
  1. Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) in der Systemaufforderung
  2. Datei-Laden: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert
  3. Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für Ihre Anfrage relevant sind
  4. Komposition: Mehrere Skills arbeiten zusammen für komplexe Workflows
Die progressive Offenlegungsarchitektur gewährleistet eine effiziente Kontextnutzung – Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation
  • Wenden Sie unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente an
  • Generieren Sie Kommunikationen nach Organisationsvorlagen
  • Stellen Sie sicher, dass Markenrichtlinien in allen Ausgaben konsistent sind
Projektmanagement
  • Strukturieren Sie Notizen mit unternehmensspezifischen Formaten (OKRs, Entscheidungsprotokolle)
  • Generieren Sie Aufgaben nach Team-Konventionen
  • Erstellen Sie standardisierte Besprechungsnotizen und Statusaktualisierungen
Geschäftsbetrieb
  • Erstellen Sie unternehmensstandard-Berichte, Vorschläge und Analysen
  • Führen Sie unternehmensspezifische analytische Verfahren durch
  • Generieren Sie Finanzmodelle nach Organisationsvorlagen

Persönliche Skills

Inhaltserstellung
  • Benutzerdefinierte Dokumentvorlagen
  • Spezialisierte Formatierung und Gestaltung
  • Domänenspezifische Inhaltsgenerierung
Datenanalyse
  • Benutzerdefinierte Datenverarbeitungs-Pipelines
  • Spezialisierte Visualisierungsvorlagen
  • Branchenspezifische analytische Methoden
Entwicklung & Automatisierung
  • Code-Generierungsvorlagen
  • Test-Frameworks
  • Bereitstellungs-Workflows

Beispiel: Finanzmodellierung

Kombinieren Sie Excel und benutzerdefinierte DCF-Analyse-Skills:
# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"]
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Build a DCF valuation model for a SaaS company with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Limits und Einschränkungen

Anfrage-Limits

  • Maximale Skills pro Anfrage: 8
  • Maximale Skill-Upload-Größe: 8 MB (alle Dateien zusammen)
  • YAML-Frontmatter-Anforderungen:
    • name: Maximal 64 Zeichen, nur Kleinbuchstaben/Zahlen/Bindestriche, keine XML-Tags, keine reservierten Wörter
    • description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Umgebungseinschränkungen

Skills werden im Code-Ausführungs-Container mit diesen Einschränkungen ausgeführt:
  • Kein Netzwerkzugriff - Können keine externen API-Aufrufe tätigen
  • Keine Laufzeit-Paketinstallation - Nur vorinstallierte Pakete verfügbar
  • Isolierte Umgebung - Jede Anfrage erhält einen neuen Container
Siehe die Code-Ausführungs-Tool-Dokumentation für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombinieren Sie Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen betreffen: Gute Anwendungsfälle:
  • Datenanalyse (Excel) + Präsentationserstellung (PowerPoint)
  • Berichtsgenerierung (Word) + Export zu PDF
  • Benutzerdefinierte Domänenlogik + Dokumentgenerierung
Vermeiden Sie:
  • Einschließen ungenutzter Skills (beeinträchtigt die Leistung)

Versionsverwaltungsstrategie

Für Produktion:
# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}
Für Entwicklung:
# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Prompt-Caching-Überlegungen

Beachten Sie bei Verwendung von Prompt-Caching, dass das Ändern der Skills-Liste in Ihrem Container den Cache bricht:
# First request creates cache
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"}  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)
Für beste Caching-Leistung halten Sie Ihre Skills-Liste über Anfragen hinweg konsistent.

Fehlerbehandlung

Behandeln Sie Skill-bezogene Fehler elegant:
try:
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Handle skill-specific errors
    else:
        raise

Nächste Schritte