Passa al contenuto principale

SKILL.md: lo standard aperto cross-agent

Intermedio

Per qualche anno ogni coding agent ha avuto il suo file: .cursorrules, CLAUDE.md, i system prompt di Codex, le istruzioni di Gemini, una dozzina d'altri. Poi Anthropic ha silenziosamente trasformato il suo formato interno Skills in una specifica aperta — e nel giro di 48 ore i più grandi agenti del mondo leggevano i file l'uno dell'altro. Oggi una singola cartella chiamata code-reviewer/ con dentro un SKILL.md gira senza modifiche in Claude Code, Codex CLI, ChatGPT, Gemini CLI, Junie, Kiro, Goose e Cursor. È quanto di più vicino a una presa condivisa il mondo degli agenti abbia mai avuto.

Questa pagina è la guida pratica sul campo: cos'è davvero lo standard a livello di byte, l'unico trucco intelligente (progressive disclosure) che rende economico installare 100 skill, esattamente quali campi rompono la portabilità appena li tocchi, il quadro onesto sulla sicurezza, e una skill portabile da copiare-incollare e mettere in produzione oggi.

What you'll learn
  • Capire cos'è SKILL.md al livello di formato file — campi obbligatori, campi opzionali, layout della cartella
  • Capire la progressive disclosure: perché 100 skill costano ~10K token allo startup, non 100× il corpo
  • Conoscere le estensioni proprietarie precise che rompono silenziosamente la portabilità tra agenti
  • Scrivere una skill che gira senza modifiche in Claude Code, Codex CLI e Gemini CLI
  • Valutare onestamente il compromesso di sicurezza prima di installare skill da qualunque marketplace

Cos'è davvero lo standard​

Tolto il marketing, lo standard aperto Agent Skills è abbastanza piccolo da tenere a mente:

  • Una cartella il cui nome è il name della skill
  • Un SKILL.md obbligatorio al suo interno — frontmatter YAML, poi corpo Markdown
  • Sottocartelle opzionali: scripts/ (eseguibili che la skill può lanciare), references/ (documenti che la skill può caricare on demand), assets/ (template, immagini, file di prompt) e — aggiunta dopo — agents/ per configurazioni proprietarie opt-in

Questa è tutta la superficie. Due campi frontmatter obbligatori fanno la maggior parte del lavoro:

  • name — fino a 64 caratteri, minuscole-con-trattini, deve coincidere col nome della cartella
  • description — fino a 1.024 caratteri, la frase che l'agente usa per decidere se caricare questa skill per il task corrente

Tutto il resto — license, compatibility, metadata e ancora sperimentale allowed-tools — è opzionale e viene ignorato senza problemi dai tool che non lo capiscono. I corpi sono Markdown; la convenzione della community è tenerli sotto ~5.000 token, e nella pratica le skill reali fanno così: la mediana sul più grande marketplace è circa 1.414 token, con il 90% sotto 3.935 token.

L'unico trucco intelligente: progressive disclosure​

Il motivo per cui SKILL.md scala non è il formato file — è come gli agenti lo caricano. Tutti gli agenti conformi implementano tre livelli:

Guided walkthrough1 of 3
  1. L'agente percorre la cartella delle skill e legge solo il frontmatter di ogni SKILL.md. Circa 100 token per skill. Installa 100 skill e hai speso ~10K token di contesto prima del primo prompt — meno di un singolo system message lungo.

È per questo che la specifica limita così stretta la description e la tratta come campo di primo livello: è l'unico testo che il modello vede quando sceglie se attivare la skill. Una description vaga è il motivo singolo più comune per cui una skill che "dovrebbe funzionare" non parte mai.

:::tip Scrivi la description per ultima, e riscrivila Una volta che il corpo della skill è solido, torna indietro e tratta la description come copy pubblicitario. Ha un unico lavoro: aiutare il modello a riconoscere la forma di un task che questa skill dovrebbe gestire. "Reviews pull requests" è brutta. "Reviews a PR diff for logic bugs, missing tests, and violated project conventions; use whenever the user asks for a review, code review, or 'look at this PR'" è buona. :::

La cartella universale​

Ogni agente conforme si aspetta lo stesso layout. Questo funziona ovunque:

code-reviewer/
├── SKILL.md          # obbligatorio — le istruzioni che l'agente legge
├── scripts/          # opzionale — eseguibili che la skill può invocare
│   └── run-linters.sh
├── references/       # opzionale — documenti lunghi caricati on demand
│   └── style-guide.md
├── assets/           # opzionale — template, file di prompt, snippet
│   └── pr-comment-template.md
└── agents/           # opzionale — PROPRIETARIO, solo opt-in
    └── openai.yaml   # ignorato da ogni agente non-Codex

La sottocartella agents/ è la valvola di sicurezza dello standard: permette ai vendor di spedire estensioni senza contaminare il nucleo portabile. Un file in agents/openai.yaml è specifico di Codex e ogni altro agente lo ignorerà. Usala quando ti serve potenza extra; sappi che ti costa portabilità.

Cosa viaggia davvero vs cosa silenziosamente non lo fa​

L'intera specifica è pensata per la portabilità, ma le skill reali nel mondo hanno tre modi di fallire.

Cosa usiPortabile?Perché
name, description, corpo Markdown✅ SìNucleo della spec. Ogni agente conforme li legge in modo identico.
scripts/, references/, assets/ richiamati dal corpo✅ SìIl layout della cartella è parte della spec; gli agenti li leggono quando il corpo lo dice.
license, metadata✅ Sì (ignorati senza problemi)Campi opzionali — gli agenti che non li supportano li saltano senza errore.
Frontmatter allowed-tools⚠️ ParzialeMarcato sperimentale nella spec; la sintassi tra agenti non è standardizzata. Claude Code ne onora una forma, Codex CLI un'altra, gli altri lo ignorano del tutto.
Lista when_to_use di Claude Code❌ Solo ClaudeIgnorata silenziosamente da Codex, Gemini CLI e chiunque altro.
Flag context: fork di Claude Code per subagent❌ Solo ClaudeSemantica di esecuzione dei subagent non portabile — il comportamento del modello altrove è diverso.
Estensioni agents/openai.yaml❌ Solo CodexVendor-specific per design. Portabili perché gli altri agenti le ignorano.

La lezione è netta: resta su name + description + corpo Markdown + le tre sottocartelle opzionali e la tua skill gira ovunque. Tocca qualunque campo frontmatter oltre ai due centrali e stai costruendo per un solo agente. È una scelta legittima — alcune skill lo richiedono davvero — ma fallo con intenzione, non perché hai copiato un template.

Come funziona davvero l'attivazione (per agente)​

La spec standardizza il file, non la decisione. Ogni agente esegue la propria logica di attivazione sulle description lette allo startup:

  • Claude Code confronta l'interpretazione del turno corrente con description e (se presente) la lista when_to_use specifica di Claude; l'attivazione è una decisione del modello, non una regola a keyword.
  • Codex CLI usa la stessa attivazione basata su description, con override opzionali in agents/openai.yaml.
  • Gemini CLI carica anch'esso le description allo startup e lascia scegliere a Gemini; il comportamento segue le euristiche di selezione tool di Gemini.
  • Cursor, Junie, Kiro, Goose implementano tutti l'attivazione basata su description con lievi variazioni di peso.

Conseguenza pratica: una skill che non parte mai su un agente ma funziona su un altro ha quasi sempre un problema di description, non di corpo. Riscrivi la description in modo che descriva la forma della richiesta dell'utente, non gli interni della skill, e il tasso di attivazione sale su ogni agente insieme.

Un SKILL.md portabile da copiare​

Ecco una skill di code review minima e davvero portabile. Mettila in ~/.agents/skills/code-reviewer/SKILL.md e girerà in Claude Code, Codex CLI, ChatGPT e Gemini CLI senza modifiche.

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

Ogni riga di quella skill gira su ogni agente conforme. Niente nel frontmatter è vendor-scoped. Il corpo usa intestazioni Markdown semplici che qualunque agente sa parsare.

Ora confrontala con una variante non portabile — sottilmente, è solo per Claude:

Variante solo Claude (non usarla se vuoi portabilità)

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

Tre cose rompono la portabilità in un colpo: when_to_use (solo Claude Code), context: fork (semantica subagent di Claude Code) e allowed-tools (sperimentale, non onorato coerentemente). Codex leggerà la description come "Reviews a diff or pull request" — così vaga che praticamente non si attiverà mai — e ignorerà il resto.

Il quadro sulla sicurezza (sii onesto con te stesso)​

La verità scomoda sull'installare skill da qualunque marketplace: una skill è istruzione arbitraria data a un agente molto capace che gira nel tuo ambiente coi tuoi permessi. Lo standard non specifica code signing, né sandboxing, né review obbligatoria, né modello di permessi a runtime. È per design una spec di file di testo, non una spec di sicurezza.

I numeri concreti, da analisi indipendenti su grandi cataloghi pubblici di skill (verifica alla fonte prima di citarli):

  • Circa una skill pubblica su tre contiene almeno un difetto rilevante per la sicurezza — istruzioni shell troppo ampie, secret hardcoded, chiamate a URL non fidati o step di bootstrap in stile curl | sh.
  • Un insieme più piccolo ma non nullo di skill è stato marcato come apertamente malevolo — tentativi di esfiltrazione, raccolta credenziali od operazioni distruttive.
  • Le skill ereditano ciò che eredita l'agente. Se il tuo agente può leggere ~/.ssh/, può farlo anche ogni skill che installi.

Difese pratiche che funzionano davvero:

Guided walkthrough1 of 4
  1. È Markdown. Ti prende un minuto. Se la description dice 'formats prose' e il corpo contiene un `curl` verso un URL che non riconosci, quello è il momento in cui ti fermi.

Per un approfondimento su come le skill vengono compromesse e cosa controllare, vedi Vetting delle Agent Skills e Coding agent sotto attacco.

Quando scrivere una skill vs quando basta un prompt​

I nuovi maintainer di un catalogo di skill spesso ne producono troppe. Una regola utile:

  • Prompt per un task una tantum o per una forma che userai in un solo progetto. Le skill portano un costo di startup — anche se piccolo — e affollano il budget delle description.
  • Scrivi una skill quando le stesse istruzioni si applicano a molte chat o progetti (code review, scrittura commit-message, generazione changelog, estrazione fatture) e la description sarebbe non ambigua. Se non riesci a scrivere una description netta, la skill non partirà comunque in modo affidabile.
  • Passa a un subagent quando il task richiede il proprio set di tool, la propria scelta di modello o vera parallelismo. Le skill istruiscono il modello principale; i subagent girano separatamente. Vedi Subagent.

Letture correlate​

Verifica la presa​

Check yourself

0/4
  1. Installi 100 skill. Quanti token costano allo startup dell'agente le loro description, all'incirca?
  2. Quale di questi campi frontmatter rompe silenziosamente la tua skill su Codex CLI e Gemini CLI anche se funziona in Claude Code?
  3. Una skill che hai scritto parte in modo affidabile su Claude Code ma quasi mai su Codex CLI. Qual è la cosa a più alta leva da sistemare per prima?
  4. Perché la postura di sicurezza delle Agent Skills è fondamentalmente più debole, ad esempio, di un pacchetto npm con lockfile e strumenti di audit?

Fonti e approfondimenti​