Codex Skills: creare una skill per attività ripetitive

Se spieghi la stessa cosa a Codex cinque volte alla settimana — come formattare un report, passare in rassegna le email o preparare testi nel tuo stile — puoi annotare una volta sola queste istruzioni in una skill. In seguito, l’agente può individuarla in base alla sua descrizione quando questa corrisponde all’attività, oppure puoi richiamarla esplicitamente. Una skill è una normale cartella con un file di testo chiamato SKILL.md; per un caso d’uso di base non serve programmare.

Di seguito vediamo com’è strutturata una skill, dove Codex la cerca, come crearne una passo dopo passo e come scegliere un modello in base al costo. I comandi e i prezzi si basano sulla documentazione ufficiale di OpenAI aggiornata al 20 settembre 2026. Qui non ripetiamo le istruzioni per installare Codex; sono disponibili nella guida Codex di OpenAI: cos’è, come installarlo e avviarlo.

Informazioni pratiche sull’uso di Ailoot sono disponibili nella documentazione.

Che cos’è una skill in Codex?#

Il formato si chiama Agent Skills. È uno standard aperto sviluppato originariamente da Anthropic e pubblicato su agentskills.io. È supportato da diversi agenti, tra cui Codex, Claude Code e altri client compatibili. Una skill semplice, composta soltanto da istruzioni testuali, può essere trasferita tra loro copiandone la cartella. Se contiene script, dipendenze o un file agents/openai.yaml, dopo il trasferimento controlla la skill: alcune impostazioni sono specifiche di un determinato client.

Questo metodo di caricamento si chiama divulgazione progressiva. L’agente usa il nome e la descrizione di una skill per stabilire quando è pertinente. Quando un’attività corrisponde alla descrizione, l’agente legge tutto il file SKILL.md e lo segue. Questo significa che puoi tenere decine di skill in Codex senza caricare nel contesto tutte le istruzioni: l’elenco iniziale occupa al massimo il 2% della finestra di contesto (oppure 8.000 caratteri, se la dimensione della finestra non è nota). Se le skill sono molte, Codex prima accorcia le loro descrizioni; se sono moltissime, può ometterne alcune dall’elenco e avvisarti.

È facile confondere una skill con AGENTS.md. Codex legge questo file in ogni sessione di progetto. Contiene regole permanenti: stack tecnologico, convenzioni e stile di programmazione. Una skill si carica su richiesta quando un’attività corrisponde alla sua descrizione. Quindi inserisci le regole permanenti in AGENTS.md e un processo ripetitivo con i relativi passaggi in una skill.

Le skill di Hermes Agent funzionano in modo simile, ma sono archiviate in cartelle diverse e si installano in modo diverso. Sono trattate in una guida separata: Skill di Hermes Agent: installazione e creazione. Questo articolo riguarda solo Codex.

Da cosa è composta una skill?#

Una cartella di skill ha questa struttura:

my-skill/
  SKILL.md        - obbligatorio: metadati e istruzioni
  scripts/        - facoltativo: codice eseguibile
  references/     - facoltativo: documenti da caricare quando servono
  assets/         - facoltativo: modelli e risorse
  agents/
    openai.yaml   - facoltativo: aspetto e dipendenze

Il file SKILL.md inizia con un blocco di metadati tra tre trattini, seguito dal testo delle istruzioni in Markdown:

---
name: weekly-sales-report
description: Compila un report settimanale sulle vendite a partire da un’esportazione CSV. Usa questa skill quando viene richiesto un report settimanale sulle vendite o un riepilogo per responsabile.
---

1. Leggi il file di esportazione dal percorso fornito dall’utente.
2. Raggruppa le righe per responsabile e calcola il totale e il numero di trattative.
3. Confronta con la settimana precedente se il file relativo alla settimana precedente è nelle vicinanze. Se non c’è, dichiaralo chiaramente nel report.
4. Salva il risultato in report.md: una tabella per responsabile, il totale e fino a tre cambiamenti chiave con cifre, in base ai dati disponibili.

Tre regole tratte dalle raccomandazioni ufficiali di OpenAI:

• Una skill, un’attività. Invece di “Gestisci tutto il mio marketing”, scegli un’attività specifica: “compila un report sulle vendite a partire da questa esportazione”. Suddividi un processo più ampio in skill separate, che possono essere richiamate in sequenza.
• Descrivi i passaggi direttamente, indicando input e output in modo esplicito: cosa usare, cosa fare e dove salvare il risultato.
• Inizia con istruzioni testuali. Usa gli script in scripts/ quando un passaggio deve essere eseguito sempre nello stesso modo, per esempio per convertire un file o chiamare un sistema esterno.

Codex seleziona una skill per un’attività in base al campo description, quindi inizia la descrizione con l’attività e le parole che usi di solito per descriverla.

Dove cerca le skill Codex?#

È pratico archiviare le skill di progetto in git insieme al codice, così tutto il team usa lo stesso insieme. Le skill personali sono adatte ai tuoi processi, per esempio al tuo stile di scrittura delle email. Se due skill a livelli diversi hanno lo stesso nome, Codex non le unisce: entrambe compaiono nell’elenco, rendendo più difficile scegliere. Dai loro nomi univoci.

Per confronto, le skill di Claude Code sono archiviate in .claude/skills, ciascuna con il proprio SKILL.md, e usano lo stesso standard aperto. Una skill semplice può essere trasferita copiandone la cartella; poi dovresti eseguirla e controllare che venga richiamata. Per un confronto tra le estensioni di Claude Code, vedi Skill, subagenti, MCP o plugin.

Come decide Codex quale skill richiamare?#

All’inizio il richiamo esplicito è più affidabile: nella CLI di Codex, inserisci $weekly-sales-report per selezionare quel processo specifico. Il richiamo implicito è più comodo per il lavoro quotidiano. Dopo aver scritto una skill, provala usando parole normali: chiedi a Codex di svolgere l’attività con parole tue, senza $, e verifica se seleziona la skill. Se non lo fa, controlla innanzitutto se Codex vede la skill in /skills, se si trova in una delle cartelle di caricamento e se la skill o il suo richiamo automatico sono disabilitati. Se è disponibile e le impostazioni sono corrette, perfeziona la description: indica l’attività e i modi tipici per formulare la richiesta.

Se vuoi che una skill sia disponibile soltanto tramite un comando esplicito, puoi configurare anche questo: in agents/openai.yaml, il parametro allow_implicit_invocation: false disabilita il richiamo automatico, mentre $name continua a funzionare. Puoi disabilitare completamente una skill senza eliminarla tramite ~/.codex/config.toml:

[[skills.config]]
path = "/full/path/to/the/skill/SKILL.md"
enabled = false

Dopo aver modificato config.toml, riavvia Codex. Codex rileva automaticamente le modifiche alle cartelle delle skill, ma se una nuova skill non compare, riavvia Codex.

Come creare una skill personale: passo dopo passo#

1. Scegli un’attività

   Scegli un processo che ripeti regolarmente e che abbia un risultato chiaro: un report, una tabella, una lettera o un’analisi. Se non hai mai ricevuto un risultato di quel tipo, prima completa manualmente l’attività con un agente. Usa il risultato ottenuto come riferimento per le istruzioni.

2. Crea una skill

   Per creare una skill con l’assistente integrato, inserisci $skill-creator in una sessione Codex. Ti chiederà cosa fa la skill, quando dovrebbe essere richiamata e se sono necessari script, poi preparerà la struttura per te. Per crearne una manualmente, crea una cartella .agents/skills nel progetto, con una sottocartella per la skill, per esempio .agents/skills/weekly-sales-report, e inserisci al suo interno un file SKILL.md usando l’esempio riportato sopra.

3. Scrivi le istruzioni

   Scrivi i passaggi come elenco numerato, indicando chiaramente input e output. Se il processo richiede precisione (trasferire dati, rinominare, calcolare), specifica nel dettaglio ogni passaggio. Per le attività creative (scrivere testi, scegliere argomentazioni), stabilisci limiti e criteri per un buon risultato, lasciando al modello spazio per lavorare.

4. Prova il richiamo

   Chiedi a Codex di svolgere l’attività usando parole tue, senza nominare la skill. Se seleziona la skill giusta, la descrizione ha funzionato per quella formulazione. Poi prova il richiamo esplicito con $name. Se la skill non viene richiamata, controlla la cartella, verifica se compare in /skills e controlla le impostazioni di disabilitazione descritte sopra. Se una nuova skill non compare nell’elenco, riavvia Codex. Se il richiamo esplicito funziona e il richiamo automatico è consentito, ma Codex non risponde a una richiesta formulata con parole tue, perfeziona l’inizio della description: indica prima l’attività e poi i modi tipici per formularla. Prova di nuovo.

5. Perfeziona dopo le esecuzioni

   Dopo ogni esecuzione, controlla il risultato e indica all’agente cosa modificare nella skill: “La prossima volta aggiungi una colonna che mostri la quota nella tabella riepilogativa”. Se la prima versione non produce il risultato che ti serve, perfeziona la skill per il lavoro creativo sulla base dei commenti ricevuti.

Le skill già pronte di OpenAI e della community si installano con $skill-installer e il nome della skill. Per condividere le tue skill con altre persone, distribuiscile come plugin: è un metodo di pacchettizzazione separato, non necessario per l’uso personale.

Come controllare il risultato di un agente#

I controlli possono essere oggettivi o soggettivi. I controlli oggettivi sono misurabili: “il report include tutti i 12 responsabili dell’esportazione” oppure “la somma della tabella corrisponde al totale del CSV”. Indicali come requisiti vincolanti. I controlli soggettivi riguardano la qualità: “il testo sembra scritto da me” oppure “le conclusioni sono brevi”. Puoi formalizzare anche questi: inserisci nella skill un esempio di passaggio ben scritto e chiedi all’agente di confrontare il risultato con l’esempio.

Una tecnica utile è un ciclo di revisione: dopo aver preparato il risultato, l’agente passa in rassegna un elenco di criteri, corregge ciò che individua e solo allora te lo mostra. Anthropic usa un approccio simile chiamato evaluator-optimizer: un agente svolge il lavoro, un valutatore separato lo esamina e restituisce commenti, e il processo si ripete fino all’accettazione. In una singola skill, di solito è una versione semplificata: un controllo finale rispetto a un elenco. Tieni presente il limite: è meno efficace di un valutatore indipendente, perché l’agente che svolge il lavoro potrebbe non accorgersi dei propri errori.

Esempio di blocco di controllo per il nostro report:

## Prima di consegnare, controlla
- Nella tabella sono presenti tutti i responsabili dell’esportazione; non ne è stato escluso nessuno.
- Il totale corrisponde alla somma del CSV fino all’ultimo centesimo.
- Ogni cambiamento chiave è supportato da una cifra; se non ci sono dati per il confronto, il report lo dichiara chiaramente.
- Il file è salvato in report.md e il percorso è stato condiviso con l’utente.

Quale modello scegliere per una skill?#

La colonna più a destra suggerisce attività per i controlli iniziali. Non è una classifica né il risultato di un confronto: puoi individuare il modello giusto per la tua skill soltanto dopo averlo eseguito e averlo confrontato con il risultato di riferimento.

I prezzi nella tabella sono tariffe API ricavate dalle pagine dei modelli aggiornate al 20 settembre 2026, non prezzi degli abbonamenti ChatGPT. Con un abbonamento, l’utilizzo rientra nei relativi limiti. A questa data, Sol ha una tariffa promozionale di $4/$20 almeno fino al 21 novembre 2026; il prezzo standard è $5/$30. Prima di un’esecuzione ricorrente su larga scala, controlla la pagina dei prezzi: le promozioni di OpenAI cambiano.

Esegui la stessa skill con il modello meno costoso successivo e confronta il risultato con quello di riferimento. Se la qualità resta alta, prova il modello ancora meno costoso. Se la qualità cala, torna a quello precedente. I modelli hanno anche livelli di effort: Astra va da low a max e la famiglia 5.6 da none a max. Provali anche rispetto allo stesso riferimento: scegli prima il modello, poi il livello di effort.

L’esecuzione regolare di una skill comporta costi ricorrenti. Il prezzo di input di Astra è 50 volte quello di Luna, quindi usare modelli diversi per la stessa skill ricorrente può comportare costi sensibilmente diversi. Per una skill che analizza schermate e documenti, un modello più debole può costare di più a causa delle rielaborazioni.

Errori comuni nella creazione e nell’uso di una skill#

• Una skill “per tutto”. Un processo, una skill: è anche la raccomandazione di OpenAI. È difficile descrivere con precisione una skill universale di dieci pagine, e Codex seleziona una skill per un’attività in base alla sua descrizione.
• Una descrizione vaga. “Aiuta con i report” non chiarisce per quali tipi di report è destinata la skill. All’inizio della description, indica l’attività e i modi tipici per formularla.
• Istruzioni senza un risultato definito. Se non specifichi cosa produrre e dove salvarlo, i risultati possono variare da un’esecuzione all’altra.
• Nessun controllo. Senza un passaggio finale con criteri, il risultato potrebbe essere una bozza incompleta che dovrai revisionare interamente da solo.
• Il modello più potente come impostazione predefinita. Prima verifica se l’attività può essere svolta da un modello meno costoso: esegui la stessa skill e confronta il risultato con quello di riferimento. Cambia modello solo se la qualità resta alta.
• Gli stessi nomi in cartelle diverse. Codex non unisce le skill con lo stesso nome, rendendo più difficile scegliere quella giusta.

Come iniziare e trasferire una skill a Claude Code#

Se lavori con più agenti, puoi trasferire a Claude Code una cartella che contiene soltanto istruzioni testuali e un file SKILL.md. Lì le skill sono archiviate in .claude/skills e si richiamano con /name. Dopo il trasferimento, controlla la skill se contiene script, dipendenze o agents/openai.yaml. Per una guida alla raccolta di skill di Claude Code, vedi Skill di Claude Code: come creare la tua raccolta; per un confronto tra Codex e Claude Code, vedi Codex vs Claude Code.

Apri Ailoot.