Agent Skills mit der API verwenden

Agent Skills erweitern die Funktionen von Claude durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Diese Anleitung zeigt Ihnen, wie Sie sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwenden.

Für die vollständige API-Referenz einschließlich Request/Response-Schemas und aller Parameter siehe:

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

This feature is in beta and is not covered by Zero Data Retention (ZDR) arrangements. Beta features are excluded from ZDR.

Quick Links

Erste Schritte mit Agent Skills

Erstellen Sie Ihren ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices zum Verfassen von Skills

Übersicht

Für einen tieferen Einblick in die Architektur und reale Anwendungen von Agent Skills lesen Sie unseren Engineering-Blog: Equipping agents for the real world with Agent Skills.

Skills integrieren sich mit der Messages API über das Code-Ausführungs-Tool. Ob Sie vorgefertigte Skills verwenden, die von Anthropic verwaltet werden, oder benutzerdefinierte Skills, die Sie hochgeladen haben, die Integrationsform ist identisch – beide erfordern Code-Ausführung und verwenden die gleiche container-Struktur.

Skills verwenden

Skills integrieren sich identisch in der Messages API, unabhängig von der Quelle. Sie geben Skills im container-Parameter mit einer skill_id, einem type und einer optionalen version an, und sie werden in der Code-Ausführungsumgebung ausgeführt.

Sie können Skills aus zwei Quellen verwenden:

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`

Beide Skill-Quellen werden vom List Skills Endpoint zurückgegeben (verwenden Sie den source-Parameter zum Filtern). Die Integrationsform und die Ausführungsumgebung sind identisch – der einzige Unterschied ist, woher die Skills stammen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigen Sie:

Anthropic API-Schlüssel aus der Console
Beta-Header:
- code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 - Aktiviert Skills API
- files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien zum/vom Container
Code-Ausführungs-Tool aktiviert in Ihren Anfragen

Skills in Messages verwenden

Container-Parameter

Skills werden mit dem container-Parameter in der Messages API angegeben. Sie können bis zu 8 Skills pro Anfrage einschließen.

Die Struktur ist identisch für sowohl Anthropic als auch benutzerdefinierte Skills – geben Sie den erforderlichen type und skill_id an, und schließen Sie optional version ein, um auf eine bestimmte Version zu pinnen:

Heruntergeladene generierte Dateien

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

Wie es funktioniert:

Skills erstellen Dateien während der Code-Ausführung
Die Antwort enthält file_id für jede erstellte Datei
Verwenden Sie die Files API, um den tatsächlichen Dateiinhalt herunterzuladen
Speichern Sie lokal oder verarbeiten Sie nach Bedarf

Beispiel: Erstellen und Herunterladen einer Excel-Datei

Zusätzliche Files API-Operationen:

Für vollständige Details zur Files API siehe die Files API-Dokumentation.

Multi-Turn-Konversationen

Verwenden Sie denselben Container über mehrere Nachrichten hinweg wieder, indem Sie die Container-ID angeben:

Langfristige Operationen

Skills können Operationen durchführen, die mehrere Turns erfordern. Behandeln Sie pause_turn Stop-Gründe:

Die Antwort kann einen pause_turn Stop-Grund enthalten, der anzeigt, dass die API eine langfristige Skill-Operation pausiert hat. Sie können die Antwort in einer nachfolgenden Anfrage so wie sie ist bereitstellen, um Claude seinen Turn fortsetzen zu lassen, oder Sie können den Inhalt ändern, wenn Sie das Gespräch unterbrechen und zusätzliche Anleitung geben möchten.

Mehrere Skills verwenden

Kombinieren Sie mehrere Skills in einer einzelnen Anfrage, um komplexe Workflows zu handhaben:

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

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

Anforderungen:

Muss eine SKILL.md-Datei auf der obersten Ebene enthalten
Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
Die Gesamtgröße des Uploads muss unter 8 MB liegen
YAML-Frontmatter-Anforderungen:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Zahlen/Bindestriche, keine XML-Tags, keine reservierten Wörter („anthropic", „claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Für vollständige Request/Response-Schemas siehe die Create Skill API Reference.

Skills auflisten

Rufen Sie alle Skills ab, die in Ihrem Workspace verfügbar sind, einschließlich sowohl vorgefertigter Anthropic Skills als auch Ihrer benutzerdefinierten Skills. Verwenden Sie den source-Parameter zum Filtern nach Skill-Typ:

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

Einen Skill abrufen

Rufen Sie Details zu einem bestimmten Skill ab:

Einen Skill löschen

Um einen Skill zu löschen, müssen Sie zunächst alle seine Versionen löschen:

Der Versuch, einen Skill mit vorhandenen Versionen zu löschen, gibt einen 400-Fehler zurück.

Versionierung

Skills unterstützen Versionierung, um Updates sicher zu verwalten:

Von Anthropic verwaltete Skills:

Versionen verwenden Datumsformat: 20251013
Neue Versionen werden als Updates veröffentlicht
Geben Sie exakte Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwenden Sie "latest", um immer die neueste Version zu erhalten
Erstellen Sie neue Versionen beim Aktualisieren von Skill-Dateien

Weitere Informationen finden Sie in der API-Referenz zum Erstellen von Skill-Versionen.

Wie Skills geladen werden

Wenn Sie Skills in einem Container angeben:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) in der Systemaufforderung
Dateiladung: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert
Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für Ihre Anfrage relevant sind
Zusammensetzung: Mehrere Skills arbeiten zusammen für komplexe Workflows

Die progressive Offenlegungsarchitektur gewährleistet eine effiziente Kontextnutzung – Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation

Wenden Sie unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente an
Generieren Sie Kommunikationen nach organisatorischen Vorlagen
Stellen Sie sicher, dass Markenrichtlinien in allen Ausgaben konsistent sind

Projektmanagement

Strukturieren Sie Notizen mit unternehmensspezifischen Formaten (OKRs, Entscheidungsprotokolle)
Generieren Sie Aufgaben nach Team-Konventionen
Erstellen Sie standardisierte Meeting-Zusammenfassungen und Status-Updates

Geschäftsbetrieb

Erstellen Sie unternehmensstandard-Berichte, Vorschläge und Analysen
Führen Sie unternehmensspezifische analytische Verfahren durch
Generieren Sie Finanzmodelle nach organisatorischen Vorlagen

Persönliche Skills

Inhaltserstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Styling
Domänenspezifische Inhaltsgenerierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische analytische Methoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Bereitstellungs-Workflows

Beispiel: Finanzmodellierung

Kombinieren Sie Excel und benutzerdefinierte DCF-Analyse-Skills:

Limits und Einschränkungen

Anfragegrenzen

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

Umgebungseinschränkungen

Skills werden im Code-Ausführungs-Container mit diesen Einschränkungen ausgeführt:

Kein Netzwerkzugriff – Können keine externen API-Aufrufe tätigen
Keine Laufzeit-Paketinstallation – Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung – Jede Anfrage erhält einen frischen Container

Weitere Informationen finden Sie in der Dokumentation des Code-Ausführungs-Tools für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombinieren Sie Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen betreffen:

Gute Anwendungsfälle:

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

Vermeiden Sie:

Einbeziehung ungenutzter Skills (beeinträchtigt die Leistung)

Versionsverwaltungsstrategie

Für Produktion:

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Für Entwicklung:

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Überlegungen zum Prompt-Caching

Beachten Sie beim Verwenden von Prompt-Caching, dass das Ändern der Skills-Liste in Ihrem Container den Cache bricht:

Für optimale Caching-Leistung halten Sie Ihre Skills-Liste über Anfragen hinweg konsistent.

Fehlerbehandlung

Behandeln Sie Skill-bezogene Fehler elegant:

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

import anthropic

client = anthropic.Anthropic()

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

import anthropic

client = anthropic.Anthropic()

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


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


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

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id, betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

# Delete a file
client.beta.files.delete(file_id=file_id, betas=["files-api-2025-04-14"])

# First request creates container
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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

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

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

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

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-4-6",
        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"}],
    )

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

import anthropic

client = anthropic.Anthropic()

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

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

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

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

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

# List all Skills
skills = client.beta.skills.list(betas=["skills-2025-10-02"])

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

# List only custom Skills
custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"])

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

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

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

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

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

# Create a new version
from anthropic.lib import files_from_dir

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

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

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

# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir

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

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

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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