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 not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 post del 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 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`

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

Download dei file generati

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

Come funziona:

Le Skills creano file durante l'esecuzione del codice
La risposta include file_id per ogni file creato
Utilizza l'API Files per scaricare il contenuto effettivo del file
Salva localmente o elabora secondo le necessità

Esempio: Creazione e download di un file Excel

Operazioni aggiuntive dell'API Files:

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

Conversazioni Multi-Turn

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

Operazioni a Lunga Esecuzione

Le 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 a lunga esecuzione. Puoi fornire la risposta così com'è in una richiesta successiva per permettere a Claude di continuare il suo turno, oppure 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:

Gestione delle Skills Personalizzate

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.

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 30 MB
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 delle Skills

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

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

Recupero di una Skill

Ottieni i dettagli su una Skill specifica:

Eliminazione di una Skill

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

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

Versionamento

Le Skills supportano il versionamento 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à

Skills Personalizzate:

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 Crea Versione Skill per i dettagli completi.

Come Vengono Caricate le Skills

Quando specifichi Skills in un container:

Scoperta dei Metadati: Claude vede i metadati per ogni Skill (nome, descrizione) nel prompt di sistema
Caricamento dei File: I file della Skill vengono copiati nel container in /skills/{directory}/
Uso Automatico: Claude carica e utilizza automaticamente le Skills quando rilevante per la tua richiesta
Composizione: Più Skills si compongono insieme per flussi di lavoro complessi

L'architettura di divulgazione progressiva garantisce un utilizzo efficiente del contesto: Claude carica solo le istruzioni complete della Skill quando necessario.

Casi d'Uso

Skills Organizzative

Brand & Comunicazioni

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

Gestione dei Progetti

Struttura le note con formati specifici dell'azienda (OKR, log delle decisioni)
Genera attività seguendo le convenzioni del team
Crea riepiloghi di riunioni e aggiornamenti di stato standardizzati

Operazioni Aziendali

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

Skills Personali

Creazione di Contenuti

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

Analisi dei Dati

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

Sviluppo & Automazione

Template di generazione del codice
Framework di test
Flussi di lavoro di distribuzione

Esempio: Modellazione Finanziaria

Combina Excel e Skills di analisi DCF personalizzate:

Limiti e Vincoli

Limiti di Richiesta

Numero massimo di Skills per richiesta: 8
Dimensione massima di caricamento Skill: 30 MB (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 Ambientali

Le Skills vengono eseguite nel contenitore di esecuzione del codice 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 contenitore nuovo

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

# 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 sulla Memorizzazione nella Cache dei Prompt

Quando si utilizza la memorizzazione nella cache dei prompt, nota che modificare l'elenco delle Skills nel tuo contenitore interrompe la cache:

Per le migliori prestazioni di caching, mantieni il tuo elenco di Skills coerente tra le richieste.

Gestione degli errori

Gestisci gli errori correlati alle Skill con eleganza:

Conservazione dei dati

Le Skill degli agenti non sono coperte da accordi ZDR. Le definizioni delle Skill e i dati di esecuzione vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.

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

Passaggi successivi

Riferimento API

Riferimento API completo con tutti gli endpoint

Guida alla creazione

Best practice per scrivere Skill efficaci

client = anthropic.Anthropic()

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

client = anthropic.Anthropic()
file_id = "file_abc123"
# 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"])

# La prima richiesta crea il contenitore
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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 contenitore
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-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Riutilizza il contenitore
        "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-7",
    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.beta.messages.create(
        model="claude-opus-4-7",
        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-7",
    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"}],
)

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
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

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

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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-opus-4-7",
    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"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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