Skill degli agenti AI: quando crearne una e come

Che cos'è una skill, senza farne un glossario

Una skill è una procedura impacchettata per un agente: istruzioni, metadati, eventuali script, riferimenti e asset. L'idea è semplice: invece di mettere tutto in CLAUDE.md o AGENTS.md, lasci all'agente una descrizione breve e fai caricare il contenuto completo solo quando il task lo richiede.

• Claude Code descrive le skill come SKILL.md con istruzioni, invocabili direttamente o automaticamente quando rilevanti.
• Codex usa le skill come formato per workflow riusabili e le carica con progressive disclosure.
• Lo standard Agent Skills definisce una cartella con SKILL.md, name, description e file opzionali.
• La differenza rispetto a MCP è netta: una skill spiega una procedura, MCP collega sistemi esterni.

Il gate decisionale

Prima di creare una skill, chiediti se stai trasformando una procedura reale o solo spostando testo da un file all'altro. Una skill ha senso quando la stessa sequenza torna spesso, quando gli errori dell'agente sono prevedibili e quando non vuoi pagare quel contesto in ogni sessione.

• Sì alla skill: procedura ripetuta tra sessioni, repo o clienti.
• Sì alla skill: passaggi ordinati, esempi, output atteso e controlli finali.
• Sì alla skill: materiale lungo che serve solo in alcuni task.
• No alla skill: regola sempre valida, come stile codice o comando test obbligatorio.
• No alla skill: accesso a un sistema esterno, dove serve MCP o una CLI.

Come si crea in pratica

Il formato portabile è una directory con un file SKILL.md. Per compatibilità tra agenti conviene includere sempre name e description nel frontmatter, anche se alcuni client sono più permissivi. La description è il pezzo più importante: decide quando l'agente capisce che la skill è rilevante.

• Claude Code: skill personali in ~/.claude/skills/<nome>/SKILL.md e skill di progetto in .claude/skills/<nome>/SKILL.md.
• Codex: skill utente in ~/.agents/skills e skill di repository in .agents/skills lungo il percorso fino alla root.
• Agent Skills standard: SKILL.md richiesto, scripts, references e assets opzionali.
• Test minimo: chiedi un task che dovrebbe attivarla, poi uno che non dovrebbe attivarla.

my-review-skill/
├── SKILL.md
├── references/
│   └── review-checklist.md
└── scripts/
    └── collect-diff.sh

---
name: my-review-skill
description: Reviews code changes against the team checklist. Use when the user asks for a PR review, risk review, or pre-commit check.
---

## Goal

Review the current code changes and return concise findings first.

## Steps

1. Read references/review-checklist.md.
2. Inspect the current diff.
3. Prioritize bugs, regressions, security risks, and missing tests.
4. Report only actionable findings with file and line references.
5. If there are no findings, say that clearly and list residual test risk.

Esempi utili senza trasformarla in directory

Le skill migliori non sono una collezione di nomi alla moda. Sono procedure che tolgono attrito a lavori ricorrenti. Parti dal problema che vuoi rendere ripetibile, non dalla voglia di avere una skill in più.

• Review di codice con convenzioni del team, severità e formato findings.
• Generazione di report ricorrenti da issue, changelog e metriche.
• Pipeline editoriale con fonti, controlli SEO e stile di pubblicazione.
• Checklist di release con build, test, changelog e note di deploy.
• Audit di accessibilità o sicurezza con criteri sempre uguali.
• Preparazione di documenti o presentazioni con template e struttura fissa.

Errori comuni

Una skill troppo generica è quasi invisibile: l'agente non sa quando usarla, oppure la usa sempre. Una skill troppo lunga diventa invece un nuovo contenitore disordinato. Trattala come una piccola interfaccia operativa: nome chiaro, trigger chiaro, passi chiari, output chiaro.

• Description vaga: aiuta con il progetto non dice quando attivarla.
• Scope enorme: una skill per fare tutto diventa una seconda memoria generale.
• Duplicazione: copiare AGENTS.md dentro una skill crea divergenze.
• Script senza errori leggibili: l'agente non capisce perché fallisce.
• Assenza di esempi: l'agente deve inventare formato e criteri ogni volta.

Come si collega agli altri pezzi del contesto

Le skill stanno dopo le istruzioni di progetto e accanto agli strumenti. CLAUDE.md o AGENTS.md dicono all'agente come comportarsi sempre. MCP o CLI gli danno capacità operative. La skill coordina una procedura: decide quali passi seguire, quali strumenti usare e quale output consegnare.

• Se la regola vale sempre, mettila nelle istruzioni di progetto.
• Se serve collegare un sistema esterno, valuta MCP o CLI.
• Se serve ripetere un workflow con criteri e controlli, crea una skill.
• Se il workflow usa molte fonti interne, la skill può indicare quali riferimenti caricare solo al bisogno.

Quante skill servono davvero

Poche e buone. Ogni skill aggiunge almeno nome e descrizione alla fase di discovery; Codex documenta anche un budget per evitare che la lista affolli il contesto iniziale. Se una skill non viene usata, non è neutra: rende più difficile scegliere quella giusta.

• Tieni skill separate solo quando hanno trigger e output diversi.
• Unisci skill che sono varianti dello stesso workflow.
• Rimuovi o archivia skill non usate.
• Rendi manuali le skill rischiose o distruttive, invece di lasciarle invocare automaticamente.

Domande frequenti