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 SDK specifica per linguaggio: Installazione, guida rapida, 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, 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 della 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 e Claude Fable 5.1)
• Informazioni sui modelli attuali: ID dei modelli, dimensioni della "context window" (finestra di contesto) e prezzi
• Errori comuni: Indicazioni dettagliate su come evitare gli errori più frequenti nell'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, pensiero 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:

/claude-api

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

/claude-api migrate this project to claude-opus-5

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

/claude-api migrate everything under src/ to claude-opus-5
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-5

Quando l'ambito è ambiguo (ad esempio, un semplice /claude-api migrate to claude-opus-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:

• Sostituzioni degli ID dei modelli, incluse le costanti tipizzate degli SDK (Model.CLAUDE_OPUS_4_8 → Model.CLAUDE_OPUS_5) in tutti i linguaggi supportati, e classifica ogni file come chiamante, definitore di 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 che il modello di destinazione non richiede (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 punto di partenza per 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 coding e agentici su Claude Opus 4.8 e Claude Opus 4.7)
• Regolazione del comportamento dei prompt, segnalando i prompt di controllo della lunghezza, di attivazione degli strumenti, dei subagenti e di rispetto delle istruzioni che potrebbero comportarsi diversamente sul modello di destinazione
• Gestione dei valori predefiniti silenziosi, riattivando il riepilogo del pensiero (thinking.display: "summarized") quando il ragionamento viene mostrato agli utenti su Claude Opus 4.8 e Claude Opus 4.7
• Configurazione del fallback per i rifiuti, aggiungendo la gestione di stop_reason: "refusal" prima di leggere il contenuto della risposta e configurando un percorso di retry di fallback quando la destinazione è Claude Fable 5.1, Claude Fable 5 o Claude Opus 5 (il parametro lato server fallbacks, tipicamente nella sua modalità "default", il middleware refusal-fallback dell'SDK o un retry con credito di fallback), e aggiornando il codice di fallback scritto per le 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 Migrare a Claude Opus 5 da Claude Opus 4.8 e Migrare a Claude Fable 5.1.

Configurare un Managed Agent

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

/claude-api 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:

Build a streaming chat UI with the Claude API in TypeScript

Migrare un progetto esistente:

/claude-api migrate this codebase to claude-opus-5 and re-tune effort

Onboarding di un nuovo Managed Agent:

/claude-api managed-agents-onboard

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