Utilizzo di Agent Skills con l'API

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 incluso schemi di richiesta/risposta e tutti i parametri, vedi:

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

Quick Links

Inizia con Agent Skills

Crea la tua prima Skill

Crea Custom Skills

Best practice 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.

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:

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`
Gestione	Pre-costruite e mantenute da Anthropic	Carica e gestisci tramite Skills API
Disponibilità	Disponibile a tutti gli utenti	Privata 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:

Chiave API Anthropic dalla Console
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
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.beta.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:

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

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.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: 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}")

Operazioni aggiuntive dell’API Files:

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

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

Conversazioni Multi-Turn

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

# First request creates container
response1 = client.beta.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"}]
)

# 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-sonnet-4-5-20250929",
    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 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.beta.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"}]
)

# 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-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 una guida aggiuntiva.

Utilizzo di Più Skills

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

response = client.beta.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()

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

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 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:

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

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

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

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

# Use latest version
response = client.beta.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:

Metadata Discovery: Claude vede i metadati per ogni Skill (nome, descrizione) nel system prompt
File Loading: I file 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 uso efficiente del contesto—Claude carica solo le istruzioni complete di Skill quando necessario.

Casi d’Uso

Organizational Skills

Brand & Communications

Applica 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 note con formati specifici dell’azienda (OKRs, decision log)
Genera attività seguendo le convenzioni del team
Crea recap 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 deployment

Esempio: Financial Modeling

Combina Excel e custom DCF analysis Skills:

# 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-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)
Requisiti del 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 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 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:

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

Per lo sviluppo:

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

Considerazioni sul Prompt Caching

Quando utilizzi il prompt caching, nota che cambiare l’elenco di Skills nel tuo container interromperà la cache:

# First request creates cache
response1 = client.beta.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"}]
)

# Adding/removing Skills breaks cache
response2 = client.beta.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.beta.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}")
        # Handle skill-specific errors
    else:
        raise

Prossimi Passi

Riferimento API

Riferimento API completo con tutti gli endpoint

Guida di Authoring

Best practice per la scrittura di Skills efficaci

Strumento di Esecuzione del Codice

Scopri l’ambiente di esecuzione del codice

Primi passi

Modelli e prezzi

Crea con Claude

Capacità

Strumenti

Competenze Agente

Agent SDK

MCP nell'API

Claude su piattaforme di terze parti

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Amministrazione e monitoraggio

​Quick Links

Inizia con Agent Skills

Crea Custom Skills

​Overview

​Utilizzo di Skills

​Prerequisiti

​Utilizzo di Skills in Messages

​Parametro Container

​Download dei File Generati

​Conversazioni Multi-Turn

​Operazioni a Lunga Durata

​Utilizzo di Più Skills

​Gestione di Custom Skills

​Creazione di una Skill

​Elenco di Skills

​Recupero di una Skill

​Eliminazione di una Skill

​Versioning

​Come Vengono Caricate le Skills

​Casi d’Uso

​Organizational Skills

​Personal Skills

​Esempio: Financial Modeling

​Limiti e Vincoli

​Limiti di Richiesta

​Vincoli dell’Ambiente

​Best Practices

​Quando Utilizzare Più Skills

​Strategia di Gestione delle Versioni

​Considerazioni sul Prompt Caching

​Gestione degli Errori

​Prossimi Passi

Riferimento API

Guida di Authoring

Strumento di Esecuzione del Codice

Quick Links

Overview

Utilizzo di Skills

Prerequisiti

Utilizzo di Skills in Messages

Parametro Container

Download dei File Generati

Conversazioni Multi-Turn

Operazioni a Lunga Durata

Utilizzo di Più Skills

Gestione di Custom Skills

Creazione di una Skill

Elenco di Skills

Recupero di una Skill

Eliminazione di una Skill

Versioning

Come Vengono Caricate le Skills

Casi d’Uso

Organizational Skills

Personal Skills

Esempio: Financial Modeling

Limiti e Vincoli

Limiti di Richiesta

Vincoli dell’Ambiente

Best Practices

Quando Utilizzare Più Skills

Strategia di Gestione delle Versioni

Considerazioni sul Prompt Caching

Gestione degli Errori

Prossimi Passi