Skill Claude API

La skill claude-api è una Agent Skill open-source che fornisce a Claude materiale di riferimento dettagliato e aggiornato per creare applicazioni su due superfici Anthropic:

• Messages API: La superficie principale per richieste singole, chat in streaming, "tool use" (uso degli strumenti), elaborazione batch, "prompt caching" (cache dei prompt), output strutturati e loop di agenti personalizzati.
• Claude Managed Agents (beta): Una superficie ospitata da Anthropic per agenti stateful gestiti lato server, con esecuzione degli strumenti ospitata da Anthropic, configurazioni degli agenti persistenti e sandbox per sessione.

Copre otto linguaggi di programmazione sia per la Messages API sia per Managed Agents: Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL.

La skill è inclusa in Claude Code ed è disponibile anche nel repository open-source delle skill di Anthropic, da cui puoi installarla in qualsiasi ambiente che supporti le Agent Skills.

La skill usa la "progressive disclosure" (divulgazione progressiva) per mantenere efficiente il contesto: Claude carica solo la documentazione pertinente al linguaggio del tuo progetto, alla superficie (Messages API o Managed Agents) e all'attività specifica in corso (uso degli strumenti, streaming, batch e così via), invece di caricare tutto in una volta.

Cosa fornisce la skill

Quando viene attivata, la skill fornisce a Claude:

Per la Messages API:

• Documentazione degli SDK specifica per linguaggio: installazione, avvio rapido, pattern comuni e gestione degli errori per il linguaggio del tuo progetto
• Indicazioni sull'uso degli strumenti: esempi specifici per linguaggio e fondamenti concettuali per il "function calling" (chiamata di funzioni), incluso il tool runner beta dove disponibile
• Pattern di streaming: dettagli di implementazione per creare interfacce di chat e gestire la visualizzazione incrementale
• Elaborazione batch: elaborazione batch offline al 50% del costo
• Cache dei prompt: progettazione per la stabilità del prefisso, posizionamento dei breakpoint e verifica degli invalidatori silenziosi
• Migrazione dei modelli: Indicazioni passo passo per migrare a modelli Claude più recenti (incluse le modifiche incompatibili e i cambiamenti di comportamento su Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, e Claude Fable 5.1)
• Migrazione al ragionamento preservato: Individuazione, misurazione e correzione delle modifiche alla cronologia che invalidano i blocchi thinking, disponibile tramite il sottocomando /claude-api preserved-thinking-migration
• Informazioni sui modelli attuali: ID dei modelli, dimensioni della "context window" (finestra di contesto) e prezzi
• Errori comuni: indicazioni dettagliate per evitare gli errori frequenti durante l'integrazione con l'API

Per Managed Agents (beta):

• Flusso di onboarding: Una procedura guidata basata su un'intervista per configurare un nuovo Managed Agent da zero, disponibile tramite il sottocomando /claude-api managed-agents-onboard
• Documentazione Managed Agents specifica per linguaggio: Creazione di agenti persistenti, avvio di sessioni, streaming di eventi e gestione delle conferme degli strumenti per Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL
• Pattern client: Riconnessione dello stream senza perdite, gate queued/processed basato su processed_at, gestione delle interruzioni, insidie del montaggio dei file e gestione delle credenziali
• Vincoli di deployment: Managed Agents è disponibile solo sulla Claude API e su Claude Platform on AWS (non su Amazon Bedrock, Google Cloud o Microsoft Foundry). La skill indirizza gli altri deployment verso la Messages API e l'uso degli strumenti.

Quando si attiva la skill

La skill si attiva in due modi:

L'attivazione automatica avviene quando:

• Il tuo codice importa un SDK Anthropic (anthropic per Python, @anthropic-ai/sdk per TypeScript/JavaScript)
• Chiedi a Claude di aiutarti a creare, eseguire il debug o ottimizzare qualcosa con la Claude API, un SDK Anthropic o Managed Agents
• Aggiungi, modifichi o regoli una funzionalità di Claude in un file (cache dei prompt, ragionamento adattivo, compattazione, uso degli strumenti, batch, file, citazioni, memoria) o un riferimento a un modello

L'invocazione manuale avviene digitando /claude-api (con un sottocomando o testo libero opzionale) in qualsiasi ambiente in cui la skill è installata.

La skill non si attiva per attività di programmazione generiche, lavoro di ML/data science o codice che importa altri SDK di IA (come OpenAI).

Linguaggi supportati

La skill rileva automaticamente il linguaggio del tuo progetto esaminando i file del progetto (ad esempio, requirements.txt per Python, tsconfig.json per TypeScript, go.mod per Go) e carica la documentazione appropriata.

Se il tuo progetto usa più linguaggi, Claude chiede quale si applica. Per i linguaggi non supportati (Rust, Swift, C++), la skill fornisce esempi cURL/HTTP raw.

Come usare la skill

In Claude Code (inclusa)

La skill è distribuita con Claude Code e non richiede installazione. Quando chiedi a Claude di aiutarti a creare qualcosa con la Claude API, o quando il tuo progetto importa già un SDK Anthropic, la skill si attiva automaticamente.

Puoi anche invocarla direttamente:

Per saperne di più su come funzionano le skill incluse in Claude Code, consulta la documentazione delle skill di Claude Code.

Dal repository delle skill

Il codice sorgente della skill è disponibile nel repository delle skill di Anthropic. Puoi installarla usando il comando npx:

npx skills add https://github.com/anthropics/skills --skill claude-api

Oppure chiedi a Claude Code di installarla come plugin di Claude Code:

/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills

Migrare a un modello Claude più recente

La skill Claude API può eseguire migrazioni di modelli Claude su un'intera base di codice. Invocala direttamente con /claude-api migrate:

Puoi anche passare subito un ambito specifico per saltare la domanda di conferma dell'ambito:

Quando l'ambito è ambiguo (ad esempio, un semplice /claude-api migrate to claude-opus-5-5), la skill ti chiede di scegliere tra l'intera directory di lavoro, una sottodirectory specifica o un elenco esplicito di file prima di modificare qualsiasi file. Questo vale sia per i chiamanti della Messages API sia per quelli di Managed Agents.

La skill gestisce:

• Sostituzione degli ID dei modelli, incluse le costanti tipizzate degli SDK (Model.CLAUDE_OPUS_4_8 → Model.CLAUDE_OPUS_5_5) in tutti i linguaggi supportati, classificando ogni file come chiamante, definitore del modello o riferimento a stringa opaca prima di modificarlo
• Rilevamento della piattaforma cloud, preservando i formati degli ID dei modelli specifici della piattaforma (ad esempio, il prefisso anthropic. su Amazon Bedrock) e saltando le modifiche per le funzionalità non disponibili sulle piattaforme gestite dai partner
• Modifiche incompatibili ai parametri, come la rimozione di temperature, top_p e top_k per Claude Opus 4.8 e Claude Opus 4.7, e la conversione di thinking: {type: "enabled", budget_tokens: N} in thinking: {type: "adaptive"}
• Sostituzione del prefill, convertendo i pattern di prefill dei messaggi dell'assistente in output strutturati dove applicabile
• Pulizia degli header beta, rimuovendo gli header beta non richiesti dal modello di destinazione (ad esempio, effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14) e tornando da client.beta.messages.create() a client.messages.create()
• Calibrazione dell'effort, raccomandando un valore iniziale di output_config.effort per il modello di destinazione (ad esempio, il valore predefinito high su Claude Opus 5, e xhigh per i casi d'uso di programmazione e agentici su Claude Opus 4.8 e Claude Opus 4.7)
• Regolazione del comportamento dei prompt, segnalando i prompt relativi al controllo della lunghezza, all'attivazione degli strumenti, ai subagenti e al rispetto delle istruzioni che potrebbero comportarsi diversamente sul modello di destinazione
• Gestione dei valori predefiniti silenziosi, riattivando il riepilogo del ragionamento (thinking.display: "summarized") quando il ragionamento viene mostrato agli utenti su Claude Opus 4.8 e Claude Opus 4.7
• Configurazione del fallback in caso di rifiuto, aggiungendo la gestione di stop_reason: "refusal" prima di leggere il contenuto della risposta e configurando un percorso di nuovo tentativo di fallback quando la destinazione è Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 o Claude Sonnet 5.5 (il parametro lato server fallbacks, tipicamente nella sua modalità "default", il middleware di fallback in caso di rifiuto dell'SDK o un nuovo tentativo con credito di fallback), e aggiornando il codice di fallback scritto per forme di anteprima precedenti

Durante le modifiche, la skill spiega inline ogni cambiamento e la sua motivazione. Al termine, produce una checklist di elementi che richiedono verifica manuale (tipicamente test di integrazione, regolazione dei prompt di controllo della lunghezza e ridefinizione delle baseline di costo e "rate limit" (limite di velocità)).

Per l'elenco completo delle modifiche specifiche per modello applicate dalla skill, consulta Migrazione a Claude Opus 5.5 da Claude Opus 5, Migrazione a Claude Opus 5.5 da Claude Opus 4.8, Migrazione a Claude Sonnet 5.5 da Claude Sonnet 5, guida alla migrazione a Claude Haiku 5.5, e guida alla migrazione a Claude Fable 5.1 e Claude Mythos 5.1.

Verificare un'integrazione per il ragionamento preservato

Il ragionamento preservato mantiene valido un blocco thinking solo finché il prompt system, i tools e i messaggi che lo precedono rimangono invariati. Per trovare e correggere i punti in cui il tuo codice modifica quella cronologia, apri il repository che costruisce le tue richieste e invoca il sottocomando preserved-thinking-migration:

La skill procede in cinque passaggi:

1. Ambito: Verifica se la tua integrazione è interessata, quindi invia tre richieste di test per confermare che l'API segnali una modifica intenzionale.
2. Individuazione: Acquisisce alcune delle tue sessioni multi-turno, confronta le richieste consecutive ed elenca ogni punto in cui il tuo codice modifica il prefisso.
3. Misurazione: Riproduce le sessioni con "drop_block" e riporta quali conversazioni perdono blocchi thinking, a quale turno e perché.
4. Correzione: Sostituisce una modifica alla volta con il pattern corrispondente in Apportare modifiche senza modificare il prefisso, e misura di nuovo dopo ogni cambiamento.
5. Report: Riepiloga ogni causa, la modifica apportata per essa e i conteggi prima e dopo.

Se il tuo progetto dispone di una valutazione, la skill confronta anche i punteggi e l'utilizzo dei token con e senza i blocchi thinking scartati.

Le richieste di test e le riproduzioni sono vere richieste alla Messages API, fatturate alle tariffe normali del modello. Ogni riproduzione richiede solo pochi token di output e imposta tool_choice su none, quindi nessuno strumento viene eseguito. La skill indica il costo e chiede la tua approvazione prima di inviarle.

Configurare un Managed Agent

Per creare lo scaffolding di un nuovo Managed Agent da zero, invoca il sottocomando managed-agents-onboard:

La skill conduce un'intervista che ti guida attraverso il modello mentale di Managed Agents (configurazioni degli Agent rispetto alle Session), crea un template di configurazione dell'agente, configura ambienti e strumenti, imposta il loop della sessione e genera codice eseguibile per il tuo linguaggio. La skill copre anche il flusso obbligatorio Agent (una volta) → Session (ogni esecuzione): model, system e tools risiedono sull'agente, mai sulla sessione, e gli agenti dovrebbero essere creati una sola volta e referenziati tramite ID.

Managed Agents richiede l'header beta managed-agents-2026-04-01, che l'SDK imposta automaticamente per tutte le chiamate client.beta.agents.*, client.beta.environments.*, client.beta.sessions.* e client.beta.vaults.*.

Esempi di utilizzo

Ecco alcuni esempi di attività che la skill aiuta Claude a gestire:

Creare un'applicazione di chat:

Migrare un progetto esistente:

Onboarding di un nuovo Managed Agent:

In ogni caso, la skill carica la documentazione specifica per linguaggio pertinente e guida Claude nell'implementazione usando i pattern API attuali e le best practice.

Prossimi passi