Utilizzo degli Agent Skills con l'API

Gli Agent Skills estendono le capacità di Claude attraverso cartelle organizzate di istruzioni, script e risorse. Questa guida mostra come utilizzare sia gli Skill predefiniti che quelli personalizzati con l'API di Claude.



Link rapidi



Panoramica

Gli Skill si integrano con la Messages API attraverso lo strumento di esecuzione del codice. Che si utilizzino Skill predefiniti gestiti da Anthropic o Skill personalizzati che hai caricato, la forma dell'integrazione è identica: entrambi richiedono l'esecuzione del codice e utilizzano la stessa struttura container.



Utilizzo degli Skill

Gli Skill si integrano in modo identico nella Messages API indipendentemente dalla fonte. Specifichi gli Skill nel parametro container con uno skill_id, un type e una version opzionale, e vengono eseguiti nell'ambiente di esecuzione del codice.

Puoi utilizzare Skill da due fonti:

Entrambe le fonti 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 gli Skill e come vengono gestiti.



Prerequisiti

Per utilizzare gli Skill, hai bisogno di:

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

Gli Skill sono generalmente disponibili sull'API di Claude e non richiedono un header anthropic-beta, né per la Skills API né per container.skills nelle richieste Messages. Gli esempi in questa guida inviano comunque l'header beta skills-2025-10-02 (più code-execution-2025-08-25 nelle richieste Messages) e utilizzano il namespace beta degli SDK. Entrambi gli header rimangono opt-in validi, quindi gli esempi funzionano così come sono scritti, e puoi ometterli nelle tue richieste.

Gli Skill richiedono lo strumento di esecuzione del codice, quindi utilizza un modello dalla sua lista di compatibilità dei modelli.



Utilizzo degli Skill in Messages



Parametro container

Gli Skill vengono specificati utilizzando il parametro container nella Messages API. Puoi includere fino a 20 Skill per ogni richiesta.

La struttura è identica sia per gli Skill Anthropic che per quelli personalizzati. Specifica i campi obbligatori type e skill_id, e includi opzionalmente version per fissare una versione specifica:

client = anthropic.Anthropic()

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



Download dei file generati

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

Come funziona:

1. Gli Skill 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 localmente o elabora secondo necessità.

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

Esempio: creazione e download di un file Excel

client = anthropic.Anthropic()

# Passaggio 1: usa una Skill per creare un file
response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
)


# 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 che contiene 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.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.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.beta.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.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Elimina un file
client.beta.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 su più messaggi specificando l'ID del container:

client = anthropic.Anthropic()

# La prima richiesta crea il container
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 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 il testo dell'assistente; container.id mantiene 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.beta.messages.create(
    model="claude-opus-5",
    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"}],
)



Operazioni di lunga durata

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

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

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

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



Utilizzo di più Skill

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

client = anthropic.Anthropic()

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



Gestione degli Skill personalizzati



Creazione di uno Skill

Un bundle 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 gli Agent Skills nell'API per crearne uno, e l'elenco Requisiti che segue gli esempi per i vincoli completi.

Carica il tuo Skill personalizzato per renderlo 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 un percorso di directory.

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

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

---
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: quando omesso, deriva 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.



Elenco degli Skill

Recupera tutti gli Skill disponibili nel tuo workspace, inclusi sia gli Skill predefiniti di Anthropic che i tuoi Skill personalizzati. Usa il parametro source per filtrare per tipo di skill:

# Elenca tutte le Skill
ant beta:skills list

# Elenca solo le Skill personalizzate
ant beta:skills list --source custom

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



Recupero di uno Skill

Ottieni i dettagli su uno Skill specifico:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv



Eliminazione di uno Skill

L'eliminazione di uno Skill rimuove anche tutte le sue versioni. La cascata è un comportamento solo GA, quindi a differenza degli altri esempi in questa guida, questi chiamano direttamente la superficie GA anziché il namespace beta.

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



Versionamento

Gli Skill supportano il versionamento per gestire gli aggiornamenti in modo sicuro:

Skill Anthropic:

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

Skill personalizzati:

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

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

# Crea una nuova versione
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Usa una versione specifica
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usa la versione più recente
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

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



Come vengono caricati gli Skill

Quando specifichi gli Skill in un container:

1. Scoperta dei metadati: Claude vede i metadati per ogni Skill (nome, descrizione) nel prompt di sistema.
2. Caricamento dei file: I file dello Skill vengono copiati nel container in /skills/{skill-name}/. La directory è il nome dello Skill (pptx per uno Skill Anthropic, il name di SKILL.md per uno Skill personalizzato), non il suo ID skill_01....
3. Utilizzo automatico: Claude carica e utilizza automaticamente gli Skill quando sono rilevanti per la tua richiesta.
4. Composizione: Più Skill si compongono insieme per flussi di lavoro complessi.

Claude carica le istruzioni complete dello Skill solo quando necessario.



Casi d'uso

Gli Skill si adattano sia al lavoro organizzativo che personale. Le organizzazioni li utilizzano per applicare la formattazione del brand ai documenti, strutturare note e report attorno ai template aziendali ed eseguire procedure analitiche specifiche dell'azienda. Gli individui li utilizzano per template di documenti personalizzati, pipeline di dati specializzate e convenzioni di generazione o deployment del codice.



Esempio: modellazione finanziaria

Combina gli Skill Excel e di analisi DCF personalizzata:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Crea una Skill personalizzata per l'analisi DCF

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

# Usa con Excel per creare un modello finanziario
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)



Limiti e vincoli



Limiti delle richieste

• Numero massimo di Skill per richiesta: 20
• Dimensione massima di caricamento dello 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

Gli Skill vengono eseguiti 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 un ID container esistente

Consulta Strumento di esecuzione del codice per i pacchetti disponibili.



Best practice



Quando utilizzare più Skill

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

Casi d'uso validi:

• 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 Skill inutilizzati (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 dello Skill non modifichino mai il comportamento distribuito. Se ometti version o la imposti su "latest", le richieste utilizzano la versione più recente dello Skill, quindi una versione caricata da chiunque nel workspace modifica immediatamente ciò che eseguono i tuoi agenti di produzione. L'ID versione proviene dalla risposta di creazione versione in Versionamento o dalla List Skill Versions API. L'ID è sempre una stringa: racchiudi tra virgolette gli ID timestamp epoch in JSON o YAML.

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

Per lo sviluppo: usa latest per acquisire 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 utilizzi la cache dei prompt, modificare l'elenco degli Skill nel tuo container invalida la cache. Gli Skill vengono renderizzati nel prompt di sistema in un ordine fisso, quindi lo stesso elenco produce lo stesso prefisso memorizzabile in cache:

client = anthropic.Anthropic()

# Le Skill vengono renderizzate nel prompt di sistema in un ordine fisso e compatibile con la cache
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Modificare l'elenco delle Skill ([xlsx] vs [xlsx, pptx]) cambia il prefisso: un cache miss, mentre un elenco identico è un cache hit
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # 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 il tuo elenco di Skill, incluso il suo ordine, coerente tra le richieste. Anche fissare le versioni degli Skill personalizzati aiuta: con "latest", la pubblicazione di una nuova versione può invalidare il prefisso memorizzato in cache se modifica la descrizione dello Skill.



Gestione degli errori

Gestisci gli errori relativi agli Skill in modo elegante:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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 gli errori specifici della skill
    else:
        raise



Conservazione dei dati

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

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



Registrazione di audit

Se la tua organizzazione ha la Compliance API abilitata, il suo Activity Feed registra la creazione e l'eliminazione di Skill e versioni di Skill 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