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, uso degli strumenti, elaborazione batch, 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 di agenti persistenti e sandbox per sessione.

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

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

La skill utilizza la divulgazione progressiva per mantenere il contesto efficiente: Claude carica solo la documentazione pertinente al linguaggio del tuo progetto, alla superficie (Messages API o Managed Agents) e al compito specifico da svolgere (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, avvio rapido, pattern comuni e gestione degli errori per il linguaggio del tuo progetto
• Guida all'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 audit degli invalidatori silenziosi
• Migrazione dei modelli: Guida passo passo per migrare a modelli Claude più recenti (incluse le modifiche incompatibili e i cambiamenti di comportamento su Claude Opus 5)
• Informazioni sui modelli attuali: ID dei modelli, dimensioni della finestra di contesto e prezzi
• Errori comuni: Guida dettagliata per evitare gli errori più frequenti nell'integrazione con l'API

Per i Managed Agents (beta):

• Flusso di onboarding: Una procedura guidata basata su 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 di processed_at, gestione delle interruzioni, insidie del file-mount 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 invece 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 i 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 digitando /claude-api (con sottocomando o testo opzionale) in qualsiasi ambiente in cui la skill è installata.

La skill non si attiva per attività di programmazione generiche, lavori 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 utilizza più linguaggi, Claude chiede quale si applica. Per i linguaggi non supportati (Rust, Swift, C++), la skill fornisce esempi cURL/HTTP grezzi.



Come usare la skill



In Claude Code (inclusa)

La skill è fornita 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 maggiori informazioni 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 di skill 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 code base. Invocala direttamente con /claude-api migrate:

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

Puoi anche passare un ambito specifico in anticipo 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 che per quelli dei 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) 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 che sono GA sul 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 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, di subagenti e di rispetto delle istruzioni che potrebbero comportarsi diversamente sul modello di destinazione
• Gestione dei default silenziosi, riattivando la sintesi 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 o Claude Opus 5 (il parametro lato server fallbacks, tipicamente nella sua modalità "default", il middleware SDK di refusal-fallback, o un retry con credito di fallback), e aggiornando il codice di fallback scritto per le forme di preview precedenti

Durante le modifiche, la skill spiega inline ogni cambiamento e la sua motivazione. Al completamento, produce una checklist di elementi che richiedono verifica manuale (tipicamente test di integrazione, regolazione dei prompt di controllo della lunghezza e ricalibrazione di costi/limiti di velocità).

Per l'elenco completo delle modifiche specifiche per modello che la skill applica, consulta Migrare a Claude Opus 5 da Claude Opus 4.8.



Configurare un Managed Agent

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

/claude-api managed-agents-onboard

La skill esegue un'intervista che ti guida attraverso il modello mentale dei Managed Agents (configurazioni di Agent rispetto a Sessions), crea un template di configurazione dell'agente, configura ambienti e strumenti, imposta il loop di sessione ed emette codice eseguibile per il tuo linguaggio. La skill copre anche il flusso obbligatorio Agent (una volta) → Session (a 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 pertinente specifica per il linguaggio e guida Claude nell'implementazione utilizzando i pattern API attuali e le best practice.



Prossimi passi