Agent Skill

Se usi un assistente di programmazione IA come Claude Code, Codex o Cursor, lo Skill di SpicyAPI gli insegna a lavorare con SpicyAPI come si deve. Lo installi una volta sola. Da quel momento puoi dire «aggiungi alla mia app la generazione di immagini con SpicyAPI» e l’assistente segue le regole di SpicyAPI invece di tirare a indovinare.

Per seguire questa pagina non serve essere sviluppatori. Se sai incollare un comando in un terminale, sai installare lo Skill.

Che cos’è uno Skill

Uno Skill è una cartella di istruzioni scritte per un assistente IA anziché per le persone. Pensalo come il manuale operativo che consegneresti a un nuovo collega: non fa il lavoro da solo, ma dice a chi lo fa quali passaggi seguire, in che ordine e che cosa non fare mai.

Gli assistenti IA sanno molto di programmazione in generale, ma non hanno conoscenze affidabili sulle regole specifiche di SpicyAPI. Se deve tirare a indovinare, un assistente può:

• inventarsi un ID del modello o un campo di input che non esiste;
• incollare la tua chiave API direttamente nel codice;
• inviare due volte la stessa richiesta a pagamento dopo un intoppo di rete, e pagare due volte;
• consegnarti un link al risultato che smette di funzionare qualche giorno dopo.

Con lo Skill installato, l’assistente legge le regole di SpicyAPI prima di cominciare. In pratica funziona così:

1. La cartella dello Skill si trova in un posto che l’assistente controlla all’avvio di ogni sessione.
2. L’assistente legge il riassunto dello Skill, lungo un paragrafo. Quando la tua richiesta riguarda SpicyAPI, apre le istruzioni complete. Non devi nominare lo Skill.
3. Segue quelle istruzioni mentre scrive codice o esegue comandi per te.

Tre cose da sapere fin da subito:

• È solo testo. File Markdown e YAML: niente programmi, niente script, nulla che venga eseguito quando lo installi. Puoi aprire ogni file con un editor di testo; vedi Che cosa contiene.
• Non contiene alcuna chiave API e non fa chiamate. Da solo non può raggiungere il tuo account né spendere denaro.
• È gratuito e open source. Ha licenza MIT, è pubblicato su npm come @spicyapi/skill ed è sviluppato in modo aperto su github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK e CLI

SpicyAPI ha quattro strumenti ufficiali. Risolvono problemi diversi e sono pensati per essere usati insieme.

Lo Skill non sostituisce nessuno di questi strumenti. Dice all’assistente come usarli: gli strumenti MCP quando sono collegati, la CLI per le operazioni una tantum e l’SDK del tuo linguaggio per il codice che entra nella tua applicazione.

• Solo lo Skill. L’assistente scrive codice di integrazione corretto per il tuo progetto, ma non può consultare nulla nel tuo account né eseguire attività per te.
• Solo MCP. L’assistente può agire sul tuo account, ma ogni volta deve capire da solo l’ordine giusto dei passaggi.
• Entrambi. L’assistente può provare le cose per te e le fa nel modo documentato. Se vuoi che il tuo assistente esegua attività reali, installali entrambi. Non vanno in conflitto.

In che cosa aiuta

La colonna di sinistra è ciò che chiedi. La colonna di destra è ciò che lo Skill fa fare all’assistente mentre esegue la richiesta.

Che cosa non fa

• Spendere denaro di propria iniziativa. Lo Skill è testo e non può chiamare nulla. Se il tuo assistente ha anche il server MCP o la CLI e una chiave API, può creare attività a pagamento. Lo Skill gli dice di mostrarti prima il prezzo e di ottenere la tua conferma esplicita, a meno che la tua richiesta non abbia già autorizzato chiaramente proprio quell’esecuzione a pagamento. Con il server MCP, inoltre, ogni azione a pagamento si ferma per una conferma che l’assistente non può saltare.
• Inventare funzionalità. Non scrive chiamate per cose che l’API pubblica non offre, come annullare un’attività, eliminare il record di un’attività o reinviare un webhook.
• Toccare le impostazioni del tuo account. Registrazione, accesso, pagamenti, ricariche, membri del team, richieste sulla privacy e chiusura dell’account restano nella console di SpicyAPI. L’assistente non prova ad automatizzarli.
• Fingere un test. Se chiedi un test reale, fa una richiesta reale (ed eventualmente a pagamento, dopo la tua conferma) e riferisce che cosa è successo davvero. Un mock superato non viene mai presentato come «verificato».
• Aggiungere un’impostazione sui contenuti. SpicyAPI non ha alcun flag sulla modalità dei contenuti né una revisione dei contenuti richiesta per richiesta, e lo Skill non se ne inventa uno. È il modello che scegli a decidere che cosa può fare.

Prima di iniziare

Ti servono quattro cose. Per l’installazione bastano le prime tre.

1. Un assistente di programmazione IA che supporti gli Agent Skills. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf e molti altri li supportano. Lo Skill usa il formato di cartella portabile degli Agent Skills, quindi funziona con qualsiasi assistente che legga quel formato. Se non sei sicuro del tuo, cerca «skills» nella sua documentazione.

2. Node.js 22 o successivo, che fornisce il comando npx. Verifica con:

   node --version

   L’installer skills al momento chiede Node.js 22.20 o successivo, mentre l’installer del pacchetto stesso richiede la 22.13 o successiva. Se il comando non viene trovato o la versione è più bassa, installa la versione LTS da nodejs.org e apri un nuovo terminale.

3. Un terminale. Su macOS, l’app Terminale. Su Windows, PowerShell. Se vuoi un’installazione per un singolo progetto, esegui i comandi dalla cartella di quel progetto.

4. Una chiave API di SpicyAPI, quando inizi a chiamare l’API. Per installare lo Skill non serve. Crea una chiave nella console: inizia con sk-spicy- e viene mostrata una sola volta. Salvala in una variabile d’ambiente chiamata SPICY_API_KEY e non incollare mai la chiave in una chat con il tuo assistente. Vedi Autenticazione.

Installazione

Ci sono due modi per installarlo. Entrambi mettono al loro posto gli stessi file. Usa il primo, a meno che tu non abbia un motivo per non farlo.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, solo questo progetto
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, tutti i progetti
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code e Codex, tutti i progetti, senza domande
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Verifica che funzioni

npx skills list      # Skill installati nel progetto corrente
npx skills list -g   # Skill installati per tutti i progetti

Esempi di richieste

Incolla una di queste richieste nel tuo assistente e adatta i dettagli. Nomina SpicyAPI nella richiesta, così l’assistente sa che lo Skill si applica.

Se sai già quale modello vuoi, copia il suo ID esatto dalla scheda API della pagina del modello o dal catalogo in tempo reale autenticato (GET /api/v1/models) e inseriscilo nella richiesta. Gli esempi scrivono MODEL_ID_FROM_CATALOG nel punto in cui va quell’ID: è un segnaposto, non un ID reale. Se non ne hai uno, chiedi all’assistente di sceglierlo dal catalogo in tempo reale. Vedi Catalogo dei modelli e schemi.

Aggiungere un endpoint per le immagini a un’app Next.js

Aggiungi alla mia app Next.js una API route lato server che riceve un prompt di testo, genera un’immagine con SpicyAPI usando il modello MODEL_ID_FROM_CATALOG, attende il risultato e restituisce il link all’immagine. Leggi la chiave API da SPICY_API_KEY.

Su che cosa lo Skill fa vigilare l’assistente:

• La chiave resta sul tuo server, in SPICY_API_KEY. La tua pagina web chiama la tua route; non chiama mai SpicyAPI con la chiave.
• Prima di costruire la richiesta legge dal catalogo in tempo reale i campi di input attuali di quel modello.
• Per prima cosa ottiene un preventivo esatto e ti mostra il costo stimato e l’addebito massimo. La richiesta a pagamento porta con sé quel preventivo confermato.
• Crea una chiave di idempotenza per la generazione e la riutilizza se la richiesta va in timeout.
• Attende con una scadenza e poi controlla lo state dell’attività: un’attesa conclusa non equivale a una generazione riuscita.

Ricevere i risultati con un webhook in Express

Aggiungi al mio server Express un endpoint webhook che riceve i risultati delle attività SpicyAPI, verifica la firma usando SPICY_WEBHOOK_SECRET e salva nel mio database il link al risultato.

• Verifica la firma sul corpo grezzo esatto della richiesta, prima di analizzarlo come JSON.
• Usa il request_id della consegna per ignorare i duplicati, perché lo stesso evento può arrivare più di una volta.
• Legge il risultato direttamente da un webhook completo e verificato, senza fare un’ulteriore consultazione.

Copiare i video finiti nel tuo archivio

Quando un’attività video di SpicyAPI riesce, scarica il video e caricalo nel mio bucket S3, poi salva il mio link al posto di quello di SpicyAPI.

• I link ai risultati sono temporanei e i file generati vengono conservati per circa 14 giorni, quindi salva una copia duratura che controlli tu.
• Non invia la tua chiave API quando scarica da un link al risultato.
• Se un link è scaduto, chiede di nuovo a SpicyAPI la stessa attività per ottenere un link nuovo. Non crea mai una nuova attività solo per avere un link.

Trasformare la foto di un utente in un video

Permetti agli utenti di caricare una foto nella mia app e di trasformarla in un breve video con SpicyAPI.

• Prima carica il file su SpicyAPI e mette nella richiesta l’indirizzo spicy:// restituito, invece di incollare il file in base64.
• Rispetta i limiti di caricamento: 10 MiB per le immagini, 90 MiB per i video MP4 o WebM e per l’audio MP3 o WAV.
• Una foto che si trova già a un link HTTPS pubblico può essere passata direttamente, senza caricarla.

Gestire i nuovi tentativi e un saldo basso

Fai in modo che la mia integrazione con SpicyAPI gestisca i fallimenti: riprova dopo i timeout di rete senza pagare due volte, mostra un messaggio chiaro quando il saldo del mio account è troppo basso e rallenta quando raggiungo il limite di frequenza.

• Dopo un timeout riprova con la stessa chiave di idempotenza, così un nuovo tentativo non può creare una seconda attività a pagamento.
• Non riprova in caso di «saldo insufficiente» (codice 40201): il tuo utente vede un messaggio chiaro e tu ricarichi dalla console.
• Prima di riprovare aspetta quanto indicato da Retry-After.
• Se il preventivo è scaduto o il prezzo è cambiato (codice 40901), ottiene un nuovo preventivo e ti chiede di nuovo conferma, invece di rinunciare al controllo del prezzo.
• Sa che ripetere un’attività fallita crea una nuova attività che può essere addebitata di nuovo, quindi lo fa solo quando vuoi davvero un nuovo tentativo.

Generare un lotto

Genera con SpicyAPI le foto prodotto dei 20 articoli in products.csv, al massimo 3 alla volta, e registra nel log l’ID di ogni attività.

• SpicyAPI non ha un endpoint per i lotti, quindi esegue un numero limitato di richieste alla volta.
• Ogni elemento ha la propria chiave di idempotenza e il proprio prezzo.
• Registra l’ID di ogni attività non appena questa viene accettata.
• Se un elemento va in timeout, recupera solo quell’elemento e non reinvia mai l’intero lotto.

Che cosa contiene

La cartella installata è fatta così:

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

L’assistente apre i due file di riferimento solo quando un compito ne ha bisogno, così la sua memoria di lavoro resta libera per il tuo progetto. Per leggere i file prima di installarli, esegui npx @spicyapi/skill path: stampa la cartella in cui il pacchetto li tiene.

Lo Skill dice all’assistente di configurare il tuo codice e i tuoi strumenti con queste variabili d’ambiente. Lo Skill in sé non ne legge nessuna.

Aggiornare e rimuovere

Aggiornare

Lo Skill cambia quando cambia il flusso di lavoro consigliato da SpicyAPI, e le copie installate non si aggiornano da sole. La cartella installata non riporta alcun numero di versione, quindi reinstallare è il modo più semplice per essere sicuri di avere la versione attuale.

• Installato con npx skills add: esegui di nuovo lo stesso comando, con lo stesso ambito e gli stessi assistenti. Sostituisce i file installati con quello che il repository contiene in quel momento, quindi un aggiornamento ti arriva appena viene pubblicato, senza attese.

• Installato con l’installer del pacchetto: eseguilo di nuovo con --force e lo stesso --target. Aggiungere @latest fa sì che npx scarichi il pacchetto più recente invece di riutilizzarne uno in cache:

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

Rimuovere

Rimuovere lo Skill non ha effetti sul tuo account SpicyAPI, sulle tue chiavi API né sul codice che l’assistente ha già scritto.

• Installato con npx skills add: esegui questo comando dalla stessa cartella di progetto, aggiungendo -g se l’avevi installato a livello globale. Poi controlla che la cartella spicyapi sia sparita.

  npx skills remove spicyapi

• Installato con l’installer del pacchetto: elimina la cartella spicyapi, dal Finder, da Esplora file o da un terminale:

  # macOS e Linux: usa la cartella in cui l’hai installato
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Controlla due volte il percorso prima di premere Invio: deve terminare con spicyapi.

Poi avvia una nuova sessione, così l’assistente smette di usare lo Skill.

Risoluzione dei problemi

Codice sorgente

Il pacchetto ha licenza MIT ed è sviluppato in modo aperto su github.com/spicyapi-ai/spicy-skill. È lì che si leggono le istruzioni che lo Skill installa davvero, si segnala un comportamento diverso da quello descritto e si propone una modifica.

Prossimi passi