Utilizzo di Agent Skills con l'API

Agent Skills estendono le capacità di Claude attraverso cartelle organizzate di istruzioni, script e risorse. Questa guida mostra come utilizzare sia Skills pre-costruite che personalizzate con l'API Claude.

Per il riferimento API completo incluso schemi di richiesta/risposta e tutti i parametri, vedi:

Skill Management API Reference - Operazioni CRUD per Skills
Skill Versions API Reference - Gestione delle versioni

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

Quick Links

Inizia con Agent Skills

Crea la tua prima Skill

Crea Custom Skills

Best practices per la creazione di Skills

Overview

Per un approfondimento sull'architettura e le applicazioni nel mondo reale di Agent Skills, leggi il nostro blog di ingegneria: Equipping agents for the real world with Agent Skills.

Skills si integrano con l'API Messages attraverso lo strumento di esecuzione del codice. Che tu stia utilizzando Skills pre-costruite gestite da Anthropic o Skills personalizzate che hai caricato, la forma di integrazione è identica—entrambe richiedono l'esecuzione del codice e utilizzano la stessa struttura container.

Using Skills

Skills si integrano in modo identico nell'API Messages indipendentemente dalla fonte. Specifichi Skills nel parametro container con uno skill_id, type e opzionalmente version, e vengono eseguiti nell'ambiente di esecuzione del codice.

Puoi utilizzare Skills da due fonti:

Aspetto	Anthropic Skills	Custom Skills
Valore Type	`anthropic`	`custom`
Skill IDs	Nomi brevi: `pptx`, `xlsx`, `docx`, `pdf`	Generati: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Formato versione	Basato su data: `20251013` o `latest`	Timestamp epoch: `1759178010641129` o `latest`

Entrambe le fonti di skill sono restituite dall'endpoint List Skills (usa il parametro source per filtrare). La forma di integrazione e l'ambiente di esecuzione sono identici—l'unica differenza è da dove provengono le Skills e come vengono gestite.

Prerequisites

Per utilizzare Skills, hai bisogno di:

Chiave API Anthropic dalla Console
Beta headers:
- code-execution-2025-08-25 - Abilita l'esecuzione del codice (richiesto per Skills)
- skills-2025-10-02 - Abilita l'API Skills
- files-api-2025-04-14 - Per caricare/scaricare file da/verso il container
Strumento di esecuzione del codice abilitato nelle tue richieste

Using Skills in Messages

Container Parameter

Skills sono specificate utilizzando il parametro container nell'API Messages. Puoi includere fino a 8 Skills per richiesta.

La struttura è identica sia per Anthropic che per custom Skills—specifica il type e skill_id richiesti, e opzionalmente includi version per fissare una versione specifica:

Downloading Generated Files

Quando Skills creano documenti (Excel, PowerPoint, PDF, Word), restituiscono attributi file_id nella risposta. Devi utilizzare l'API Files per scaricare questi file.

Come funziona:

Skills creano file durante l'esecuzione del codice
La risposta include file_id per ogni file creato
Usa l'API Files per scaricare il contenuto effettivo del file
Salva localmente o elabora come necessario

Esempio: Creazione e download di un file Excel

Operazioni aggiuntive dell'API Files:

Per i dettagli completi sull'API Files, vedi la documentazione dell'API Files.

Multi-Turn Conversations

Riutilizza lo stesso container su più messaggi specificando l'ID del container:

Long-Running Operations

Skills possono eseguire operazioni che richiedono più turni. Gestisci i motivi di arresto pause_turn:

La risposta può includere un motivo di arresto pause_turn, che indica che l'API ha messo in pausa un'operazione Skill di lunga durata. Puoi fornire la risposta così com'è in una richiesta successiva per permettere a Claude di continuare il suo turno, o modificare il contenuto se desideri interrompere la conversazione e fornire ulteriori indicazioni.

Using Multiple Skills

Combina più Skills in una singola richiesta per gestire flussi di lavoro complessi:

Managing Custom Skills

Creating a Skill

Carica la tua Skill personalizzata per renderla disponibile nel tuo workspace. Puoi caricare utilizzando un percorso di directory o singoli oggetti file.

Requisiti:

Deve includere un file SKILL.md al livello superiore
Tutti i file devono specificare una directory radice comune nei loro percorsi
La dimensione totale del caricamento deve essere inferiore a 8MB
Requisiti del frontmatter YAML:
- name: Massimo 64 caratteri, solo lettere minuscole/numeri/trattini, nessun tag XML, nessuna parola riservata ("anthropic", "claude")
- description: Massimo 1024 caratteri, non vuoto, nessun tag XML

Per schemi di richiesta/risposta completi, vedi il riferimento API Create Skill.

Listing Skills

Recupera tutte le Skills disponibili nel tuo workspace, incluse sia le Skills pre-costruite Anthropic che le tue Skills personalizzate. Usa il parametro source per filtrare per tipo di skill:

Vedi il riferimento API List Skills per opzioni di paginazione e filtraggio.

Retrieving a Skill

Ottieni i dettagli su una Skill specifica:

Deleting a Skill

Per eliminare una Skill, devi prima eliminare tutte le sue versioni:

Il tentativo di eliminare una Skill con versioni esistenti restituirà un errore 400.

Versioning

Le Skills supportano il versioning per gestire gli aggiornamenti in modo sicuro:

Skills gestite da Anthropic:

Le versioni utilizzano il formato data: 20251013
Nuove versioni rilasciate quando vengono apportati aggiornamenti
Specifica versioni esatte per la stabilità

Custom Skills:

Timestamp epoch generati automaticamente: 1759178010641129
Usa "latest" per ottenere sempre la versione più recente
Crea nuove versioni quando aggiorni i file della Skill

Consulta il riferimento API Create Skill Version per i dettagli completi.

Come vengono caricate le Skills

Quando specifichi Skills in un container:

Metadata Discovery: Claude vede i metadati per ogni Skill (nome, descrizione) nel prompt di sistema
File Loading: I file della Skill vengono copiati nel container in /skills/{directory}/
Automatic Use: Claude carica e utilizza automaticamente le Skills quando rilevanti per la tua richiesta
Composition: Più Skills si compongono insieme per flussi di lavoro complessi

L'architettura di progressive disclosure garantisce un utilizzo efficiente del contesto—Claude carica solo le istruzioni complete della Skill quando necessario.

Casi d'uso

Organizational Skills

Brand & Communications

Applica la formattazione specifica dell'azienda (colori, caratteri, layout) ai documenti
Genera comunicazioni seguendo i template organizzativi
Assicura coerenza delle linee guida del brand in tutti gli output

Project Management

Struttura le note con formati specifici dell'azienda (OKRs, decision logs)
Genera attività seguendo le convenzioni del team
Crea riepiloghi di riunioni e aggiornamenti di stato standardizzati

Business Operations

Crea report, proposte e analisi standard dell'azienda
Esegui procedure analitiche specifiche dell'azienda
Genera modelli finanziari seguendo i template organizzativi

Personal Skills

Content Creation

Template di documenti personalizzati
Formattazione e styling specializzati
Generazione di contenuti specifici del dominio

Data Analysis

Pipeline di elaborazione dati personalizzate
Template di visualizzazione specializzati
Metodi analitici specifici del settore

Development & Automation

Template di generazione codice
Framework di testing
Flussi di lavoro di deployment

Esempio: Financial Modeling

Combina Skills di Excel e analisi DCF personalizzata:

Limiti e vincoli

Limiti di richiesta

Massimo Skills per richiesta: 8
Dimensione massima upload Skill: 8MB (tutti i file combinati)
Requisiti frontmatter YAML:
- name: Massimo 64 caratteri, solo lettere minuscole/numeri/trattini, nessun tag XML, nessuna parola riservata
- description: Massimo 1024 caratteri, non vuoto, nessun tag XML

Vincoli dell'ambiente

Le Skills vengono eseguite nel container di code execution con questi limiti:

Nessun accesso di rete - Non è possibile effettuare chiamate API esterne
Nessuna installazione di pacchetti runtime - Solo pacchetti preinstallati disponibili
Ambiente isolato - Ogni richiesta ottiene un container fresco

Consulta la documentazione dello strumento code execution per i pacchetti disponibili.

Best Practices

Quando utilizzare più Skills

Combina Skills quando le attività coinvolgono più tipi di documenti o domini:

Buoni casi d'uso:

Analisi dati (Excel) + creazione di presentazioni (PowerPoint)
Generazione di report (Word) + esportazione in PDF
Logica di dominio personalizzata + generazione di documenti

Evita:

Includere Skills non utilizzate (impatta le prestazioni)

Strategia di gestione delle versioni

Per la produzione:

# Fissa versioni specifiche per la stabilità
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Versione specifica
        }
    ]
}

Per lo sviluppo:

# Usa latest per lo sviluppo attivo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Ottieni sempre la più recente
        }
    ]
}

Considerazioni sulla prompt caching

Quando utilizzi prompt caching, nota che cambiare l'elenco delle Skills nel tuo container interromperà la cache:

Per le migliori prestazioni di caching, mantieni l'elenco delle Skills coerente tra le richieste.

Error Handling

Gestisci gli errori correlati alle Skills con eleganza:

Prossimi passi

API Reference

Riferimento API completo con tutti gli endpoint

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"]
)

# Crea una nuova versione
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"],
)

# Usa una versione specifica
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"}],
)

# Usa la versione più recente
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"}],
)

# Crea una Skill di analisi DCF personalizzata
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"],
)

# Usa con Excel per creare un modello finanziario
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"}],
)

# La prima richiesta crea la 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"}],
)

# Aggiungere/rimuovere Skills interrompe la 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}")
        # Gestisci errori specifici della Skill
    else:
        raise