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 dal server con esecuzione degli strumenti ospitata da Anthropic, configurazioni di agenti persistenti e sandbox per sessione.

Copre 8 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, dove puoi installarla in qualsiasi ambiente che supporti le Agent Skills.

La skill utilizza la progressive disclosure (divulgazione progressiva) per mantenere il contesto efficiente: Claude carica solo la documentazione rilevante per il linguaggio del tuo progetto, la superficie (Messages API o Managed Agents) e il compito specifico in questione (uso degli strumenti, streaming, batch e così via), invece di caricare tutto in una volta.



Cosa fornisce la skill

Quando attivata, la skill fornisce a Claude:

Per la Messages API:

• Documentazione SDK specifica per linguaggio: Installazione, quick start, 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 utente di chat e gestire la visualizzazione incrementale
• Elaborazione batch: Elaborazione batch offline al 50% del costo
• Cache dei prompt: Progettazione della stabilità dei prefissi, posizionamento dei breakpoint e audit degli invalidatori silenziosi
• Migrazione dei modelli: Guida passo-passo per migrare a modelli Claude più recenti (incluse le breaking change e i cambiamenti di comportamento su Claude Opus 4.8)
• Informazioni aggiornate sui modelli: ID dei modelli, dimensioni della finestra di contesto e prezzi
• Errori comuni: Guida dettagliata per evitare errori frequenti durante l'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 perdita di dati, gate queued/processed di processed_at, gestione delle interruzioni, problematiche di file-mount e gestione delle credenziali
• Vincoli di deployment: I Managed Agents sono disponibili 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 i Managed Agents
• Aggiungi, modifichi o ottimizzi una funzionalità di Claude in un file (cache dei prompt, adaptive thinking, compaction, uso degli strumenti, batch, file, citazioni, memoria) o un riferimento a un modello

Invocazione manuale digitando /claude-api (con 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 di 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 raw.



Come usare la skill



In Claude Code (inclusa)

La skill è inclusa in 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 sulle 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 installarla come plugin di Claude Code:

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



Migrazione a un modello Claude più recente

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

/claude-api migrate this project to claude-opus-4-8

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-4-8
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-4-8

Quando l'ambito è ambiguo (ad esempio, un semplice /claude-api migrate to claude-opus-4-8), 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 modello, incluse le costanti SDK tipizzate (Model.CLAUDE_OPUS_4_7 → Model.CLAUDE_OPUS_4_8) in tutti i linguaggi supportati, e classifica ogni file come chiamante, definitore di modello o riferimento a stringa opaca prima della modifica
• Rilevamento della piattaforma cloud, preservando i formati di ID modello specifici della piattaforma (ad esempio, il prefisso anthropic. su Amazon Bedrock) e saltando le modifiche per funzionalità non disponibili sulle piattaforme gestite da partner
• Modifiche ai parametri con breaking change, 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 assistant 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, xhigh per casi d'uso di coding e agentici su Claude Opus 4.8 e Claude Opus 4.7)
• Ottimizzazione del comportamento dei prompt, segnalando i prompt di controllo della lunghezza, attivazione degli strumenti, subagent e seguimento delle istruzioni che potrebbero comportarsi diversamente sul modello di destinazione
• Gestione dei default silenziosi, riattivando la summarization del thinking (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 il target è Claude Fable 5 (il parametro fallbacks lato server, il middleware refusal-fallback dell'SDK o un retry con fallback-credit), e aggiornando il codice di fallback scritto per forme di preview precedenti

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

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



Configurazione di 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 esegue un'intervista che ti guida attraverso il modello mentale dei Managed Agents (configurazioni 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 (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.

I Managed Agents richiedono 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:

Creazione di un'applicazione di chat:

Build a streaming chat UI with the Claude API in TypeScript

Migrazione di un progetto esistente:

/claude-api migrate this codebase to claude-opus-4-8 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 attraverso l'implementazione utilizzando i pattern API e le best practice attuali.



Passaggi successivi