Agent Skills mit der API verwenden

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



Überblick

Skills werden über das „code execution tool" (Code-Ausführungstool) in die Messages API integriert, siehe Code-Ausführungstool. Unabhängig davon, ob du vorgefertigte, von Anthropic verwaltete Skills oder selbst hochgeladene benutzerdefinierte Skills verwendest, ist die Form der Integration identisch: Beide erfordern Codeausführung und verwenden dieselbe container-Struktur.



Skills verwenden

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

Du kannst Skills aus zwei Quellen verwenden:

Beide Skill-Quellen werden vom List Skills-Endpunkt zurückgegeben (verwende den source-Parameter zum Filtern). Die Form der Integration 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:

1. Claude API-Key aus der Claude Console
2. Code-Ausführungstool, das in deinen Requests aktiviert ist

Skills sind auf der Claude API allgemein verfügbar und erfordern keinen anthropic-beta-Header, weder für die Skills API noch für container.skills in Messages-Requests. Requests, die weiterhin den Beta-Header skills-2025-10-02 senden, funktionieren weiterhin, und Skills API-Requests, die ihn senden, behalten das frühere Beta-Response-Format. Die PHP-Tabs auf dieser Seite rufen weiterhin den beta-Namespace des SDK auf und senden diesen Header, sodass ihre ausgegebene Ausgabe die früheren Response-Felder zeigt.

Skills erfordern das Code-Ausführungstool, 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 20 Skills pro Request einbinden.

Die Struktur ist für Anthropic Skills 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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:

1. Skills erstellen Dateien während der Codeausführung.
2. Die Response enthält für jede erstellte Datei eine file_id innerhalb der Tool-Result-Blöcke der Codeausführung (siehe Response-Format).
3. Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen.
4. Speichere die Datei lokal oder verarbeite sie 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: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.files.retrieve_metadata(file_id=file_id)
    file_content = client.files.download(file_id=file_id)

    # Schritt 4: Speichere sie auf der Festplatte
    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.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.files.list():
    print(f"{file.filename} - {file.created_at}")

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



Mehrstufige 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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"}],
)

# Konversation mit demselben Container fortsetzen
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Text des Assistenten weitergeben; 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# pause_turn bei lang laufenden Operationen behandeln
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 YAML-Frontmatter für name und description sowie beliebige unterstützende Skripte oder Ressourcen enthält. Siehe Erste Schritte mit Agent Skills in der API, um einen 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 (das Suffix ;filename= im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen). Für den Skill aus der Schritt-für-Schritt-Anleitung erstellst du ein Zip mit zip -r financial_skill.zip financial_skill/ und setzt es anstelle des Platzhalters example_skill.zip in den Zip-Upload-Optionen ein.

zip -r financial_skill.zip financial_skill/
ant skills create --file financial_skill.zip

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Anforderungen:

• Muss eine SKILL.md-Datei im Upload-Stammverzeichnis enthalten (oder auf oberster Ebene eines einzelnen umschließenden Ordners)
• display_name ist optional: Wenn es weggelassen wird, wird es aus dem name der SKILL.md abgeleitet; ein expliziter Wert darf bis zu 255 Zeichen lang sein und muss innerhalb des Workspace nicht eindeutig sein
• Die gesamte Upload-Größe 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

Die vollständigen Request-/Response-Schemas findest du in der Create Skill API-Referenz.



Skills auflisten

Rufe alle für deinen Workspace verfügbaren Skills ab, einschließlich der vorgefertigten Anthropic Skills und deiner benutzerdefinierten Skills. Verwende den source-Parameter, um nach Skill-Typ zu filtern:

# Alle Skills auflisten
ant skills list

# Nur benutzerdefinierte Skills auflisten
ant skills list --source custom

Paginierungs- und Filteroptionen findest du in der List Skills API-Referenz.



Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

ant skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv



Einen Skill löschen

Das Löschen eines Skills entfernt auch alle seine Versionen.

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null



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 Versions-IDs: skver_01AbCdEfGhIjKlMnOpQrStUv
• 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. Dateien, die du weglässt, werden nicht übernommen, und der name in der SKILL.md der neuen Version muss mit dem bestehenden Namen des Skills übereinstimmen. Die folgenden Beispiele laden das vollständige financial_skill/-Bundle aus Einen Skill erstellen erneut hoch.

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

# Verwende eine bestimmte Version
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_ID"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Verwende die neueste Version
ant messages create <<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:

1. Metadaten-Erkennung: Claude sieht die Metadaten jedes Skills (Name, Beschreibung) im System-Prompt.
2. Laden der Dateien: 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 der SKILL.md für einen benutzerdefinierten Skill), nicht seine skill_01...-ID.
3. Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für deinen Request relevant sind.
4. Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

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



Anwendungsfälle

Skills eignen sich sowohl für organisatorische als auch für persönliche Arbeit. Organisationen verwenden sie, um Marken-Formatierung auf Dokumente anzuwenden, Notizen und Berichte anhand von Unternehmensvorlagen zu strukturieren und unternehmensspezifische Analyseverfahren auszuführen. Einzelpersonen verwenden sie für benutzerdefinierte Dokumentvorlagen, spezialisierte Datenpipelines sowie Konventionen für Codegenerierung oder Deployment.



Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle einen benutzerdefinierten Skill für DCF-Analysen

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

# Verwende ihn mit Excel, um ein Finanzmodell zu erstellen
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 Anzahl Skills pro Request: 20
• 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 laufen im Code-Ausführungscontainer mit diesen Einschränkungen:

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

Verfügbare Pakete findest du unter Code-Ausführungstool.



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 als PDF
• Benutzerdefinierte Domänenlogik + Dokumentgenerierung

Vermeide:

• Das Einbinden ungenutzter Skills (beeinträchtigt die Performance)



Strategie zur 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 niemals dein bereitgestelltes Verhalten ändern. Wenn du version weglässt oder auf "latest" setzt, verwenden Requests die neueste Version des Skills, sodass eine von irgendjemandem im Workspace hochgeladene Version sofort ändert, was deine Produktions-Agenten ausführen. Die Versions-ID stammt aus der Create-Version-Response unter Versionierung oder aus der List Skill Versions API. Die ID ist immer ein String, setze sie daher in JSON oder YAML in Anführungszeichen (Versionen, die unter dem Beta-Header skills-2025-10-02 erstellt wurden, haben numerisch aussehende Epoch-Zeitstempel-IDs).

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

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

# 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, bricht eine Änderung der Skills-Liste in deinem Container den Cache. 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 benutzerdefinierter 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 sauber:

client = anthropic.Anthropic()

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



Datenaufbewahrung

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

Zur ZDR-Berechtigung über alle Features hinweg siehe API und Datenaufbewahrung.



Audit-Logging

Wenn deine Organisation die Compliance API aktiviert hat, zeichnet deren Activity Feed das Erstellen und Löschen von Skills und Skill-Versionen auf, die mit einem Claude API-Key oder über die Claude Console vorgenommen werden. Operationen, die stattfinden, während die Compliance API deaktiviert ist, werden nicht aufgezeichnet und können später nicht wiederhergestellt werden. Richte daher die Compliance API ein, bevor du dich auf diesen Audit-Trail verlässt.



Nächste Schritte