MessagesSkills

Agent Skills mit der API verwenden

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

Agent Skills erweitern Claudes Fähigkeiten 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.

Die vollständige API-Referenz einschließlich Request-/Response-Schemas und aller Parameter findest du hier:

Skill Management API-Referenz - CRUD-Operationen für Skills
Skill Versions API-Referenz - Versionsverwaltung

Diese Funktion ist nicht für Zero Data Retention (ZDR) qualifiziert. Daten werden gemäß der standardmäßigen Aufbewahrungsrichtlinie der Funktion gespeichert.

Schnellzugriff

Erste Schritte mit Agent Skills

Erstelle deinen ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices für das Erstellen von Skills

Überblick

Für einen tiefen Einblick in die Architektur und reale Anwendungen von Agent Skills lies den Engineering-Blogbeitrag: Equipping agents for the real world with Agent Skills.

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

Skills verwenden

Skills integrieren sich in der Messages API unabhängig von ihrer Quelle identisch. Du gibst 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.

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 kommen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigst du:

Claude API-Key aus der Console
Beta-Header:
- code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 - Aktiviert die Skills API
- files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien in den/aus dem Container
Code-Execution-Tool in deinen Requests aktiviert

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-4-8",
    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.
Verwende die Files API, um den tatsächlichen Dateiinhalt herunterzuladen.
Speichere lokal oder verarbeite nach Bedarf.

Beispiel: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 die 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: Auf der Festplatte speichern
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Weitere Files-API-Operationen:

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

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

# Eine Datei löschen
client.beta.files.delete(file_id=file_id)

Vollständige Details zur Files API findest du in der Files-API-Dokumentation.

Mehrstufige Konversationen

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-4-8",
    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 trä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-4-8",
    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-Gründe:

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-4-8",
    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 bei langen 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-4-8",
        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 Response kann einen pause_turn-Stop-Grund enthalten, der anzeigt, dass die API eine lang laufende Skill-Operation pausiert hat. Du kannst die Response unverändert in einem nachfolgenden Request zurückgeben, damit Claude seinen Turn fortsetzt, oder den Inhalt ändern, wenn du die Konversation unterbrechen und zusätzliche Anleitung geben möchtest.

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-4-8",
    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 sowie beliebige unterstützende Skripte oder Ressourcen enthält. Siehe Erste Schritte mit Agent Skills in der API, um einen zu erstellen, und die Anforderungen-Liste 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 zusätzlich einen files_from_dir-Helper, der einen Verzeichnispfad akzeptiert.

Dateien werden über den Dateinamen identifiziert, den du anhängst. Uploads einzelner Dateien müssen ein gemeinsames Top-Level-Verzeichnis in ihren Pfaden beibehalten (das ;filename=-Suffix im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen), und ein Zip-Archiv muss das Skill-Verzeichnis als einzigen Top-Level-Eintrag enthalten.

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 Top-Level-Verzeichnisses 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 es weggelassen wird, wird es aus dem SKILL.md-name abgeleitet; ein expliziter Wert muss unter den benutzerdefinierten Skills in deinem Workspace eindeutig sein
Die Gesamtgröße des Uploads muss unter 30 MB liegen
Anforderungen an das YAML-Frontmatter:
- 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

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:

# Alle Skills auflisten
ant beta:skills list

# Nur benutzerdefinierte Skills auflisten
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 aus der zurückgegebenen Liste
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, sobald 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 updated_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-4-8
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-4-8
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.
Dateiladen: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert.
Automatische Nutzung: Claude lädt und verwendet Skills automatisch, wenn sie für deinen Request relevant sind.
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

Die Architektur der progressiven Offenlegung sorgt für eine effiziente Kontextnutzung: Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation

Unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente anwenden
Kommunikation nach organisatorischen Vorlagen generieren
Konsistente Markenrichtlinien über alle Ausgaben hinweg sicherstellen

Projektmanagement

Notizen mit unternehmensspezifischen Formaten strukturieren (OKRs, Entscheidungsprotokolle)
Aufgaben nach Team-Konventionen generieren
Standardisierte Meeting-Zusammenfassungen und Statusberichte erstellen

Geschäftsabläufe

Unternehmensstandardisierte Berichte, Angebote und Analysen erstellen
Unternehmensspezifische Analyseverfahren ausführen
Finanzmodelle nach organisatorischen Vorlagen generieren

Persönliche Skills

Content-Erstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Gestaltung
Domänenspezifische Content-Generierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische Analysemethoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Deployment-Workflows

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle einen benutzerdefinierten DCF-Analyse-Skill

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

# Verwende ihn mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)
Anforderungen an das YAML-Frontmatter:
- 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

Umgebungseinschränkungen

Skills laufen im Code-Ausführungscontainer mit diesen Einschränkungen:

Kein Netzwerkzugriff: Kann keine externen API-Aufrufe durchführen
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Container sind isoliert; ein neuer Container wird erstellt, sofern du keine bestehende Container-ID angibst

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

Best Practices

Wann mehrere Skills verwenden

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

Gute Anwendungsfälle:

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

Vermeide:

Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie zur Versionsverwaltung

Für die Produktion:

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

Für die Entwicklung:

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

Überlegungen zum Prompt-Caching

Beachte bei der Verwendung von Prompt-Caching, dass eine Änderung der Skills-Liste in deinem Container den Cache ungültig macht:

client = anthropic.Anthropic()

# Erste Anfrage erstellt den Cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Hinzufügen/Entfernen von Skills macht den Cache ungültig
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # 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 über Requests hinweg konsistent.

Fehlerbehandlung

Behandle Skill-bezogene Fehler angemessen:

client = anthropic.Anthropic()

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

Datenspeicherung

Agent Skills fallen nicht unter ZDR-Vereinbarungen. Skill-Definitionen und Ausführungsdaten werden gemäß Anthropics Standard-Datenspeicherungsrichtlinie aufbewahrt.

Informationen zur ZDR-Berechtigung für alle Features findest du unter API und Datenspeicherung.

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 erfolgreich entdecken und 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 zu iterieren

Was this page helpful?

MessagesSkills

Agent Skills mit der API verwenden

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

Die vollständige API-Referenz einschließlich Request-/Response-Schemas und aller Parameter findest du hier:

Skill Management API-Referenz - CRUD-Operationen für Skills
Skill Versions API-Referenz - Versionsverwaltung

Diese Funktion ist nicht für Zero Data Retention (ZDR) qualifiziert. Daten werden gemäß der standardmäßigen Aufbewahrungsrichtlinie der Funktion gespeichert.

Schnellzugriff

Erste Schritte mit Agent Skills

Erstelle deinen ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices für das Erstellen von Skills

Überblick

Für einen tiefen Einblick in die Architektur und reale Anwendungen von Agent Skills lies den Engineering-Blogbeitrag: Equipping agents for the real world with Agent Skills.

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 Console
Beta-Header:
- code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 - Aktiviert die Skills API
- files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien in den/aus dem Container
Code-Execution-Tool in deinen Requests aktiviert

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-4-8",
    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.
Verwende die Files API, um den tatsächlichen Dateiinhalt herunterzuladen.
Speichere lokal oder verarbeite nach Bedarf.

Beispiel: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 die 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: Auf der Festplatte speichern
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Weitere Files-API-Operationen:

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

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

# Eine Datei löschen
client.beta.files.delete(file_id=file_id)

Vollständige Details zur Files API findest du in der Files-API-Dokumentation.

Mehrstufige Konversationen

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-4-8",
    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 trä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-4-8",
    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-Gründe:

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-4-8",
    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 bei langen 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-4-8",
        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-4-8",
    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 Top-Level-Verzeichnisses 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 es weggelassen wird, wird es aus dem SKILL.md-name abgeleitet; ein expliziter Wert muss unter den benutzerdefinierten Skills in deinem Workspace eindeutig sein
Die Gesamtgröße des Uploads muss unter 30 MB liegen
Anforderungen an das YAML-Frontmatter:
- 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

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

Skills auflisten

# Alle Skills auflisten
ant beta:skills list

# Nur benutzerdefinierte Skills auflisten
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 aus der zurückgegebenen Liste
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, sobald 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 updated_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-4-8
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-4-8
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.
Dateiladen: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert.
Automatische Nutzung: Claude lädt und verwendet Skills automatisch, wenn sie für deinen Request relevant sind.
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

Die Architektur der progressiven Offenlegung sorgt für eine effiziente Kontextnutzung: Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation

Unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente anwenden
Kommunikation nach organisatorischen Vorlagen generieren
Konsistente Markenrichtlinien über alle Ausgaben hinweg sicherstellen

Projektmanagement

Notizen mit unternehmensspezifischen Formaten strukturieren (OKRs, Entscheidungsprotokolle)
Aufgaben nach Team-Konventionen generieren
Standardisierte Meeting-Zusammenfassungen und Statusberichte erstellen

Geschäftsabläufe

Unternehmensstandardisierte Berichte, Angebote und Analysen erstellen
Unternehmensspezifische Analyseverfahren ausführen
Finanzmodelle nach organisatorischen Vorlagen generieren

Persönliche Skills

Content-Erstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Gestaltung
Domänenspezifische Content-Generierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische Analysemethoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Deployment-Workflows

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle einen benutzerdefinierten DCF-Analyse-Skill

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

# Verwende ihn mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)
Anforderungen an das YAML-Frontmatter:
- 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

Umgebungseinschränkungen

Skills laufen im Code-Ausführungscontainer mit diesen Einschränkungen:

Kein Netzwerkzugriff: Kann keine externen API-Aufrufe durchführen
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Container sind isoliert; ein neuer Container wird erstellt, sofern du keine bestehende Container-ID angibst

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

Best Practices

Wann mehrere Skills verwenden

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

Gute Anwendungsfälle:

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

Vermeide:

Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie zur Versionsverwaltung

Für die Produktion:

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

Für die Entwicklung:

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

Überlegungen zum Prompt-Caching

Beachte bei der Verwendung von Prompt-Caching, dass eine Änderung der Skills-Liste in deinem Container den Cache ungültig macht:

client = anthropic.Anthropic()

# Erste Anfrage erstellt den Cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Hinzufügen/Entfernen von Skills macht den Cache ungültig
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # 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 über Requests hinweg konsistent.

Fehlerbehandlung

Behandle Skill-bezogene Fehler angemessen:

client = anthropic.Anthropic()

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

Datenspeicherung

Agent Skills fallen nicht unter ZDR-Vereinbarungen. Skill-Definitionen und Ausführungsdaten werden gemäß Anthropics Standard-Datenspeicherungsrichtlinie aufbewahrt.

Informationen zur ZDR-Berechtigung für alle Features findest du unter API und Datenspeicherung.

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 erfolgreich entdecken und 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 zu iterieren

Was this page helpful?

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Mehrstufige 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

Organisatorische Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwenden

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenspeicherung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Mehrstufige 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

Organisatorische Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwenden

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenspeicherung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Mehrstufige 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

Organisatorische Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwenden

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenspeicherung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Mehrstufige 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

Organisatorische Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwenden

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenspeicherung

Nächste Schritte