Agent Skills estendono le capacità di Claude attraverso cartelle organizzate di istruzioni, script e risorse. Questa guida ti mostra come utilizzare sia Skills pre-costruite che personalizzate con l’API Claude.
Per il riferimento API completo inclusi schemi di richiesta/risposta e tutti i parametri, vedi:

Inizia con Agent Skills

Crea la tua prima Skill

Crea Custom Skills

Best practices per l’authoring 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.

​
Utilizzo di Skills

Skills si integrano in modo identico nell’API Messages indipendentemente dalla fonte. Specifichi Skills nel parametro container con un skill_id, type e opzionalmente version, e vengono eseguiti nell’ambiente di esecuzione del codice. Puoi utilizzare Skills da due fonti:
AspettoAnthropic SkillsCustom Skills
Valore Typeanthropiccustom
Skill IDsNomi brevi: pptx, xlsx, docx, pdfGenerati: skill_01AbCdEfGhIjKlMnOpQrStUv
Formato versioneBasato su data: 20251013 o latestTimestamp epoch: 1759178010641129 o latest
GestionePre-costruite e mantenute da AnthropicCarica e gestisci tramite Skills API
DisponibilitàDisponibili a tutti gli utentiPrivate al tuo workspace
Entrambe le fonti di skill vengono 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.

​
Prerequisiti

Per utilizzare Skills, hai bisogno di:
  1. Chiave API Anthropic dalla Console
  2. Header Beta:
    • 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
  3. Strumento di esecuzione del codice abilitato nelle tue richieste

​
Utilizzo di Skills in Messages

​
Parametro Container

Skills vengono 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: 
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 Skills creano documenti (Excel, PowerPoint, PDF, Word), restituiscono attributi file_id nella risposta. Devi utilizzare l’API Files per scaricare questi file. Come funziona:
  1. Skills creano file durante l’esecuzione del codice
  2. La risposta include file_id per ogni file creato
  3. Usa l’API Files per scaricare il contenuto effettivo del file
  4. Salva localmente o elabora come necessario
Esempio: Creazione e download di un file Excel 
import anthropic

client = anthropic.Anthropic()

# Step 1: Usa una Skill per creare un file
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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: Estrai gli ID 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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Scarica il file usando l'API Files
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: Salva su disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")
Operazioni aggiuntive dell’API Files: 
# Ottieni i metadati del file
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")

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

# Elimina un file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
Per i dettagli completi sull’API Files, vedi la documentazione dell’API Files.

​
Conversazioni Multi-Turn

Riutilizza lo stesso container in più messaggi specificando l’ID del container: 
# La prima richiesta crea il container
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Continua la conversazione con lo stesso container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Riutilizza il container
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

​
Operazioni a Lunga Durata

Skills possono eseguire operazioni che richiedono più turni. Gestisci i motivi di arresto pause_turn: 
messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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"}]
    )
La risposta può includere un motivo di arresto pause_turn, che indica che l’API ha messo in pausa un’operazione Skill a 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.

​
Utilizzo di Più Skills

Combina più Skills in una singola richiesta per gestire flussi di lavoro complessi: 
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 di Custom Skills

​
Creazione di una Skill

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

client = anthropic.Anthropic()

# Opzione 1: Usando l'helper files_from_dir (solo Python, consigliato)
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"]
)

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

# Opzione 3: Usando tuple di file (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}")
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
  • Frontmatter YAML: name (massimo 64 caratteri), description (massimo 1024 caratteri)
Per gli schemi completi di richiesta/risposta, vedi il riferimento API Create Skill.

​
Elenco di Skills

Recupera tutte le Skills disponibili nel tuo workspace, incluse sia le Skills pre-costruite di Anthropic che le tue Skills personalizzate. Usa il parametro source per filtrare per tipo di skill: 
# Elenca tutte le 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})")

# Elenca solo le Custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)
Vedi il riferimento API List Skills per le opzioni di paginazione e filtro.

​
Recupero di una Skill

Ottieni i dettagli su una Skill specifica: 
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}")

​
Eliminazione di una Skill

Per eliminare una Skill, devi prima eliminare tutte le sue versioni: 
# Step 1: Elimina tutte le versioni
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: Elimina la Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
Il tentativo di eliminare una Skill con versioni esistenti restituirà un errore 400.

​
Versioning

Skills supportano il versioning per gestire gli aggiornamenti in modo sicuro: Anthropic-Managed Skills:
  • 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 Skill
# 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)
Vedi il riferimento API Create Skill Version per i dettagli completi.

​
Come Vengono Caricate le Skills

Quando specifichi Skills 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 Skill vengono copiati nel container in /skills/{directory}/
  3. Uso Automatico: Claude carica e utilizza automaticamente le Skills quando rilevante per la tua richiesta
  4. Composizione: Più Skills si compongono insieme per flussi di lavoro complessi
L’architettura di divulgazione progressiva assicura un utilizzo efficiente del contesto—Claude carica solo le istruzioni complete di Skill quando necessario.

​
Casi d’Uso

​
Organizational Skills

Brand & Communications
  • Applica la formattazione specifica dell’azienda (colori, font, layout) ai documenti
  • Genera comunicazioni seguendo i template organizzativi
  • Assicura linee guida di brand coerenti in tutti gli output
Project Management
  • Struttura le note con formati specifici dell’azienda (OKRs, decision log)
  • 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 documento 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 dell’industria
Development & Automation
  • Template di generazione del codice
  • Framework di test
  • Flussi di lavoro di distribuzione

​
Esempio: Financial Modeling

Combina Excel e custom DCF analysis Skills: 
# Crea 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"]
)

# Usa con Excel per creare un modello finanziario
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

​
Limiti e Vincoli

​
Limiti di Richiesta

  • Massimo Skills per richiesta: 8
  • Dimensione massima caricamento Skill: 8MB (tutti i file combinati)
  • Limiti frontmatter YAML: name 64 caratteri, description 1024 caratteri

​
Vincoli dell’Ambiente

Le Skills vengono eseguite nel container di esecuzione del codice con questi limiti:
  • Nessun accesso di rete - Non può effettuare chiamate API esterne
  • Nessuna installazione di pacchetti runtime - Solo pacchetti pre-installati disponibili
  • Ambiente isolato - Ogni richiesta ottiene un container fresco
Vedi la documentazione dello strumento di esecuzione del codice 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 dei dati (Excel) + creazione di presentazioni (PowerPoint)
  • Generazione di report (Word) + esportazione in PDF
  • Logica di dominio personalizzata + generazione di documenti
Evita:
  • Includere Skills inutilizzate (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 di Skills nel tuo container romperà la cache: 
# La prima richiesta crea la cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 rompe la cache
response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)
Per le migliori prestazioni di caching, mantieni il tuo elenco di Skills coerente tra le richieste.

​
Gestione degli Errori

Gestisci gli errori correlati alle Skills con eleganza: 
try:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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

​
Prossimi Passi

API Reference

Riferimento API completo con tutti gli endpoint

Authoring Guide

Best practices per scrivere Skills efficaci

Code Execution Tool

Scopri l’ambiente di esecuzione del codice