Agent Skills

Utilizzo di Agent Skills con l'API

Scopri come utilizzare Agent Skills per estendere le capacità di Claude tramite 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

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:

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

Operazioni aggiuntive dell'API Files:

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:

Operazioni a Lunga Durata

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

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.

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:

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

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:

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:

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:

Prossimi Passi

Riferimento API

Riferimento API completo con tutti gli endpoint

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

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

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

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

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

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

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

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

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

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

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

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

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

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