AGENTS.md vs CLAUDE.md vs skill: cosa va dove

Ecco AGENTS.md: un semplice file markdown nella root del repository che dice agli agenti di coding come lavorare nel tuo progetto: come buildarlo, come lanciare i test, quali convenzioni seguire, cosa non toccare. Nessuno schema, nessuna sezione obbligatoria, nessun registro. Lo standard intero sta in una frase: metti un file chiamato AGENTS.md nel tuo repo, e gli agenti che supportano la convenzione lo leggeranno prima di toccare il tuo codice.

Molti lo chiamano "il README per gli agenti", e il paragone regge. Un README spiega il tuo progetto agli umani appena arrivati. AGENTS.md lo spiega a un software appena arrivato. La differenza è che l'agente seguirà davvero le istruzioni, quindi quelle vaghe costano soldi veri in token sprecati e modifiche sbagliate.

Da SkillProof testiamo tool per agenti di mestiere, e abbiamo visto questo file passare da progetto collaterale di OpenAI alla cosa più vicina a uno standard condiviso che il coding agentico abbia mai avuto. Questo articolo copre come si relaziona a CLAUDE.md e ai dialetti degli altri tool, e dove si collocano le skill, perché risolvono un problema diverso da quello che quasi tutti pensano.

Cos'è AGENTS.md, e chi lo legge davvero

La convenzione è nata dal team Codex di OpenAI a metà 2025 ed è stata rapidamente co-firmata da Jules di Google, Cursor, Factory, Amp e altri. L'idea di fondo era semplice: ogni vendor di agenti si era inventato il proprio file di istruzioni, e le root dei repository si stavano riempiendo di markdown quasi identici indirizzati a robot diversi. AGENTS.md ha proposto un unico filename che tutti leggono.

L'adozione da allora è stata reale ma disomogenea. Ecco la mappa onesta, così come la vediamo a metà 2026:

Tool	Legge AGENTS.md	Dialetto nativo
OpenAI Codex	Sì, nativo	Nessuno, AGENTS.md è il formato
GitHub Copilot (coding agent, VS Code)	Sì	.github/copilot-instructions.md
Cursor	Sì	.cursor/rules/*.mdc
Google Jules	Sì, nativo	Nessuno
Gemini CLI	Sì, via config	GEMINI.md
Claude Code	Non nativamente	CLAUDE.md
Zed	Sì	Nessuno
Amp	Sì	Nessuno
Aider	No	CONVENTIONS.md
Windsurf	No	.windsurf/rules/

In questa tabella saltano all'occhio due cose. Primo, la colonna dei "sì" è lunga e continua ad allungarsi; quando esce un nuovo agente nel 2026, il supporto ad AGENTS.md è di solito già nelle note di lancio. Secondo, i dialetti non sono spariti. Copilot legge ancora il proprio file di istruzioni, Cursor ha ancora le rules con glob e trigger mode che AGENTS.md non può esprimere, e Claude Code, il tool con cui passiamo più tempo, vuole ancora un CLAUDE.md.

Quindi la situazione pratica è questa: AGENTS.md è la lingua franca, i dialetti sono dove vive il potere specifico di ogni tool, e qualsiasi team che usa più di un agente ha bisogno di una policy per tenerli sincronizzati. Questa policy è il cuore di questo articolo.

Cosa mettere nel file è meno controverso di quanto lo sia stato il nome del file. I file AGENTS.md che funzionano coprono comandi di setup e build, come lanciare i test, note di stile del codice che il linter non può cogliere, e confini architetturali ("la logica dei pagamenti vive in packages/billing, non mettetela da nessun'altra parte"). I file che non funzionano suonano come dichiarazioni d'intenti. Un agente non ha bisogno di sapere che tieni al codice pulito. Ha bisogno del comando che verifica se il codice è pulito.

AGENTS.md vs CLAUDE.md

Questi due file fanno praticamente lo stesso lavoro per lettori diversi. Entrambi sono file di istruzioni a livello di progetto. Entrambi vengono caricati nel contesto all'inizio di una sessione. Entrambi dovrebbero essere brevi, perché ogni riga costa token a ogni richiesta. Se hai già scritto un buon CLAUDE.md, sai già come scrivere un buon AGENTS.md, e i nostri consigli in CLAUDE.md best practices valgono quasi riga per riga.

Le differenze vale la pena conoscerle prima di unificarli:

Pubblico. CLAUDE.md è letto da un solo tool esattamente. Questo significa che può tranquillamente fare riferimento a meccanismi specifici di Claude: skill, hook, subagent, server MCP, impostazioni dei permessi. Un AGENTS.md che dice "usa la skill systematic-debugging prima di proporre un fix" è rumore per Codex e Copilot, che non hanno idea di cosa sia una skill.

Gerarchia e import. Claude Code unisce i file CLAUDE.md provenienti da più livelli (utente globale, root del progetto, sottocartelle) e supporta import @path/to/file al loro interno. Anche AGENTS.md supporta il nesting, con il file più vicino che ha la precedenza, ma la sintassi di import è propria di Claude.

Applicazione. Nessuno dei due file viene fatto rispettare in modo coercitivo. Sono entrambi suggerimenti a un modello linguistico. Tutto ciò che deve accadere ogni volta appartiene a un hook o alla CI, non a uno di questi due file. Questo delude allo stesso modo gli utenti di tutti i tool.

Se il tuo team usa Claude Code insieme a qualunque altra cosa, ti servono entrambi i file, e la modalità di fallimento è ovvia: due file che dicono quasi la stessa cosa, che divergono nel tempo finché un agente non segue quello superato. Due schemi lo evitano, e li abbiamo testati entrambi.

Il symlink. Rendi AGENTS.md il file vero e fai puntare CLAUDE.md a lui:

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code segue il symlink e legge il contenuto come se fosse il proprio file. Questa è l'opzione a manutenzione zero, ed è quella giusta quando non hai nulla di specifico per Claude da dire. Il suo limite è l'identità esatta: entrambi i lettori ricevono ogni parola, comprese quelle rilevanti solo per l'altro.

Il wrapper sottile. Tieni AGENTS.md come fonte condivisa, e fai di CLAUDE.md un piccolo file che lo importa e aggiunge righe solo per Claude:

# CLAUDE.md
@AGENTS.md

## Claude-specific
- Use the git-workflow skill for commits and PRs.
- Never edit files under infra/ without asking.

Questo è quello che usiamo nei nostri repo. I fatti condivisi vivono in un solo posto, gli extra di Claude vivono dove solo Claude li vedrà, e un diff ad AGENTS.md aggiorna tutti i tool nello stesso momento. Lo stesso schema funziona al contrario per gli altri dialetti: tieni .github/copilot-instructions.md e i file di rule di Cursor a poche righe che rimandano ad AGENTS.md per tutto ciò che serve a entrambi i tool. Abbiamo confrontato questi dialetti nel dettaglio in Claude skills vs Cursor rules e Claude skills vs Copilot instructions.

Un avvertimento dai nostri test: qualunque schema tu scelga, sceglierne uno solo. I repo che portano avanti un CLAUDE.md completo e un AGENTS.md completo con contenuti modificati in modo indipendente sono lo scenario da deriva, solo con qualche passaggio in più.

AGENTS.md vs skill: livelli completamente diversi

Questo è il confronto che le persone cercano davvero, ed è quello costruito su un errore di categoria. AGENTS.md e le skill non sono formati in competizione. Si collocano su livelli diversi dello stack e rispondono a domande diverse.

AGENTS.md risponde a: cosa dovrebbe sapere qualsiasi agente su questo progetto? Sono fatti su un luogo. Viaggia con il repository, si applica a qualunque agente si presenti, e non dice nulla su come l'agente svolge il proprio lavoro al di là delle regole locali.

Una skill risponde a: come dovrebbe questo agente eseguire questo tipo di task? È un comportamento, impacchettato in una cartella con un SKILL.md, caricato su richiesta quando il task corrisponde alla sua descrizione. Viaggia con te, non con il repo. Installa una skill di debugging una volta e funzionerà in ogni progetto che apri, che quel progetto abbia mai sentito parlare di te o no. Abbiamo trattato i meccanismi in What are Claude skills?, ma il modello di caricamento è la differenza chiave: il contenuto di AGENTS.md resta nel contesto per l'intera sessione, mentre una skill costa circa un centinaio di token di metadati finché un task non la attiva.

Ecco lo stack completo così come lo disegniamo sulle lavagne:

Livello	Vive in	Ambito	Caricato	Domanda a cui risponde
AGENTS.md	Root del repo	Il progetto, qualsiasi agente	Ogni sessione	Cos'è questo posto?
Dialetto del tool (CLAUDE.md, rules)	Repo o config utente	Il progetto, un tool	Ogni sessione	Cosa dovrebbe fare qui questo tool?
Skill	~/.claude/skills/ o .claude/skills/	Un agente, qualsiasi progetto	Su richiesta	Come si fa questo tipo di task?
Server MCP	Config del tool	Una macchina o un team	Definizioni dei tool sempre nel contesto	A cosa può accedere l'agente?

Leggilo dall'alto in basso come capacità crescente e portabilità decrescente. Il file standard è universale e "stupido". Il dialetto è legato al tool e leggermente più intelligente. Le skill sono ricche di comportamento ma attualmente legate all'agente. MCP è infrastruttura viva con credenziali e processi.

Un esempio concreto rende ovvio il confine. "Esegui pnpm test --filter=changed prima di committare" è una riga da AGENTS.md: è un fatto sul tuo repo, vero per qualsiasi agente. "Quando fai debugging, riproduci il fallimento prima di proporre un fix, e non dichiarare mai che un fix funziona senza rieseguire il test fallito" è una skill, e di fatto è una che abbiamo testato e catalogato: systematic-debugging. Non ha nulla a che fare con un repo specifico. Metterla in AGENTS.md significa copiarla in ogni progetto e pagarne il costo in token in ogni sessione, comprese quelle in cui nessuno sta facendo debugging.

La regola pratica che diamo ai team: se copieresti una riga in un secondo repo senza modificarla, non è contesto di progetto, è comportamento, e appartiene a una skill. Se una riga ha senso solo in questo repo, è contesto, e appartiene ad AGENTS.md.

La strategia per i team che usano più tool AI

La maggior parte dei team con cui parliamo nel 2026 non usa un solo agente. Un mix tipico è Claude Code per i lavori più pesanti, Copilot nell'editor, e Cursor sulle macchine di qualche irriducibile. Ecco la configurazione che sopravvive al contatto con questa realtà:

1. Scrivi AGENTS.md come fonte di verità. Un file, nella root del repo, gestito come codice. Metti dentro ogni fatto di cui qualsiasi agente ha bisogno: comandi, convenzioni, confini, avvertimenti. Rivedi le modifiche in PR, perché un'istruzione sbagliata qui trae in inganno ogni agente che il tuo team usa.

2. Tieni i dialetti sottili. CLAUDE.md importa AGENTS.md e aggiunge solo righe specifiche per Claude. Le istruzioni di Copilot e le rules di Cursor ricevono lo stesso trattamento: un puntatore più tutto ciò che genuinamente non può essere espresso nel file condiviso. Il nostro test per "abbastanza sottile" è brutale: se un file di dialetto supera una schermata, qualcosa al suo interno probabilmente appartiene ad AGENTS.md o a una skill.

3. Metti il comportamento riutilizzabile nelle skill. Disciplina di debugging, abitudini di commit e PR, standard di scrittura dei test, formattazione dei documenti. Queste cose non appartengono a nessun file per-repo perché non sono per-repo. Installale una volta per agente e ti seguiranno ovunque. Le nostre scelte testate per il lavoro di coding sono raccolte in the best coding skills, e git-workflow è quella che installeremmo per prima in qualsiasi team che tiene all'igiene dei commit.

4. Applica le regole con hook e CI, non con la prosa. Tutto ciò che deve accadere il 100% delle volte non può vivere in un file markdown letto da un sistema probabilistico. La formattazione al salvataggio è un hook. I test prima del merge sono CI. I livelli markdown servono per il giudizio, non per l'applicazione forzata.

Questa struttura ha una proprietà che vale la pena nominare: ogni livello cambia al proprio ritmo. AGENTS.md cambia quando cambia il progetto, le skill cambiano quando cambia il mestiere del tuo team, e nessun agente legge nulla indirizzato a un agente diverso.

Vincerà uno standard unico?

La nostra opinione, indossando il cappello da osservatori di standard: il livello dei file convergerà, quello del comportamento no.

Il livello dei file converge perché gli incentivi puntano tutti nella stessa direzione. Un file di contesto ha una superficie ridotta, i vendor guadagnano compatibilità al costo di un controllo sul nome del file, e i proprietari dei repo sono visibilmente stanchi della proliferazione di file di istruzioni. Ci aspettiamo prima o poi un supporto nativo ad AGENTS.md in Claude Code, perché la pressione è pubblica e il costo di supportarlo è una semplice ricerca di file. Quando succederà, lo schema del symlink descritto sopra diventerà un'operazione a costo zero che potrai eliminare.

Il livello del comportamento è tutta un'altra storia. Meccanismi simili alle skill stanno spuntando ovunque: le skill di Claude, le rule mode di Cursor, i prompt file di Copilot, varie funzionalità "playbook" sparse tra agenti minori. Fanno rima tra loro, ma ciascuno codifica le proprie idee di vendor su come attivarsi e delimitare l'ambito. Il trigger description e il caricamento progressivo di una skill si mappano su un glob di rule di Cursor più o meno come una sinfonia si mappa su una suoneria. I formati di comportamento sono dove i vendor si differenziano, quindi hanno tutte le ragioni per continuare a divergere.

Ed ecco la parte che i vendor non mettono nei post di lancio: la portabilità del formato non è portabilità della qualità. Un file di comportamento non testato fallisce allo stesso modo su ogni tool che lo carica. Si attiva quando non dovrebbe, oppure non si attiva mai. Circa metà delle skill della community che scarichiamo da GitHub non supera il nostro primo passaggio di test, e le cause del fallimento sono indipendenti dal formato: trigger description vaghe, e istruzioni che l'autore non ha mai verificato su un tool reale. Abbiamo approfondito questo schema in why half of Claude skills don't work, e tutto ciò che c'è scritto si applica a qualunque cosa il tuo altro agente chiami la propria versione delle skill. Uno standard convergente ci darebbe un solo filename e lo stesso vecchio tasso di difetti.

Quindi: standardizza i tuoi fatti, perché l'ecosistema si sta standardizzando insieme a te. Poi sii esigente sui tuoi comportamenti, perché nessuno sta standardizzando la qualità.

FAQ

Claude Code legge AGENTS.md?

Non nativamente, a metà 2026. Claude Code cerca CLAUDE.md. Le soluzioni standard sono un symlink (ln -s AGENTS.md CLAUDE.md) oppure un CLAUDE.md sottile che importa il file condiviso con @AGENTS.md. Entrambe funzionano; la versione con import ti dà anche un posto per le istruzioni esclusive di Claude.

AGENTS.md dovrebbe sostituire il mio CLAUDE.md?

Sostituiscine il contenuto, tieni il file. Sposta tutto ciò che è indipendente dal tool in AGENTS.md, poi riduci CLAUDE.md a un import più righe specifiche per Claude su skill, hook e permessi. Cancellare del tutto CLAUDE.md ha senso solo con l'approccio del symlink, dove i due sono letteralmente gli stessi byte.

Posso mettere istruzioni simili a skill in AGENTS.md invece di installare le skill?

Puoi, e per un singolo repo piccolo va bene. I costi emergono su scala: le istruzioni si caricano in ogni sessione, rilevanti o no, e non ti seguono in altri progetti. Anche gli altri agenti che leggono il file ricevono indicazioni di comportamento scritte per Claude. Il comportamento che riutilizzeresti tra i repo appartiene a una skill.

Quanto dovrebbe essere lungo un AGENTS.md?

Abbastanza corto che ogni riga giustifichi il proprio costo di contesto. La maggior parte di quelli buoni che abbiamo revisionato sono tra le 30 e le 80 righe. Se il tuo è di qualche centinaio, probabilmente porta con sé contenuto di comportamento che appartiene alle skill, o materiale di riferimento che dovrebbe essere un documento collegato che l'agente legge su richiesta.

I file AGENTS.md nelle sottocartelle funzionano?

Sì, la convenzione supporta il nesting: il file più vicino al codice che si sta modificando vince per quell'area. I monorepo lo usano per dare a ogni package i propri comandi di build e test. Tieni il file di root per i fatti validi su tutto il repo e sposta le specifiche di package più in basso. Claude Code applica la stessa logica del file più vicino a CLAUDE.md, quindi anche lo schema del wrapper si annida in modo pulito.