Agent Skills mit der API verwenden

Erfahre, wie du Agent Skills verwendest, um die Fähigkeiten von Claude über die API zu erweitern.

Agent Skills erweitern die Fähigkeiten von Claude durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Dieser Leitfaden zeigt dir, wie du sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwendest.

Schnellzugriff

Erste Schritte mit Agent Skills in der API

Erfahre, wie du Agent Skills verwendest, um in weniger als 10 Minuten Dokumente mit der Claude API zu erstellen.

Best Practices für das Erstellen von Skills

Erfahre, wie du effektive Skills schreibst, die Claude entdecken und erfolgreich nutzen kann.

Überblick

Skills werden über das Code-Execution-Tool in die Messages API integriert. Unabhängig davon, ob du vorgefertigte, von Anthropic verwaltete Skills oder selbst hochgeladene benutzerdefinierte Skills verwendest, ist die Integrationsform identisch: Beide erfordern Code-Ausführung und verwenden dieselbe container-Struktur.

Skills verwenden

Skills werden in der Messages API unabhängig von ihrer Quelle identisch integriert. Du gibst Skills im container-Parameter mit einer skill_id, einem type und optional einer version an, und sie werden in der Code-Ausführungsumgebung ausgeführt.

Du kannst Skills aus zwei Quellen verwenden:

Aspekt	Anthropic-Skills	Benutzerdefinierte Skills
Type-Wert	`anthropic`	`custom`
Skill-IDs	Kurznamen: `pptx`, `xlsx`, `docx`, `pdf`	Generiert: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Versionsformat	Datumsbasiert: `20251013` oder `latest`	Epoch-Zeitstempel: `1759178010641129` oder `latest`
Verwaltung	Vorgefertigt und von Anthropic gepflegt	Hochladen und Verwalten über die Skills API
Verfügbarkeit	Für alle Nutzer verfügbar	Privat in deinem Workspace

Beide Skill-Quellen werden vom List-Skills-Endpunkt zurückgegeben (verwende den source-Parameter zum Filtern). Die Integrationsform und die Ausführungsumgebung sind identisch. Der einzige Unterschied besteht darin, woher die Skills stammen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigst du:

Claude API-Key aus der Claude Console
Beta-Header:
- code-execution-2025-08-25 – Aktiviert die Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 – Aktiviert die Skills API
- files-api-2025-04-14 – Nur erforderlich, wenn du die Files API verwendest, um Eingabedateien hochzuladen oder von einem Skill erzeugte Dateien herunterzuladen
Code-Execution-Tool in deinen Requests aktiviert

Skills erfordern das Code-Execution-Tool, verwende daher ein Modell aus dessen Modellkompatibilitätsliste.

Skills in Messages verwenden

Container-Parameter

Skills werden über den container-Parameter in der Messages API angegeben. Du kannst bis zu 8 Skills pro Request einbinden.

Die Struktur ist für Anthropic- und benutzerdefinierte Skills identisch. Gib die erforderlichen Felder type und skill_id an und füge optional version hinzu, um eine bestimmte Version festzulegen:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

Generierte Dateien herunterladen

Wenn Skills Dokumente erstellen (Excel, PowerPoint, PDF, Word), geben sie file_id-Attribute in der Response zurück. Du musst die Files API verwenden, um diese Dateien herunterzuladen.

So funktioniert es:

Skills erstellen Dateien während der Code-Ausführung.
Die Response enthält eine file_id für jede erstellte Datei, innerhalb der Tool-Result-Blöcke der Code-Ausführung (siehe Response-Format).
Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen.
Speichere lokal oder verarbeite nach Bedarf.

Um Eingabedateien bereitzustellen, mit denen Skills arbeiten sollen, lade sie mit der Files API hoch und referenziere sie in deinem Request mit einem Container-Upload-Block.

Beispiel: Erstellen und Herunterladen einer Excel-Datei

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)


# Schritt 2: Extrahiere Datei-IDs aus der Antwort
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":
                # jedes Content-Element ist ein bash_code_execution_output-Block mit einer file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Schritt 3: Lade die Datei über die Files API herunter
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Schritt 4: Speichere auf der Festplatte
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Zusätzliche Files-API-Operationen:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Rufe Datei-Metadaten ab
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Liste alle Dateien auf
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Lösche eine Datei
client.beta.files.delete(file_id=file_id)

Multi-Turn-Konversationen

Das container-Objekt der Response enthält die id des Containers und den expires_at-Zeitstempel (siehe Container-Wiederverwendung für Details zur Lebensdauer). Verwende denselben Container über mehrere Nachrichten hinweg wieder, indem du die Container-ID angibst:

client = anthropic.Anthropic()

# Erste Anfrage erstellt den Container
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Setze die Konversation mit demselben Container fort
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Übernimm den Text des Assistenten; container.id überträgt den Ausführungszustand
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

Lang laufende Operationen

Skills können Operationen ausführen, die mehrere Turns erfordern. Behandle pause_turn-Stop-Reasons:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

# Behandle pause_turn für lange Operationen
for _ 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-opus-5",
        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"}],
    )

Mehrere Skills verwenden

Kombiniere mehrere Skills in einem einzigen Request, um komplexe Workflows zu bewältigen:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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

Ein Skill-Bundle ist ein Verzeichnis, das auf oberster Ebene eine SKILL.md-Datei mit name- und description-YAML-Frontmatter enthält, sowie alle unterstützenden Skripte oder Ressourcen. Siehe Erste Schritte mit Agent Skills in der API, um eines zu erstellen, und die Liste Anforderungen nach den Beispielen für die vollständigen Einschränkungen.

Lade deinen benutzerdefinierten Skill hoch, um ihn in deinem Workspace verfügbar zu machen. Du kannst ein Zip-Archiv oder einzelne Dateiobjekte hochladen. Das Python-SDK bietet außerdem einen files_from_dir-Helper, der einen Verzeichnispfad akzeptiert.

Dateien werden anhand des Dateinamens identifiziert, den du anhängst. Einzeldatei-Uploads müssen ein gemeinsames Verzeichnis auf oberster Ebene in ihren Pfaden beibehalten (das ;filename=-Suffix im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen). Ein Zip-Archiv muss das Skill-Verzeichnis als einzigen Eintrag auf oberster Ebene enthalten. Für den Skill aus dem Walkthrough erstellst du eines mit zip -r financial_skill.zip financial_skill/ und ersetzt damit den Platzhalter example_skill.zip in den Zip-Upload-Optionen.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Der Upload einzelner Dateien erfordert pfadqualifizierte Dateinamen, die die CLI
# derzeit nicht setzen kann. Lade stattdessen ein ZIP-Archiv hoch.

Anforderungen:

Muss eine SKILL.md-Datei auf oberster Ebene enthalten
Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
Der Name des Verzeichnisses auf oberster Ebene muss mit dem name im SKILL.md-Frontmatter übereinstimmen (Groß-/Kleinschreibung und Unterstriche werden ignoriert: Financial_Skill entspricht financial-skill)
display_title ist optional: Wenn weggelassen, wird er vom name in SKILL.md abgeleitet; ein expliziter Wert muss unter den benutzerdefinierten Skills in deinem Workspace eindeutig sein
Die Gesamtgröße des Uploads muss unter 30 MB liegen (unkomprimiert)
Anforderungen an das YAML-Frontmatter:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter („anthropic", „claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Vollständige Request-/Response-Schemas findest du in der Create Skill API-Referenz.

Skills auflisten

Rufe alle Skills ab, die in deinem Workspace verfügbar sind, einschließlich der vorgefertigten Anthropic-Skills und deiner benutzerdefinierten Skills. Verwende den source-Parameter, um nach Skill-Typ zu filtern:

# Liste alle Skills auf
ant beta:skills list

# Liste nur benutzerdefinierte Skills auf
ant beta:skills list --source custom

Siehe die List Skills API-Referenz für Paginierungs- und Filteroptionen.

Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Einen Skill löschen

Um einen Skill zu löschen, musst du zuerst alle seine Versionen löschen:

# Schritt 1: Liste die Versionen auf und lösche dann jede einzelne
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Wiederhole dies für jede Versions-ID, die die Liste zurückgegeben hat
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Schritt 2: Lösche den Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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:

Anthropic-Skills:

Versionen verwenden das Datumsformat: 20251013
Neue Versionen werden veröffentlicht, wenn Updates vorgenommen werden
Gib exakte Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwende "latest", um immer die neueste Version zu erhalten
Erstelle neue Versionen, wenn du Skill-Dateien aktualisierst

Eine neue Version ist ein vollständiger Snapshot, kein Delta: Lade jedes Mal den vollständigen Dateisatz des Skills hoch, unter demselben Verzeichnisnamen auf oberster Ebene, der bei der Erstellung verwendet wurde. Dateien, die du weglässt, werden nicht übernommen. Die folgenden Beispiele laden das vollständige financial_skill/-Bundle aus Einen Skill erstellen erneut hoch.

# Erstelle eine neue Version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Verwende eine bestimmte Version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Verwende die neueste Version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
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
YAML

Vollständige Details findest du in der Create Skill Version API-Referenz.

Wie Skills geladen werden

Wenn du Skills in einem Container angibst:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) im System-Prompt.
Datei-Laden: Skill-Dateien werden in den Container unter /skills/{skill-name}/ kopiert. Das Verzeichnis ist der Name des Skills (pptx für einen Anthropic-Skill, der name aus SKILL.md für einen benutzerdefinierten Skill), nicht seine skill_01...-ID.
Automatische Nutzung: Claude lädt und verwendet Skills automatisch, wenn sie für deine Anfrage relevant sind.
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Skills eignen sich sowohl für organisatorische als auch für persönliche Arbeit. Organisationen nutzen sie, um Markenformatierung auf Dokumente anzuwenden, Notizen und Berichte nach Unternehmensvorlagen zu strukturieren und unternehmensspezifische Analyseverfahren auszuführen. Einzelpersonen nutzen sie für benutzerdefinierte Dokumentvorlagen, spezialisierte Daten-Pipelines sowie Konventionen für Code-Generierung oder Deployment.

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle benutzerdefinierten DCF-Analyse-Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Limits und Einschränkungen

Request-Limits

Maximale Skills pro Request: 8
Maximale Skill-Upload-Größe: 30 MB (alle Dateien zusammen, unkomprimiert)
Anforderungen an das YAML-Frontmatter:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter („anthropic", „claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Umgebungseinschränkungen

Skills werden im Code-Execution-Container mit folgenden Einschränkungen ausgeführt:

Kein Netzwerkzugriff: Externe API-Aufrufe sind nicht möglich
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Ein neuer Container wird erstellt, sofern du keine vorhandene Container-ID angibst

Siehe Code-Execution-Tool für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombiniere Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen umfassen:

Gute Anwendungsfälle:

Datenanalyse (Excel) + Präsentationserstellung (PowerPoint)
Berichtserstellung (Word) + Export nach PDF
Benutzerdefinierte Domänenlogik + Dokumentgenerierung

Vermeide:

Das Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie für die Versionsverwaltung

Die SDK-Tabs in diesem Abschnitt zeigen den container-Wert, der in einen Messages-Request aufgenommen werden soll. Die cURL- und CLI-Tabs zeigen den vollständigen Request.

Für die Produktion: Lege eine bestimmte Version fest, damit Skill-Updates dein deploytes Verhalten nie ändern. Die Versions-ID stammt aus der Create-Version-Response in Versionierung oder aus der List Skill Versions API. Die ID ist immer ein String: Setze Epoch-Zeitstempel-IDs in JSON oder YAML in Anführungszeichen.

# Fixiere auf bestimmte Versionen für Stabilität
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

Für die Entwicklung: Verwende latest, um beim Iterieren automatisch die neueste Version zu erhalten.

# Verwende latest für die aktive Entwicklung
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Überlegungen zum Prompt-Caching

Wenn du Prompt-Caching verwendest, führt eine Änderung der Skills-Liste in deinem Container zu einem Cache-Miss. Skills werden in einer festen Reihenfolge in den System-Prompt gerendert, sodass dieselbe Liste dasselbe cachebare Präfix erzeugt:

client = anthropic.Anthropic()

# Skills werden in einer festen, cache-freundlichen Reihenfolge in den System-Prompt gerendert
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Eine Änderung der Skills-Liste ([xlsx] vs. [xlsx, pptx]) ändert das Präfix: ein Cache-Miss, während eine identische Liste ein Cache-Hit ist
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Für die beste Caching-Performance halte deine Skills-Liste, einschließlich ihrer Reihenfolge, über Requests hinweg konsistent. Das Festlegen von Versionen für benutzerdefinierte Skills hilft ebenfalls: Mit "latest" kann das Veröffentlichen einer neuen Version das gecachte Präfix ungültig machen, wenn sich dadurch die Beschreibung des Skills ändert.

Fehlerbehandlung

Behandle Skill-bezogene Fehler elegant:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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}")
        # Behandle Skill-spezifische Fehler
    else:
        raise

Datenaufbewahrung

Agent Skills sind nicht durch ZDR-Vereinbarungen abgedeckt. Skill-Definitionen und Ausführungsdaten werden gemäß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Informationen zur ZDR-Eignung für alle Funktionen findest du unter API und Datenaufbewahrung.

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

Best Practices für das Erstellen von Skills

Erfahre, wie du effektive Skills schreibst, die Claude entdecken und erfolgreich nutzen kann.

Code-Execution-Tool

Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu entwickeln.

Was this page helpful?

MessagesSkills

Agent Skills mit der API verwenden

Erfahre, wie du Agent Skills verwendest, um die Fähigkeiten von Claude über die API zu erweitern.

Schnellzugriff

Erste Schritte mit Agent Skills in der API

Erfahre, wie du Agent Skills verwendest, um in weniger als 10 Minuten Dokumente mit der Claude API zu erstellen.

Best Practices für das Erstellen von Skills

Erfahre, wie du effektive Skills schreibst, die Claude entdecken und erfolgreich nutzen kann.

Überblick

Skills verwenden

Du kannst Skills aus zwei Quellen verwenden:

Aspekt	Anthropic-Skills	Benutzerdefinierte Skills
Type-Wert	`anthropic`	`custom`
Skill-IDs	Kurznamen: `pptx`, `xlsx`, `docx`, `pdf`	Generiert: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Versionsformat	Datumsbasiert: `20251013` oder `latest`	Epoch-Zeitstempel: `1759178010641129` oder `latest`
Verwaltung	Vorgefertigt und von Anthropic gepflegt	Hochladen und Verwalten über die Skills API
Verfügbarkeit	Für alle Nutzer verfügbar	Privat in deinem Workspace

Voraussetzungen

Um Skills zu verwenden, benötigst du:

Claude API-Key aus der Claude Console
Beta-Header:
- code-execution-2025-08-25 – Aktiviert die Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 – Aktiviert die Skills API
- files-api-2025-04-14 – Nur erforderlich, wenn du die Files API verwendest, um Eingabedateien hochzuladen oder von einem Skill erzeugte Dateien herunterzuladen
Code-Execution-Tool in deinen Requests aktiviert

Skills erfordern das Code-Execution-Tool, verwende daher ein Modell aus dessen Modellkompatibilitätsliste.

Skills in Messages verwenden

Container-Parameter

Skills werden über den container-Parameter in der Messages API angegeben. Du kannst bis zu 8 Skills pro Request einbinden.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

Generierte Dateien herunterladen

Wenn Skills Dokumente erstellen (Excel, PowerPoint, PDF, Word), geben sie file_id-Attribute in der Response zurück. Du musst die Files API verwenden, um diese Dateien herunterzuladen.

So funktioniert es:

Skills erstellen Dateien während der Code-Ausführung.
Die Response enthält eine file_id für jede erstellte Datei, innerhalb der Tool-Result-Blöcke der Code-Ausführung (siehe Response-Format).
Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen.
Speichere lokal oder verarbeite nach Bedarf.

Um Eingabedateien bereitzustellen, mit denen Skills arbeiten sollen, lade sie mit der Files API hoch und referenziere sie in deinem Request mit einem Container-Upload-Block.

Beispiel: Erstellen und Herunterladen einer Excel-Datei

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)


# Schritt 2: Extrahiere Datei-IDs aus der Antwort
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":
                # jedes Content-Element ist ein bash_code_execution_output-Block mit einer file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Schritt 3: Lade die Datei über die Files API herunter
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Schritt 4: Speichere auf der Festplatte
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Zusätzliche Files-API-Operationen:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Rufe Datei-Metadaten ab
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Liste alle Dateien auf
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Lösche eine Datei
client.beta.files.delete(file_id=file_id)

Multi-Turn-Konversationen

client = anthropic.Anthropic()

# Erste Anfrage erstellt den Container
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Setze die Konversation mit demselben Container fort
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Übernimm den Text des Assistenten; container.id überträgt den Ausführungszustand
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

Lang laufende Operationen

Skills können Operationen ausführen, die mehrere Turns erfordern. Behandle pause_turn-Stop-Reasons:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)

# Behandle pause_turn für lange Operationen
for _ 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-opus-5",
        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"}],
    )

Mehrere Skills verwenden

Kombiniere mehrere Skills in einem einzigen Request, um komplexe Workflows zu bewältigen:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Der Upload einzelner Dateien erfordert pfadqualifizierte Dateinamen, die die CLI
# derzeit nicht setzen kann. Lade stattdessen ein ZIP-Archiv hoch.

Anforderungen:

Muss eine SKILL.md-Datei auf oberster Ebene enthalten
Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
Der Name des Verzeichnisses auf oberster Ebene muss mit dem name im SKILL.md-Frontmatter übereinstimmen (Groß-/Kleinschreibung und Unterstriche werden ignoriert: Financial_Skill entspricht financial-skill)
display_title ist optional: Wenn weggelassen, wird er vom name in SKILL.md abgeleitet; ein expliziter Wert muss unter den benutzerdefinierten Skills in deinem Workspace eindeutig sein
Die Gesamtgröße des Uploads muss unter 30 MB liegen (unkomprimiert)
Anforderungen an das YAML-Frontmatter:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter („anthropic", „claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Vollständige Request-/Response-Schemas findest du in der Create Skill API-Referenz.

Skills auflisten

# Liste alle Skills auf
ant beta:skills list

# Liste nur benutzerdefinierte Skills auf
ant beta:skills list --source custom

Siehe die List Skills API-Referenz für Paginierungs- und Filteroptionen.

Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Einen Skill löschen

Um einen Skill zu löschen, musst du zuerst alle seine Versionen löschen:

# Schritt 1: Liste die Versionen auf und lösche dann jede einzelne
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Wiederhole dies für jede Versions-ID, die die Liste zurückgegeben hat
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Schritt 2: Lösche den Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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:

Anthropic-Skills:

Versionen verwenden das Datumsformat: 20251013
Neue Versionen werden veröffentlicht, wenn Updates vorgenommen werden
Gib exakte Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwende "latest", um immer die neueste Version zu erhalten
Erstelle neue Versionen, wenn du Skill-Dateien aktualisierst

# Erstelle eine neue Version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Verwende eine bestimmte Version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Verwende die neueste Version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
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
YAML

Vollständige Details findest du in der Create Skill Version API-Referenz.

Wie Skills geladen werden

Wenn du Skills in einem Container angibst:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) im System-Prompt.
Datei-Laden: Skill-Dateien werden in den Container unter /skills/{skill-name}/ kopiert. Das Verzeichnis ist der Name des Skills (pptx für einen Anthropic-Skill, der name aus SKILL.md für einen benutzerdefinierten Skill), nicht seine skill_01...-ID.
Automatische Nutzung: Claude lädt und verwendet Skills automatisch, wenn sie für deine Anfrage relevant sind.
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle benutzerdefinierten DCF-Analyse-Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Limits und Einschränkungen

Request-Limits

Maximale Skills pro Request: 8
Maximale Skill-Upload-Größe: 30 MB (alle Dateien zusammen, unkomprimiert)
Anforderungen an das YAML-Frontmatter:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter („anthropic", „claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Umgebungseinschränkungen

Skills werden im Code-Execution-Container mit folgenden Einschränkungen ausgeführt:

Kein Netzwerkzugriff: Externe API-Aufrufe sind nicht möglich
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Ein neuer Container wird erstellt, sofern du keine vorhandene Container-ID angibst

Siehe Code-Execution-Tool für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombiniere Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen umfassen:

Gute Anwendungsfälle:

Datenanalyse (Excel) + Präsentationserstellung (PowerPoint)
Berichtserstellung (Word) + Export nach PDF
Benutzerdefinierte Domänenlogik + Dokumentgenerierung

Vermeide:

Das Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie für die Versionsverwaltung

Die SDK-Tabs in diesem Abschnitt zeigen den container-Wert, der in einen Messages-Request aufgenommen werden soll. Die cURL- und CLI-Tabs zeigen den vollständigen Request.

# Fixiere auf bestimmte Versionen für Stabilität
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

Für die Entwicklung: Verwende latest, um beim Iterieren automatisch die neueste Version zu erhalten.

# Verwende latest für die aktive Entwicklung
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Überlegungen zum Prompt-Caching

client = anthropic.Anthropic()

# Skills werden in einer festen, cache-freundlichen Reihenfolge in den System-Prompt gerendert
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Eine Änderung der Skills-Liste ([xlsx] vs. [xlsx, pptx]) ändert das Präfix: ein Cache-Miss, während eine identische Liste ein Cache-Hit ist
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Fehlerbehandlung

Behandle Skill-bezogene Fehler elegant:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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}")
        # Behandle Skill-spezifische Fehler
    else:
        raise

Datenaufbewahrung

Agent Skills sind nicht durch ZDR-Vereinbarungen abgedeckt. Skill-Definitionen und Ausführungsdaten werden gemäß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Informationen zur ZDR-Eignung für alle Funktionen findest du unter API und Datenaufbewahrung.

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

Best Practices für das Erstellen von Skills

Erfahre, wie du effektive Skills schreibst, die Claude entdecken und erfolgreich nutzen kann.

Code-Execution-Tool

Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu entwickeln.

Was this page helpful?

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie für die Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie für die Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie für die Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie für die Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte