Usare le Agent Skills con l'API

Le Agent Skills estendono le capacità di Claude tramite cartelle organizzate di istruzioni, script e risorse. Questa guida ti mostra come usare sia le Skills predefinite sia quelle personalizzate con la Claude API.

Link rapidi

Panoramica

Le Skills si integrano con la Messages API tramite lo strumento di esecuzione del codice. Sia che tu usi Skills predefinite gestite da Anthropic sia Skills personalizzate che hai caricato, la forma dell'integrazione è identica: entrambe richiedono l'esecuzione del codice e usano la stessa struttura container.

Usare le Skills

Le Skills si integrano in modo identico nella Messages API indipendentemente dalla loro origine. Specifichi le Skills nel parametro container con skill_id, type e un version opzionale, e vengono eseguite nell'ambiente di esecuzione del codice.

Puoi usare Skills da due origini:

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

Prerequisiti

Per usare le Skills, hai bisogno di:

1. Chiave API di Claude dalla Claude Console
2. Strumento di esecuzione del codice abilitato nelle tue richieste

Le Skills richiedono lo strumento di esecuzione del codice, quindi usa un modello presente nel suo elenco di compatibilità dei modelli.

Usare le Skills in Messages

Parametro container

Le Skills vengono specificate usando il parametro container nella Messages API. Puoi includere fino a 20 Skills per ogni richiesta.

La struttura è identica sia per le Skills di Anthropic sia per quelle personalizzate. Specifica i campi obbligatori type e skill_id e, facoltativamente, includi version per fissare una versione specifica:

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

Scaricare i file generati

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

Come funziona:

1. Le Skills creano file durante l'esecuzione del codice.
2. La risposta include un file_id per ogni file creato, all'interno dei blocchi di risultato dello strumento di esecuzione del codice (vedi Formato della risposta).
3. Usa la Files API per scaricare il contenuto effettivo del file.
4. Salva in locale o elabora secondo necessità.

Per fornire file di input su cui le Skills possano lavorare, caricali con la Files API e fai riferimento a essi nella tua richiesta con un blocco container upload.

Esempio: creare e scaricare un file Excel

client = anthropic.Anthropic()

# Passaggio 1: usa una Skill per creare un file
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"}],
)


# Passaggio 2: estrai gli ID dei file dalla risposta
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":
                # ogni elemento di contenuto è un blocco bash_code_execution_output con un file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Passaggio 3: scarica il file usando la Files API
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)

    # Passaggio 4: salva su disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operazioni aggiuntive della Files API:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Ottieni i metadati del file
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Elenca tutti i file
for file in client.files.list():
    print(f"{file.filename} - {file.created_at}")

# Elimina un file
client.files.delete(file_id=file_id)

Conversazioni multi-turno

L'oggetto container della risposta contiene l'id del container e il timestamp expires_at (vedi Riutilizzo del container per i dettagli sulla durata). Riutilizza lo stesso container in più messaggi specificando l'ID del container:

client = anthropic.Anthropic()

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

# Continua la conversazione con lo stesso container
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Riporta avanti il testo dell'assistente; container.id conserva lo stato di esecuzione
        "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"}],
)

Operazioni di lunga durata

Le Skills possono eseguire operazioni che richiedono più turni. Gestisci gli stop reason pause_turn:

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

# Gestisci pause_turn per le operazioni lunghe
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"}],
    )

Usare più Skills

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

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

Gestire le Skills personalizzate

Creare una Skill

Un bundle di Skill è una directory contenente un file SKILL.md al livello superiore con frontmatter YAML name e description, più eventuali script o risorse di supporto. Consulta Inizia con le Agent Skills nell'API per crearne una, e l'elenco Requisiti che segue gli esempi per i vincoli completi.

Carica la tua Skill personalizzata per renderla disponibile nel tuo workspace. Puoi caricare un archivio zip o singoli oggetti file. L'SDK Python fornisce anche un helper files_from_dir che accetta il percorso di una directory, e il comando ant apply della CLI carica direttamente la directory.

I file sono identificati dal nome file che alleghi (il suffisso ;filename= nell'esempio cURL e gli argomenti filename negli esempi SDK). Per la skill della procedura guidata, crea uno zip con zip -r financial_skill.zip financial_skill/ e sostituiscilo al segnaposto example_skill.zip nelle opzioni di caricamento zip.

ant apply financial_skill

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

print("financial analysis helper")

Requisiti:

• Deve includere un file SKILL.md alla radice del caricamento (o al livello superiore di una singola cartella contenitore)
• display_name è opzionale: se omesso, viene derivato dal name di SKILL.md; un valore esplicito può avere fino a 255 caratteri e non deve essere univoco all'interno del workspace
• La dimensione totale del caricamento deve essere inferiore a 30 MB (non compressa)
• 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 gli schemi completi di richiesta/risposta, consulta il riferimento API Create Skill.

Elencare le Skills

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

client = anthropic.Anthropic()

# Elenca tutte le Skill
for skill in client.skills.list():
    print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")

# Elenca solo le Skill personalizzate
custom_skills = client.skills.list(source="custom")

Consulta il riferimento API List Skills per le opzioni di paginazione e filtro.

Recuperare una Skill

Ottieni i dettagli di una Skill specifica:

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

Eliminare una Skill

L'eliminazione di una Skill rimuove anche tutte le sue versioni.

client = anthropic.Anthropic()

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

Versionamento

Le Skills supportano il versionamento per gestire gli aggiornamenti in sicurezza:

Skills di Anthropic:

• Le versioni usano il formato data: 20251013
• Nuove versioni rilasciate man mano che vengono apportati aggiornamenti
• Specifica versioni esatte per la stabilità

Skills personalizzate:

• ID di versione generati automaticamente: skver_01AbCdEfGhIjKlMnOpQrStUv
• Usa "latest" per ottenere sempre la versione più recente
• Crea nuove versioni quando aggiorni i file della Skill

Una nuova versione è uno snapshot completo, non un delta: carica ogni volta l'intero set di file della Skill. I file che ometti non vengono riportati, e il name nel SKILL.md della nuova versione deve corrispondere al nome esistente della Skill. Gli esempi seguenti ricaricano il bundle completo financial_skill/ da Creare una Skill.

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Crea una nuova versione

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

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

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

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

Come vengono caricate le Skills

Quando specifichi Skills in un container:

1. Individuazione dei metadati: Claude vede i metadati di ogni Skill (nome, descrizione) nel prompt di sistema.
2. Caricamento dei file: i file della Skill vengono copiati nel container in /skills/{skill-name}/. La directory è il nome della Skill (pptx per una Skill di Anthropic, il name di SKILL.md per una Skill personalizzata), non il suo ID skill_01....
3. Uso automatico: Claude carica e usa automaticamente le Skills quando sono pertinenti alla tua richiesta.
4. Composizione: più Skills si compongono insieme per flussi di lavoro complessi.

Claude carica le istruzioni complete della Skill solo quando necessario.

Casi d'uso

Le Skills si adattano sia al lavoro organizzativo sia a quello personale. Le organizzazioni le usano per applicare la formattazione del brand ai documenti, strutturare note e report secondo i template aziendali ed eseguire procedure analitiche specifiche dell'azienda. I singoli le usano per template di documenti personalizzati, pipeline di dati specializzate e convenzioni di generazione del codice o di deployment.

Esempio: modellazione finanziaria

Combina la Skill Excel con una Skill personalizzata di analisi DCF. Per prima cosa, crea la Skill personalizzata di analisi DCF:

ant apply dcf_skill

Quindi usala insieme alla Skill Excel per creare un modello finanziario. Passa l'ID della Skill che hai creato come skill_id della Skill personalizzata:

client = anthropic.Anthropic()

# Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"

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

Limiti e vincoli

Limiti delle richieste

• Numero massimo di Skills per richiesta: 20
• Dimensione massima di caricamento di una Skill: 30 MB (tutti i file combinati, non compressi)
• 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

Vincoli dell'ambiente

Le Skills vengono eseguite nel container di esecuzione del codice con queste limitazioni:

• Nessun accesso alla rete: non è possibile effettuare chiamate API esterne
• Nessuna installazione di pacchetti a runtime: sono disponibili solo i pacchetti preinstallati
• Ambiente isolato: viene creato un nuovo container a meno che tu non specifichi l'ID di un container esistente

Consulta Strumento di esecuzione del codice per i pacchetti disponibili.

Best practice

Quando usare più Skills

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

Buoni casi d'uso:

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

Da evitare:

• Includere Skills non utilizzate (influisce sulle prestazioni)

Strategia di gestione delle versioni

Le schede SDK in questa sezione mostrano il valore container da includere in una richiesta Messages. Le schede cURL e CLI mostrano la richiesta completa.

Per la produzione: fissa una versione specifica, in modo che gli aggiornamenti delle Skills non modifichino mai il comportamento distribuito. Se ometti version o lo imposti su "latest", le richieste usano la versione più recente della Skill, quindi una versione caricata da chiunque nel workspace cambia immediatamente ciò che eseguono i tuoi agenti in produzione. L'ID di versione proviene dalla risposta di creazione della versione in Versionamento o dalla List Skill Versions API. L'ID è sempre una stringa, quindi racchiudilo tra virgolette in JSON o YAML anche quando sembra numerico.

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

Per lo sviluppo: usa latest per ottenere automaticamente la versione più recente mentre iteri.

# Usa latest per lo sviluppo attivo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Considerazioni sulla cache dei prompt

Se usi la cache dei prompt ("prompt caching"), modificare l'elenco delle Skills nel tuo container invalida la cache. Le Skills vengono rese nel prompt di sistema in un ordine fisso, quindi lo stesso elenco produce lo stesso prefisso memorizzabile in cache:

client = anthropic.Anthropic()

# Le Skills vengono inserite nel prompt di sistema in un ordine fisso e adatto alla cache
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"}],
)

# Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
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"}],
)

Per le migliori prestazioni di caching, mantieni coerente tra le richieste il tuo elenco di Skills, incluso il suo ordine. Anche fissare le versioni delle Skills personalizzate aiuta: con "latest", la pubblicazione di una nuova versione può invalidare il prefisso in cache se modifica la descrizione della Skill.

Gestione degli errori

Gestisci con eleganza gli errori relativi alle Skills:

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}")
        # Gestisci gli errori specifici delle skill
    else:
        raise

Migrare da skills-2025-10-02

La Skills API è uscita dalla beta e non richiede alcun header beta. La migrazione da skills-2025-10-02 è facoltativa: le richieste che lo inviano ancora continuano a funzionare e continuano a restituire le forme di risposta beta, quindi un'integrazione esistente continua a funzionare finché non la modifichi. Rimuovere l'header fa passare quelle richieste alle forme documentate in questa pagina:

Per migrare:

1. Rimuovi l'header beta. Elimina anthropic-beta: skills-2025-10-02 dalle tue richieste. Negli SDK, chiama client.skills invece di client.beta.skills; mantenere client.beta.skills funziona solo sulle versioni degli SDK che non inviano più l'header. Le versioni precedenti lo inviano da client.beta.skills anche senza argomento betas.
2. Rinomina i campi nel tuo codice: display_title in display_name, latest_version in latest_version_id, e leggi source.type invece di confrontare source con una stringa.
3. Usa gli ID di versione. Ovunque tu abbia memorizzato una versione in microsecondi epoch, memorizza invece l'id della versione, oppure usa latest. I riferimenti alle Skills nelle richieste Messages accettano un ID di versione, latest o (per le Skills di Anthropic) la versione del catalogo.
4. Rivedi le chiamate di eliminazione. DELETE /v1/skills/{skill_id} ora rimuove ogni versione insieme alla Skill. Se facevi affidamento sul rifiuto della beta come salvaguardia, aggiungi un tuo controllo.

Una Skill le cui versioni sono state tutte eliminate durante la beta non ha una versione corrente da restituire: GET /v1/skills/{skill_id} restituisce un errore 400 e la Skill viene omessa dalle risposte di elenco finché non vi carichi una versione. Puoi comunque eliminarla.

Namespace beta degli SDK

A partire da 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 e C# SDK 12.44.0, client.beta.skills non invia più skills-2025-10-02 e restituisce le stesse forme di client.skills, con nomi di tipo con prefisso Beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Accetta un argomento betas per le funzionalità delle Skills ancora in beta. Nei tipi beta di Messages, il tipo di riferimento alla Skill del container è rinominato da BetaSkill a BetaContainerSkill (stessi campi: type, skill_id, version); BetaSkill ora indica la risorsa Skill, in corrispondenza con Skill e ContainerSkill nei tipi non beta. Le versioni precedenti degli SDK sono tipizzate sulle forme beta; se dipendi da quei tipi, resta su una versione precedente finché non migri.

Conservazione dei dati

Le Agent Skills non sono coperte dagli accordi ZDR. Le definizioni delle Skills e i dati di esecuzione vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.

Per l'idoneità ZDR di tutte le funzionalità, consulta API e conservazione dei dati.

Registrazione di audit

Se la tua organizzazione ha abilitato la Compliance API, il suo Activity Feed registra la creazione e l'eliminazione di Skills e versioni di Skills effettuate con una chiave API di Claude o dalla Claude Console. Le operazioni che avvengono mentre la Compliance API è disattivata non vengono registrate e non possono essere recuperate in seguito, quindi configura la Compliance API prima di fare affidamento su questa traccia di audit.

Passaggi successivi