Portabilità di SKILL.md: un'analisi tecnica di Claude Code vs. Codex CLI

Il formato SKILL.md è uno standard semplice e potente per estendere le capacità degli agenti di codifica. Sia Claude Code di Anthropic che Codex CLI di OpenAI lo supportano. Questo porta a una domanda critica per gli sviluppatori: lo stesso file SKILL.md funziona su entrambi? La risposta semplice è sì, il file stesso è portabile. La risposta utile è più complessa, e ha meno a che fare con il formato del file e più con l'ambiente di esecuzione che ogni agente fornisce.

In SkillProof, installiamo ed eseguiamo gli skill di Claude Code su lavoro reale per vedere se superano il test. Pubblichiamo i risultati, inclusi i fallimenti. Dei 2090 skill testati in un ambiente Claude Code, 1291 sono stati promossi (62%), 697 hanno funzionato solo dopo una configurazione che la descrizione deve esplicitare, e 102 hanno ricevuto un verdetto di fallimento: alcuni sono stati eseguiti lasciando una situazione peggiore rispetto a non usare alcuno skill, altri non sono potuti essere eseguiti affatto a causa di una CLI mancante, una dipendenza morta o un esempio che va in crash. Non abbiamo mai eseguito uno skill su Codex CLI. Il nostro intero dataset si basa sull'esecuzione con Claude Code.

Tuttavia, il nostro corpus di test contiene un insieme unico di prove unidirezionali. Questo articolo esamina le differenze tecniche nel modo in cui i due agenti gestiscono SKILL.md e ciò che i nostri dati, basati solo su Claude, rivelano sulla portabilità da Codex a Claude.

Il terreno comune: il formato SKILL.md

Prima di confrontare gli agenti, è essenziale capire cos'è un file SKILL.md. È un file di testo che combina istruzioni per l'agente con metadati. La struttura è semplice:

1. Frontmatter YAML: Un blocco all'inizio del file, delimitato da ---, contiene coppie chiave-valore. name e description sono fondamentali. L'agente usa la descrizione per decidere quando invocare lo skill. Una chiave opzionale allowed-tools nomina gli strumenti che lo skill desidera siano pre-approvati in modo da non fermarsi per chiedere durante l'esecuzione. È un campo di comodo, non una sandbox: non sottrae strumenti al modello. Potete trovare un'analisi dettagliata nella nostra guida di riferimento al frontmatter.
2. Corpo Markdown: Sotto il frontmatter si trova il set di istruzioni per l'agente, scritto in semplice markdown. Questo dice al modello come compiere l'attività, passo dopo passo.
3. File inclusi: Uno skill può includere altri file, come script o dati di riferimento, che vengono impacchettati con esso.

Fondamentalmente, SKILL.md non contiene firme di funzioni o schemi di argomenti. È un formato di istruzioni in linguaggio naturale, non un manifest strutturato per la chiamata di funzioni. Quello è il dominio di MCP, un protocollo separato e distinto. Per un approfondimento su questo, vedete il nostro confronto tra Claude Skills vs. MCP.

Poiché SKILL.md è solo testo strutturato, qualsiasi parser conforme può leggerlo. Sia Claude Code che Codex CLI possono caricare lo stesso file senza modifiche. La differenza sta in ciò che accade dopo.

Caricamento ed esecuzione: due ambienti diversi

Sebbene il file sia lo stesso, il contesto in cui viene eseguito non lo è. L'architettura dell'agente, le impostazioni predefinite e gli strumenti disponibili definiscono l'ambiente di esecuzione. È qui che emergono le differenze pratiche tra Claude Code e OpenAI Codex.

Claude Code

Nel nostro lavoro, testiamo esclusivamente con Claude Code. Gli skill vengono caricati da ~/.claude/skills per gli skill personali e da .claude/skills all'interno di un progetto per quelli con scope di repository. Quando si assegna un'attività all'agente, questo confronta il prompt con il campo description di tutti gli skill disponibili. È anche possibile chiamarne uno direttamente per nome con un comando slash.

Un comportamento critico che abbiamo documentato è la sua modalità di fallimento. Se il frontmatter YAML in un file SKILL.md è malformato — una tabulazione fuori posto, una virgoletta mancante — Claude Code non produce un errore di validazione. Lo skill diventa semplicemente invisibile all'agente. Non verrà elencato e non sarà mai attivato. Questo fallimento silenzioso può essere difficile da debuggare, un argomento che trattiamo nel nostro post su cosa fare quando uno skill non si attiva.

La nostra metodologia prevede l'esecuzione di ogni skill su un'attività del mondo reale. I risultati dei nostri 2090 test mostrano che un 'pass' non è garantito. I 697 skill che hanno ottenuto 'setup' richiedevano una configurazione non banale che abbiamo dovuto documentare. I 102 'fails' o non potevano essere eseguiti affatto a causa di dipendenze mancanti o producevano un risultato peggiore rispetto a non usare alcuno skill.

Codex CLI

Codex CLI è un agente di codifica open-source per terminale di OpenAI. Non è un wrapper API; è uno strumento autonomo che legge una codebase, esegue modifiche su più file ed esegue comandi nel vostro ambiente locale. Ha introdotto il supporto a SKILL.md a dicembre 2025, inizialmente come funzionalità sperimentale.

I percorsi di discovery sono cambiati da quel lancio, il che è utile sapere se si sta seguendo una guida più vecchia. La documentazione attuale di OpenAI elenca .agents/skills nella directory di lavoro e nelle sue directory genitore per gli skill con scope di repository, $HOME/.agents/skills per quelli personali, e /etc/codex/skills per gli skill a livello di macchina. La posizione originale ~/.codex/skills è quella che vedrete ancora nella maggior parte dei README degli skill di terze parti. Uno skill può essere invocato esplicitamente digitando $ e scegliendo dalla lista, oppure può essere attivato implicitamente se un'attività corrisponde alla sua descrizione.

Il suo file di configurazione primario è ~/.codex/config.toml, e il suo set di istruzioni principale può essere personalizzato tramite un file chiamato AGENTS.md. Questo fornisce un punto di ingresso diverso per la personalizzazione rispetto al modello skill-centrico di Claude Code.

Quindi, Codex supporta SKILL.md? Sì, nativamente. Il formato del file è un cittadino di prima classe. La divergenza deriva dall'ambiente che fornisce per l'esecuzione di quel file.

Portabilità unidirezionale: cosa mostrano i nostri dati

Questo è il nocciolo della questione. Non abbiamo mai testato uno skill su Codex CLI. Non possiamo fornire un tasso di successo per Codex o un confronto diretto basato sui nostri dati di test. Affermare il contrario significherebbe inventare un dataset.

Ciò che possiamo fornire è uno sguardo onesto a un pattern specifico nei risultati dei nostri test su Claude Code. Dei 2090 skill che abbiamo testato, le nostre note mostrano che 47 di essi menzionano o presuppongono un ambiente Codex. Questi skill sono stati scritti per Codex, ma li abbiamo eseguiti in un ambiente Claude Code. Questo ci dà una visione unica e unidirezionale della portabilità.

I risultati per quei 47 skill sono:

• Superati: 11
• Setup: 34
• Falliti: 2

Questo racconta una storia chiara: un file SKILL.md scritto per Codex richiederà molto probabilmente una configurazione manuale per funzionare su Claude Code. Non perché il file non sia valido, ma perché le istruzioni dello skill si basano su strumenti o percorsi che non esistono nel nuovo ambiente.

Diamo un'occhiata a esempi specifici dal nostro catalogo:

• Generate 2D Map (Verdetto: Setup): Il README upstream dello skill dichiara esplicitamente che è per Codex/Grok ed elenca i percorsi di installazione ~/.codex/skills e ~/.grok/skills, non il ~/.claude/skills dichiarato nella sua descrizione. La sua pipeline principale necessita di una coppia di strumenti integrati per la generazione e la visualizzazione di immagini che Claude Code non possiede. Lo abbiamo testato sull'unico branch che non necessita di immagini — la costruzione di una mappa ortogonale Tiled come JSON — e lo skill ha eguagliato esattamente il modello base: array di tile identici al byte, metadati di spawn e uscita identici. Il file è stato caricato; la parte per cui valeva la pena installarlo non ha funzionato.

• Generate 2D Sprite (Verdetto: Setup): Questo skill ha lo stesso problema. Dipende strettamente da capacità di generazione di immagini fornite con Codex e Grok ma non con Claude Code. Può pianificare uno sprite sheet, ma non può eseguire il passo finale di produzione dell'arte.

• Ablation Planner (Verdetto: Setup): La meccanica principale di questo skill comporta il passaggio del lavoro di progettazione a uno strumento specifico di Codex. Quando eseguito nel nostro ambiente Claude Code, quello strumento non era disponibile. Il passo ha dovuto essere eseguito manualmente, che è la definizione di un verdetto 'setup'.

Al contrario, 11 di questi skill orientati a Codex sono stati superati senza problemi. Skill come Better Codex e PinMe Share hanno superato i nostri test su Claude Code. Entrambi portano il loro valore nel testo piuttosto che negli strumenti del fornitore. Better Codex è un overlay comportamentale puramente basato su prompt senza file o script esterni, e ha comunque superato il modello base in un'attività di parsing di configurazione, dove il modello di riferimento si rompeva silenziosamente su valori contenenti un segno di uguale. PinMe Share si installa da un singolo SKILL.md valido senza riferimenti pendenti, e il suo vantaggio è la conoscenza esatta di una comune CLI npm: ha emesso il comando di upload canonico e i passaggi di autenticazione richiesti, mentre il modello base ha indovinato il comando e saltato il login. Questa è la forma di uno skill portabile. Necessita di uno strumento che si può installare, non di uno strumento integrato fornito con l'agente di un fornitore.

Differenze chiave in sintesi

Un confronto diretto evidenzia i compromessi da considerare quando si sceglie tra codex cli o claude code per la programmazione con gli skill.

Caratteristica	Claude Code	Codex CLI
Percorso Skill	~/.claude/skills (personale), .claude/skills (progetto)	$HOME/.agents/skills (personale), .agents/skills (repo), /etc/codex/skills (macchina)
Config	settings.json, più CLAUDE.md per le istruzioni	~/.codex/config.toml, più AGENTS.md per le istruzioni
Sandboxing	Opt-in; le variabili d'ambiente ereditano dalla shell genitore	Attivo di default in workspace-write, rete disattivata se non abilitata
SKILL.md malformato	Fallisce il caricamento silenziosamente	(Comportamento non testato da noi)

Il compromesso della sandbox

La differenza più significativa negli ambienti di esecuzione è il comportamento predefinito della sandbox.

Codex CLI, secondo la sua documentazione, opera con una postura di sicurezza predefinita più restrittiva. Nella sua modalità workspace-write, l'accesso alla rete è disabilitato a meno che non lo si abiliti esplicitamente in config.toml. Le scritture sul file system sono limitate alla workspace corrente, e la politica di approvazione dell'agente prevede di default la richiesta di conferma prima di agire. Questo è un modello 'default-deny'.

Claude Code, come documentato da Anthropic, adotta un approccio diverso. Il sandboxing è qualcosa che si attiva piuttosto che disattivare, e anche quando è attivo la shell eredita di default l'ambiente del processo genitore. Ciò significa che se si hanno credenziali come AWS_ACCESS_KEY_ID esportate nella sessione del terminale, uno skill invocato da Claude Code può potenzialmente leggerle. Questo fa sì che gli skill che comunicano con servizi esterni o credenziali locali funzionino immediatamente, e pone su di voi l'onere di gestire tale esposizione.

Nessuno dei due approcci è intrinsecamente migliore; è un compromesso. Il modello di Codex dà priorità alla sicurezza di default, richiedendo potenzialmente più configurazione per far funzionare uno skill di rete. Il modello di Claude Code dà priorità alla funzionalità immediata, esponendo potenzialmente una parte maggiore dell'ambiente host. Uno skill che esegue una shell per chiamare un'API con curl potrebbe funzionare su Claude Code ma essere bloccato di default su Codex CLI.

La regola decisionale: giudicare l'ambiente, non il file

Quindi, Claude Code vs Codex CLI: quale usare per gli skill?

I nostri dati forniscono una risposta onesta, sebbene incompleta. Il formato del file SKILL.md in sé non è il fattore decisivo. Lo stesso file verrà caricato su entrambe le piattaforme. La vera decisione dipende dall'ambiente di esecuzione e dalle dipendenze degli skill che si desidera eseguire.

1. Verificare le dipendenze degli strumenti: Lo skill si basa su strumenti integrati e specifici dell'agente (come la generazione di immagini in Generate 2D Map)? In tal caso, non sarà portabile.
2. Verificare le dipendenze da CLI universali: Lo skill utilizza solo strumenti a riga di comando onnipresenti? Ha un'alta probabilità di essere portabile, come dimostrato dagli 11 skill orientati a Codex che hanno superato il test nel nostro ambiente Claude Code.
3. Considerare la preferenza per la sandbox: Preferite un sistema bloccato di default che richiede permessi espliciti (Codex CLI)? O preferite uno che funziona con meno attrito fin da subito ma eredita l'intero contesto del vostro ambiente (Claude Code)?

Non possiamo dichiarare un vincitore universale perché non abbiamo testato su entrambe le piattaforme. La scelta dipende dalle vostre esigenze specifiche e dalla vostra postura di sicurezza. Ciò che possiamo dire con certezza è che presumere che uno skill funzionerà solo perché il file SKILL.md è compatibile è un errore. L'ambiente è tutto.

Letture correlate: AGENTS.md vs Claude Skills copre l'altra metà della questione multi-strumento — il file di istruzioni che ogni agente legge prima di caricare qualsiasi skill. E se state scegliendo tra agenti per terminale per motivi diversi dagli skill, Claude Code vs Cursor analizza quel compromesso.

In SkillProof, il nostro valore consiste nell'eliminare questa incertezza per l'ecosistema di Claude Code. Noi facciamo i test così non dovete farli voi. Ogni verdetto 'pass' nel nostro catalogo rappresenta uno skill che abbiamo installato ed eseguito su Claude Code, su lavoro reale. Per un punto di partenza curato, i nostri pacchetti di skill basati sul ruolo raccolgono ciascuno dieci skill testati per una funzione lavorativa — sviluppatore, revisione della sicurezza, marketing, design e altri quattro — a $10 per pacchetto, con il verdetto di ogni skill dichiarato in anticipo.