Claude Skills API: cosa cambia con la GA e come usarla

Dal 20 agosto 2026, Skills API, computer use e Files API di Anthropic sono ufficialmente in general availability. Spariscono gli header beta, computer use può eseguire più azioni nello stesso turno e arriva un nuovo strumento per il browser. La GA, però, non risolve un limite fondamentale: una skill parte solo se Claude decide di richiamarla. Version pinning e progettazione dell'attivazione restano quindi responsabilità di chi integra l'API.

Cosa è cambiato davvero con la GA del 20 agosto

Le integrazioni beta già esistenti continueranno a funzionare durante la migrazione. Nel suo post di lancio, Anthropic riunisce però una serie di novità concrete:

• Addio agli header beta. L'attuale guida alle skills indica soltanto due requisiti: una Claude API key e l'esecuzione del codice abilitata nella richiesta. Gli header beta richiesti dai tutorial pre-GA non compaiono più nella documentazione.
• Più azioni per turno. Lo strumento aggiornato di computer use esegue varie azioni per chiamata del modello — clic, digitazione, pressione di tasti e screenshot — anziché una sola. L'account @ClaudeDevs riporta che i clienti dell'accesso anticipato hanno ottenuto il 20–40% in meno di round trip per attività.
• Uno strumento dedicato al browser. Combina screenshot e struttura della pagina, così l'agente può puntare a un campo o a un pulsante specifico invece di affidarsi alle coordinate dei pixel. È pensato per portali web come quelli per l'invio di pratiche assicurative.
• Files API più ampia. 1 TB di archiviazione per organizzazione, limiti di frequenza 5 volte più alti (500 RPM secondo il thread di @ClaudeDevs) e scadenza automatica dei file.
• Un percorso per la compliance. Computer use è ora idoneo ai carichi di lavoro regolamentati da HIPAA nell'ambito del BAA di Anthropic.
• Disponibilità cloud. Skills API e Files API sono disponibili anche tramite Microsoft Foundry; gli strumenti aggiornati di computer use e browser use sono indicati come "coming soon" su Vertex AI, senza una data.

Files API, Skills API e computer use: il flusso completo

L'esempio di Anthropic dedicato a un agente per i sinistri mostra il ciclo dall'inizio alla fine: recupera un documento di apertura pratica tramite file ID (Files API), applica una skill con la procedura di invio (Skills API), completa il portale dell'assicuratore con browser use (computer use), quindi salva nuovamente la conferma come file. I documenti si caricano una sola volta e vengono poi richiamati tramite file_id, senza doverli inviare a ogni richiesta.

I due set di numeri diffusi con il lancio provengono dai fornitori. Nel post di lancio, il research engineer Davide Locatelli ha riferito che il workflow per sinistri più lungo è passato da 32 minuti a 13 minuti, con completamento al 100%; separatamente, David Mlčoch, cofondatore di Asteroid, ha testato durante l'accesso anticipato flussi healthcare basati su computer use:

"32-52% fewer model calls, 25-32% lower cost per task, 100% completion on every workflow, up from 77%" — @MlcochDavid

Come richiamare Claude Skills API dalla Messages API

Per collegare una skill basta un parametro: un oggetto container nella richiesta alla Messages API, contenente un array skills. Ogni elemento include un type (anthropic o custom), un skill_id e una version facoltativa.

Secondo la guida ufficiale alle skills, intorno a quel parametro ci sono alcune regole operative:

• L'esecuzione del codice deve essere abilitata e supportata dal modello; gli esempi della guida usano claude-opus-5 con il tool type code_execution_20250825 e max_tokens=4096.
• Una singola richiesta può includere fino a 20 skills.
• Le skill vengono eseguite nel sandbox di code execution di Anthropic: niente accesso alla rete, nessuna installazione di pacchetti a runtime e un container nuovo per ogni richiesta, salvo riutilizzare tra i turni il valore container.id restituito. Ogni risposta include expires_at.
• Non è necessario ospitare i file delle skill: Anthropic li esegue nel container.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=[{"type": "code_execution_20250825"}],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "20251013"},
            {"type": "custom", "skill_id": "skill_01...", "version": "skver_01..."},
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue summary"}],
)

Per i documenti in input il percorso è inverso: prima vanno caricati tramite Files API, poi referenziati in un blocco di upload del container. La richiesta mantiene la struttura standard della Anthropic Messages API, quindi funziona sia con una chiave diretta sia con un relay compatibile con Anthropic come la Claude API di AIReiter.

Le skill integrate usano ID brevi e leggibili — pptx, xlsx, docx, pdf — e versioni in formato data, come 20251013 o latest. Le skill personalizzate ricevono invece ID skill_01..., circoscritti al proprio workspace.

Pubblicare una custom Skill: le regole che bloccano l'upload

Una skill personalizzata è una directory il cui file SKILL.md di primo livello contiene YAML frontmatter (name e description), con eventuali script e file di riferimento nella stessa directory. Il file minimo può essere fatto così:

---
name: eu-claims-filing
description: Use when filing or amending EU insurance claims. Loads the
  carrier-specific submission procedure, required fields, and rejection
  codes before filling any portal form.
---

# EU claims filing procedure
1. Pull the intake document by file_id ...

Il caricamento può avvenire con un archivio ZIP o con file singoli — il Python SDK mette a disposizione files_from_dir — e Anthropic applica limiti rigidi prima ancora che la skill venga eseguita. Sono tutti riportati nella guida alle skills:

La gestione passa dalla CLI ant o dagli endpoint API sottostanti, come indicato nella stessa guida. Ecco il percorso dal file alla versione fissata:

ant skills create ./eu-claims-filing   # returns skill_01...
ant skills:versions create skill_01...  # returns skver_01... — pin this in production

Ci sono due comportamenti che spesso sorprendono i team al primo utilizzo: una nuova versione è uno snapshot completo — va ricaricato l'intero set di file e ciò che viene omesso non viene mantenuto — mentre l'eliminazione di una skill cancella tutte le sue versioni.

Checklist per la produzione: versioni, isolamento e cache

In produzione, i problemi più insidiosi sono versioni mutabili, permessi estesi al workspace e cache miss. La guida alle skills è esplicita su tutti e tre.

1. Fissa le versioni. Usando latest, o non indicando affatto la versione, chiunque abbia accesso al workspace può cambiare immediatamente il comportamento dell'agente distribuito caricando una nuova versione. In produzione, fissa gli ID skver_...; conserva latest per lo sviluppo attivo.
2. Considera il workspace come confine del tenant. Ogni API key all'interno di un workspace può leggere, invocare ed eliminare tutte le skill personalizzate presenti: il confine di isolamento è il workspace, non l'utente né la sessione. Le applicazioni multi-tenant dovrebbero usare un workspace per tenant, tenendo presente il limite predefinito di 100 workspace.
3. Mantieni stabile l'elenco delle skill per sfruttare la cache. Cambiare l'elenco delle skill, incluso il loro ordine, modifica il prefisso del system prompt e invalida la prompt cache. Fissare le versioni personalizzate protegge anche quel prefisso, perché una descrizione latest ricaricata lo riscriverebbe. Con fatturazione per token, una lista di skill variabile tra richieste azzera silenziosamente i risparmi dovuti ai cache hit.
4. Gestisci pause_turn. Le skill di lunga durata restituiscono stop_reason: "pause_turn"; per proseguire, reinvia il contenuto restituito in una richiesta successiva, oppure modifica la conversazione per interrompere il flusso.
5. Valuta la retention dei dati. Agent Skills non rientra negli accordi zero-data-retention: definizioni delle skill e dati di esecuzione seguono la policy di retention standard di Anthropic. Con la Compliance API abilitata, l'Activity Feed registra creazione ed eliminazione di skill e versioni delle skill, ma solo dal momento dell'abilitazione in poi.
6. Intercetta gli errori corretti. Racchiudi le chiamate per catturare anthropic.BadRequestError e separa gli errori relativi alle skill dagli altri errori di richiesta non valida.
7. Non allegare skill inutilizzate. La documentazione lo dichiara chiaramente: includere skill non usate ha un impatto sulle prestazioni.

Il problema dell'attivazione che nessuna modifica API risolve

La GA ha migliorato l'infrastruttura che circonda le skill, non il modo in cui Claude decide di usarle. Un dubbio ricorrente nelle discussioni degli utenti qui sotto è proprio questo: le skill funzionano come procedure attivate in base al contesto, non come un secondo system prompt.

"My problem with Claude Skills is that they are not skills. Nothing forces Claude to actually use them. Claude does whatever it wants... These are just md files." — @Yampeleg, scritto prima della GA; il meccanismo di invocazione non è cambiato

Il thread di r/ClaudeAI sull'effettivo funzionamento delle skill raccoglie le correzioni pratiche più utili:

"userstyle gets prepended every turn but skills only fire when claude decides to invoke based on the description." — u/samxu01

"Skills must have a simple, clear metadata description that also focuses on an action that Claude is doing." — u/Chadum

Da queste discussioni emergono quattro regole:

• Scrivi la descrizione attorno alle frasi trigger e all'azione da compiere, non attorno a una persona.
• Inserisci nel corpo passaggi, controlli, regole e scelte degli strumenti. Il test di u/MartinMystikJonas: "If your skills define steps agent should do, things it should check, rules it should follow and tools it should use then it is useful."
• Codifica ciò che Claude gestisce male in modo nativo, come suggerisce u/Actual_Committee4670.
• Sposta i requisiti sempre attivi nel system prompt o in CLAUDE.md — che viene anteposto a ogni turno, come nota u/samxu01 — e riserva gli hook ai momenti del ciclo di vita, per esempio prima di un commit.

Risposte rapide

Servono ancora gli header beta per Skills API?

No. Dalla GA del 20 agosto 2026, i requisiti sono una Claude API key e l'esecuzione del codice abilitata; nella documentazione attuale non è richiesto alcun header beta.

Le skill consumano la context window?

All'inizio, solo i loro metadati. Secondo la guida alle skills, Claude riceve subito il frontmatter di ogni skill, copia i file nel container e carica le istruzioni complete solo quando l'attività lo richiede. È il motivo per cui la documentazione sconsiglia di allegare skill inutilizzate.

Qual è la differenza tra una Skill e MCP?

Una skill è un pacchetto di istruzioni e script eseguito nel sandbox di Claude senza accesso alla rete; MCP collega Claude a sistemi esterni live. È la distinzione proposta da Anthropic nella sua panoramica sulle skills. Un workflow per sinistri può usare entrambi: un server MCP per il database delle polizze e una skill per la procedura di invio.

Un solo SKILL.md può funzionare in Claude.ai, Claude Code e API?

Il formato SKILL.md è condiviso, ma la distribuzione cambia a seconda della superficie: skill caricate nel workspace per l'API, directory .claude/skills in Claude Code e upload legati al piano nell'app Claude.ai.

Skills API funziona con lo zero data retention?

No: Agent Skills è escluso dagli accordi zero-data-retention; le definizioni delle skill e i dati di esecuzione seguono la policy di retention standard.

Quale meccanismo scegliere per ogni esigenza

La scelta dipende da quando deve avvenire l'invocazione:

Il 20 agosto ha reso il meccanismo delle skill pronto per la produzione; non ha reso intercambiabili le righe di questa tabella.

Approfondimenti correlati: prezzi della Claude API per modello e token e registrare una Claude skill in Claude Code.