Claude Platform Docs
MessagesSkills

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.

Erfahre, wie du mit Agent Skills in weniger als 10 Minuten Dokumente mit der Claude API erstellst.

Erfahre, wie du effektive Skills schreibst, die Claude erfolgreich entdecken und verwenden 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 skill_id, type und optional version an, und sie laufen in der Code-Execution-Umgebung.

Du kannst Skills aus zwei Quellen verwenden:

AspektAnthropic SkillsBenutzerdefinierte Skills
Type-Wertanthropiccustom
Skill-IDsKurznamen: pptx, xlsx, docx, pdfGeneriert: skill_01AbCdEfGhIjKlMnOpQrStUv
VersionsformatDatumsbasiert: 20251013 oder latestVersions-ID: skver_01AbCdEfGhIjKlMnOpQrStUv oder latest
VerwaltungVorgefertigt und von Anthropic gepflegtHochladen und Verwalten über die Skills API
VerfügbarkeitFür alle Nutzer verfügbarPrivat für deinen 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:

  1. Claude API-Key aus der Claude Console
  2. Code-Execution-Tool, das in deinen Requests aktiviert ist

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 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-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 Code-Ausführung.
  2. Die Response enthält für jede erstellte Datei eine file_id innerhalb der Tool-Result-Blöcke der Code-Ausfü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-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 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 Inhaltselement ist ein bash_code_execution_output-Block, der eine file_id enthält
                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: 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.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 Container
response1 = client.messages.create(
    model="claude-opus-5-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"}],
)

# Unterhaltung mit demselben Container fortsetzen
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Übernimm den Text des Assistenten; container.id trägt den Ausführungsstatus
        "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-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-5",
    max_tokens=4096,
    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.messages.create(
        model="claude-opus-5-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-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 alle unterstützenden 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, und der CLI-Befehl ant apply lädt das Verzeichnis selbst hoch.

Dateien werden anhand des Dateinamens identifiziert, den du anhängst (das ;filename=-Suffix im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen). Für den Skill aus der 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.

ant apply financial_skill
financial_skill/SKILL.md
---
name: financial-skill
description: Docs example skill.
---
financial_skill/analyze.py
print("financial analysis helper")

Anforderungen:

  • Muss eine SKILL.md-Datei im Upload-Root 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/Zahlen/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:

client = anthropic.Anthropic()

# Alle Skills auflisten
for skill in client.skills.list():
    print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")

# Nur benutzerdefinierte Skills auflisten
custom_skills = client.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:

client = anthropic.Anthropic()

skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")

Einen Skill löschen

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

client = anthropic.Anthropic()

client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

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.

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle eine neue Version

new_version = client.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("financial_skill"),
)

# Verwende eine bestimmte Version
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": new_version.id,
            }
        ]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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

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 nach 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. Erstelle zunächst den benutzerdefinierten DCF-Analyse-Skill:

ant apply dcf_skill

Verwende ihn dann mit dem Excel-Skill, um ein Finanzmodell zu erstellen. Übergib die ID des von dir erstellten Skills als skill_id des benutzerdefinierten Skills:

client = anthropic.Anthropic()

# Benutzerdefinierter DCF-Analyse-Skill (ID aus der Create-Antwort der Skills-API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.messages.create(
    model="claude-opus-5-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/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-Execution-Container mit diesen Einschränkungen:

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

Verfügbare Pakete findest du unter Code-Execution-Tool.


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, auch wenn sie numerisch aussieht.

# Auf bestimmte Versionen festlegen für Stabilität
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-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"}],
)

# Das Ändern 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-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-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}")
        # Behandle skill-spezifische Fehler
    else:
        raise

Migration von skills-2025-10-02

Die Skills API ist nicht mehr in der Beta und benötigt keinen Beta-Header. Die Migration weg von skills-2025-10-02 ist optional: Requests, die ihn weiterhin senden, funktionieren weiter und geben weiterhin die Beta-Response-Formen zurück, sodass eine bestehende Integration weiter funktioniert, bis du sie änderst. Das Entfernen des Headers stellt diese Requests auf die auf dieser Seite dokumentierten Formen um:

Mit skills-2025-10-02Ohne den Header
Skill-Bezeichnungdisplay_title (bis zu 64 Zeichen, eindeutig pro Workspace)display_name (bis zu 255 Zeichen, nicht eindeutig); wird aus dem name der SKILL.md abgeleitet, wenn weggelassen
Zeiger auf die neueste Versionlatest_version, ein Epoch-Mikrosekunden-String wie "1759178010641129"latest_version_id, eine Versions-ID wie "skver_01AbCdEfGhIjKlMnOpQrStUv"; GET /v1/skills/{skill_id}/versions/latest löst sie in einem Aufruf auf
Versionskennung in URLsEpoch-Mikrosekunden-StringVersions-ID (skver_...). Unter der Beta erfasste IDs mit dem Präfix skill_version_ werden als Eingabe akzeptiert.
VersionsobjektEnthält directory (immer gleich dem Skill-name)Kein directory-Feld
sourceEin String, "custom" oder "anthropic"Ein Objekt, zum Beispiel {"type": "custom"}; der Wert für den Beispielkatalog ist "anthropic_example"
List-Responses{ data, has_more, next_page }{ data, next_page }; limit von 1 bis 1.000 (Standard 20)
Reihenfolge der VersionslisteÄlteste zuerstNeueste zuerst, Standard-limit 20. Seiten-Cursor der einen Form sind für die andere nicht gültig.
Löschen eines SkillsGibt einen 400-Fehler zurück, solange eine Version existiertLöscht den Skill und alle seine Versionen
Löschen der einzigen Version eines SkillsErlaubt, hinterlässt einen Skill ohne VersionenGibt einen 400-Fehler zurück; lade zuerst eine Ersatzversion hoch oder lösche den Skill
Upload-LayoutDateien müssen in einem Verzeichnis auf oberster Ebene liegen, dessen Name mit dem Skill-name übereinstimmtSKILL.md darf im Root des Uploads liegen; die gespeicherten Pfade sind in beiden Fällen gleich
Response-TypenCreateSkillResponse, GetSkillResponse und ein Typ pro OperationSkill, SkillVersion, DeletedSkill, DeletedSkillVersion

So migrierst du:

  1. Entferne den Beta-Header. Entferne anthropic-beta: skills-2025-10-02 aus deinen Requests. Rufe in den SDKs client.skills statt client.beta.skills auf; client.beta.skills beizubehalten funktioniert nur mit den SDK-Releases, die den Header nicht mehr senden. Frühere Releases senden ihn von client.beta.skills aus, auch ohne betas-Argument.
  2. Benenne Felder in deinem Code um: display_title zu display_name, latest_version zu latest_version_id, und lies source.type, statt source mit einem String zu vergleichen.
  3. Verwende Versions-IDs. Überall, wo du eine Epoch-Mikrosekunden-Version gespeichert hast, speichere stattdessen die id der Version oder verwende latest. Skill-Referenzen in Messages-Requests akzeptieren eine Versions-ID, latest oder (für Anthropic Skills) die Katalogversion.
  4. Überprüfe Delete-Aufrufe. DELETE /v1/skills/{skill_id} entfernt jetzt jede Version zusammen mit dem Skill. Wenn du dich auf die Verweigerung der Beta als Schutzmaßnahme verlassen hast, füge eine eigene Prüfung hinzu.

Ein Skill, dessen Versionen unter der Beta alle gelöscht wurden, hat keine aktuelle Version, die zurückgegeben werden könnte: GET /v1/skills/{skill_id} gibt einen 400-Fehler zurück, und der Skill wird in List-Responses ausgelassen, bis du eine Version dafür hochlädst. Du kannst ihn weiterhin löschen.

SDK-Beta-Namespace

Ab Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 und C# SDK 12.44.0 sendet client.beta.skills nicht mehr skills-2025-10-02 und gibt dieselben Formen wie client.skills zurück, mit Typnamen mit Beta-Präfix (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Es akzeptiert ein betas-Argument für Skills-Features, die sich noch in der Beta befinden. In den Beta-Messages-Typen wird der Container-Skill-Referenztyp von BetaSkill in BetaContainerSkill umbenannt (gleiche Felder: type, skill_id, version); BetaSkill bezeichnet jetzt die Skill-Ressource, entsprechend Skill und ContainerSkill in den Nicht-Beta-Typen. Frühere SDK-Releases sind auf die Beta-Formen typisiert; wenn du von diesen Typen abhängst, bleibe bei einem früheren Release, bis du migrierst.

Datenaufbewahrung

Agent Skills sind nicht von ZDR-Vereinbarungen abgedeckt. 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

Vollständige API-Referenz mit allen Endpunkten

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

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

Was this page helpful?