Skill, metodi e framework

Approfondimento · AI

Skill, metodi e framework

Una skill è un modo per impacchettare una procedura: non un prompt più lungo, ma un piccolo manuale che l’agente apre solo quando serve. La stessa idea sta dietro a Superpowers, Caveman e a molti framework che promettono di rendere un agente più disciplinato.

In breve. Una skill è conoscenza procedurale scritta una volta e riusata molte. Costa poco finché non si attiva, ma può eseguire codice: trattala come codice di terzi, non come una nota a margine.

Che cos’è una skill

Quattro cose vengono spesso confuse. Una skill è conoscenza procedurale: spiega come fare un compito, con quali controlli e in quale formato. Un tool è una funzione che esegue un’azione. Un server MCP è il protocollo con cui un’applicazione espone tool e risorse. Un agente è il ciclo che decide cosa fare e quando.

Skill Tool Server MCP Agente
Cos’è Procedura scritta in Markdown Funzione eseguibile Contratto per esporre capacità Ciclo di decisione e azione
Chi la usa Il modello, quando si attiva Il modello o il codice Un host con i suoi client Il modello, con tool e regole
Unità di riuso Cartella versionabile Firma e comportamento Server e sue primitive Configurazione e prompt
Rischio principale Attivazione sbagliata, script fragili Effetti collaterali Permessi e injection Loop, costo, autonomia

Le Agent Skills sono uno standard aperto: la specifica è pubblica e un numero crescente di client le legge. Il formato è volutamente semplice — una cartella con un file SKILL.md e, se serve, script e riferimenti — perché il valore non è nella tecnologia, ma nel fatto che una procedura possa essere letta, revisionata e spostata da uno strumento all’altro.

La portabilità è il vero argomento a favore dello standard. Se una procedura è scritta come skill, può essere spostata da un client all’altro senza riscriverla; se è scritta come prompt dentro un prodotto, resta lì. Non è una garanzia assoluta — i client interpretano i dettagli in modo diverso — ma è molto meglio di un formato proprietario.

C’è anche un vantaggio economico, oltre che organizzativo. Cento skill caricate come metadati costano circa 10.000 token in tutto, una volta; cento prompt completi costerebbero il loro contenuto a ogni chiamata. Il risparmio però si paga in latenza di attivazione e in precisione: se la description è ambigua, il modello apre la skill sbagliata e il risparmio diventa un errore.

La differenza con un prompt è il momento del caricamento. Un prompt entra nel contesto a ogni chiamata; una skill entra solo quando il modello decide che serve, e solo nella parte necessaria. È la stessa idea dei manuali di officina: non li leggi tutti, apri la pagina giusta.

Anatomia e disclosure progressiva

Una skill è una directory. Il nome della directory è il nome della skill; dentro c’è un file di istruzioni e, se servono, materiali di supporto.

mia-skill/
├── SKILL.md          # metadati e istruzioni
├── scripts/          # logica deterministica
├── references/       # dettagli da consultare
└── assets/           # modelli e file statici

Il frontmatter YAML dichiara i metadati. I limiti non sono decorativi: sono ciò che permette a un client di caricare cento skill senza esaurire il contesto.

Campo Obbligatorio Limite Note
name Sì 64 caratteri Minuscole, numeri e trattini; niente trattini iniziali, finali o consecutivi; deve coincidere con il nome della directory.
description Sì 1.024 caratteri Dice cosa fa e quando usarla. È il testo che decide l’attivazione.
license No — Utile per la distribuzione e per chi deve approvare.
compatibility No 500 caratteri Requisiti di ambiente, dipendenze, versioni.
metadata No — Coppie chiave-valore libere: proprietario, versione, contatti.
allowed-tools No — Sperimentale: limita i tool disponibili quando la skill è attiva.

Il caricamento avviene in tre fasi. All’avvio il client legge solo name e description di tutte le skill: circa 100 token per skill. Quando una skill si attiva, carica il corpo del SKILL.md, per il quale la specifica consiglia meno di 5.000 token e meno di 500 righe. Solo se il compito lo richiede, carica i file in scripts/, references/ e assets/. Questa è la disclosure progressiva: paghi il dettaglio solo quando ti serve.

La description è il campo più difficile e il più importante. Deve contenere due cose insieme: cosa fa la skill e in quali situazioni va usata. “Gestisce report” è troppo vago; “Prepara il report settimanale delle vendite dai dati esportati” dice cosa, ma non quando. Aggiungi le parole che usa chi chiede: “report della settimana”, “riepilogo vendite”, “aggiornamento per la riunione”. Non elencare tutte le varianti possibili: scegli quelle che distinguono il compito da quelli vicini.

Il corpo, invece, deve essere scritto per essere seguito, non per essere ammirato. Frasi brevi, passi numerati, controlli verificabili. Se una parte richiede più di una pagina, non è il corpo: è un riferimento.

I riferimenti ai file devono restare a un solo livello di profondità. Una catena di link è facile da scrivere e impossibile da seguire: il modello apre un file, trova un altro riferimento, e nel frattempo ha consumato il contesto che serviva al compito.

Struttura di una skill: SKILL.md, script, riferimenti e asset, con i tre livelli di caricamento progressivo.
La cartella a sinistra, i tre livelli a destra: metadati sempre, corpo all’attivazione, risorse solo su richiesta. Illustrazione Adripedia.

Creare una skill, passo per passo

Il punto di partenza non è “scrivo una skill”, ma “ho un compito che ripeto”. Un buon segnale è la frase “l’ho già spiegato la settimana scorsa”: se la ripeti, merita una skill. Un cattivo segnale è un compito che hai fatto una volta sola e che forse non rifarai. Sette passi:

  1. Scegli un compito ricorrente, con un inizio e una fine chiari.
  2. Scrivi una description che dica cosa fa e quando usarla, con le parole che userebbe chi chiede.
  3. Scrivi il corpo con cinque parti: quando usarla, quando non usarla, procedura, controlli, formato di output.
  4. Sposta i dettagli lunghi in references/.
  5. Metti la logica deterministica in scripts/: non chiedere al modello di fare aritmetica che può fare un programma.
  6. Testa l’attivazione e il risultato.
  7. Versiona e annota le modifiche.

Un esempio completo, neutro e senza comandi di un harness specifico:

report-settimanale/
├── SKILL.md
├── references/
│   └── formato.md
└── scripts/
    └── aggrega.py
---
name: report-settimanale
description: Prepara il report settimanale delle vendite dai dati esportati. Usala quando l'utente chiede il report della settimana, il riepilogo vendite o l'aggiornamento per la riunione del lunedì.
license: MIT
compatibility: richiede accesso alla cartella dati/ e a Python 3.
metadata:
  owner: team-vendite
  versione: "1.2"
---

# Report settimanale

## Quando usarla
Quando esistono file di vendita della settimana e serve un riepilogo
per regione, con confronto sulla settimana precedente.

## Quando non usarla
Se i dati sono già aggregati, se manca la settimana precedente
o se la richiesta riguarda previsioni: in questi casi spiega cosa manca.

## Procedura
1. Elenca i file in dati/vendite-*.csv della settimana richiesta.
2. Esegui scripts/aggrega.py con la settimana come argomento.
3. Controlla che il totale delle righe coincida con il totale dei file.
4. Compila il report seguendo references/formato.md.

## Controlli
- Ogni numero deve avere una fonte nel file di origine.
- Se un file è illeggibile, fermati e segnala quale.
- Non arrotondare prima della verifica dei totali.

## Formato di output
Markdown con: titolo, periodo, tabella per regione, confronto
percentuale, tre righe di commento. Nessun dato personale.
# scripts/aggrega.py (pseudocodice)
leggi i file della settimana
verifica la presenza della colonna "importo"
somma per regione e per giorno
confronta con la settimana precedente
scrivi report.md con la data nel nome
se manca un file: esci con codice 2 e indica il percorso

Resisti alla tentazione di mettere tutto nella skill. Una skill che spiega tre compiti diversi si attiva a sproposito e confonde il modello. Se ti accorgi che la procedura ha due inizi e due fini, hai due skill. E se il compito cambia ogni settimana, forse non è una skill: è una conversazione.

Nota cosa non c’è: nessun comando di installazione, nessun nome di prodotto, nessuna istruzione che dipenda dal contesto di chi l’ha scritta. La skill deve funzionare per una persona che non ti conosce e che apre la cartella tra sei mesi.

Testare una skill

Una skill ha due modi di fallire: non si attiva quando dovrebbe, oppure si attiva quando non dovrebbe. Il primo test è quindi un test di attivazione, non di contenuto.

Test Cosa verifica Come
Attivazione positiva La skill si carica sulle richieste giuste. 10 richieste realistiche, formulate in modi diversi.
Attivazione negativa La skill resta spenta sulle richieste vicine ma diverse. 10 richieste che usano parole simili per altri scopi.
Compito Il risultato rispetta il formato e i controlli. Esegui la procedura su dati veri e confronta con l’atteso.
Regressione Una modifica non rompe i casi già superati. Riesegui l’intera suite a ogni versione.
Costo Il corpo e le risorse restano entro i budget. Misura i token caricati per attivazione.

Le dieci richieste positive non devono essere variazioni della stessa frase. Cambia il registro, la lunghezza, il livello di dettaglio. Le negative devono essere insidiose: richieste che contengono le stesse parole chiave ma un obiettivo diverso. Se la description è troppo larga, la skill si attiva sempre; se è troppo stretta, non si attiva mai.

Per il frontmatter esiste un controllo strutturale. Se lo strumento è installato, il comando è:

skills-ref validate ./report-settimanale

Il tasso di attivazione corretto è una metrica semplice: quante delle dieci richieste positive attivano la skill, quante delle dieci negative restano spente. Un valore come 9/10 e 10/10 è un buon punto di partenza; 5/10 significa che la description non descrive il compito, 0/10 negative significa che è troppo larga. Annota i falsi positivi: sono i più costosi, perché consumano contesto e possono portare il modello fuori strada.

La validazione dice se il formato è corretto, non se la skill è utile. Quella è una misura sul compito: tasso di attivazione corretto, risultato conforme, costo in token. La lunghezza non è una misura di qualità; spesso è il contrario.

Distribuire e mantenere

Una skill vive in un repository, come il codice. Può essere distribuita tramite un marketplace di plugin, un installer compatibile o una semplice cartella condivisa. Il metodo conta meno del contratto: chi la installa deve sapere cosa scarica, da quale versione e con quali permessi.

Il versionamento deve essere leggibile: un numero di versione e un elenco delle modifiche che spieghino se il comportamento è cambiato. Una skill che aggiorna la procedura senza dirlo è peggio di una skill vecchia: ha cambiato il risultato di un flusso che qualcuno dava per stabile.

La compatibilità tra client non è garantita dalla sola specifica. Alcuni client leggono i metadati e non eseguono script; altri supportano campi sperimentali; altri ancora applicano regole proprie di attivazione. Dichiara nel compatibility ciò che serve e prova la skill su più di un client, se puoi.

Prevedi anche la dismissione. Una skill che non serve più va rimossa o marcata come deprecata, con una nota che dica cosa usare al suo posto. Se resta installata, continua a occupare metadati e a competere per l’attivazione con le skill nuove.

Infine la governance, la parte che nessuno scrive e che tutti rimpiangono: chi approva una skill nuova, chi la mantiene, con quale frequenza si aggiorna, come si revoca. Una skill senza proprietario è un debito tecnico con un prompt.

Metodi e framework

Esistono progetti che impacchettano metodi interi — non solo una procedura — sotto forma di skill, comandi e istruzioni iniziali. Sono interessanti per due motivi: mostrano cosa si può fare con le skill e mostrano quanto velocemente un metodo diventi un’opinione. Numeri e dichiarazioni sono quelli pubblicati dai progetti, rilevati l’11 novembre 2026.

Leggi questa sezione come una rassegna, non come una classifica. Ogni progetto risponde a una domanda diversa: come si struttura il lavoro, come si riduce il rumore, come si mantiene il contesto, come si parte velocemente, come si ricorda tra sessioni. La domanda giusta non è “quale è il migliore”, ma “quale problema ho”.

Superpowers

Che cos’è. Una metodologia completa di sviluppo per coding agent, costruita su skill componibili e istruzioni iniziali che ne impongono l’uso. Il flusso tipico è brainstorming, design, piano, implementazione, review. Unità di confezione. Skill, subagenti, hook e istruzioni di avvio, con supporto per molti harness. Punto forte. Disciplina e tracciabilità: il lavoro lascia documenti intermedi invece di sparire in una chat. Costo e rischio. Overhead di token e di processo, opinionato, manutenzione delle skill, supporto variabile tra harness. Quando usarlo. Progetti con più fasi e bisogno di memoria del processo. Repository obra/superpowers, licenza MIT, oltre 316.000 stelle.

Caveman

Che cos’è. Una skill e un proxy per coding agent che riduce i token facendo parlare l’assistente in modo telegrafico, mentre codice, comandi, percorsi ed errori restano esatti. Ha modalità caveman, ultracave e megacave, e una funzione di “auto-clarity” per avvisi di sicurezza e azioni irreversibili. Unità di confezione. Skill e proxy, con installer dedicato. Punto forte. Riduzione dichiarata dei token di input. Costo e rischio. La compressione può togliere sfumature; il guadagno dipende dal compito. Quando usarlo. Sessioni lunghe in cui la verbosità costa più del dettaglio.

Il progetto (JuliusBrussee/caveman, Apache-2.0, oltre 119.000 stelle) dichiara il 33,2% in meno di token di input su sessioni intere e una riduzione del 65% in alcune prove. Dichiara anche, con onestà rara, che “Answer concisely” è il vero baseline e che la voce caveman taglia solo il 3% in più alla mediana, mentre ultracave arriva al 35%. Sono dichiarazioni del progetto, non misure indipendenti. Nota: abczsl520/caveman-agent è un progetto diverso, non lo stesso Caveman.

BMAD

Che cos’è. Un metodo agile per lo sviluppo guidato dall’AI, in cui i workflow producono brief, specifiche e architettura che diventano contesto per la fase successiva. Unità di confezione. Workflow, agenti e modelli di documento. Punto forte. Continuità del contesto e decisioni esplicite. Costo e rischio. Processo pesante per i lavoretti, versione in transizione, licenza da verificare. Quando usarlo. Progetti con più persone e fasi che devono lasciare traccia. Repository bmad-code-org/BMAD-METHOD, oltre 55.000 stelle; la release stabile è la v6.12, la v7 è in alpha, e il repository non dichiara una licenza SPDX standard.

ECC

Che cos’è. Un “agent harness performance optimization system”: un pacchetto di agenti, skill, comandi, hook, regole e convenzioni MCP. Unità di confezione. Plugin con manifest. Punto forte. Una batteria pronta all’uso. Costo e rischio. Superficie enorme, opinionato, manutenzione e audit continui. Quando usarlo. Quando vuoi partire da un insieme ampio e sei disposto a studiarlo. Repository affaan-m/ECC, licenza MIT, oltre 301.000 stelle; il manifest dichiara 67 agenti, 271 skill e 92 shim di comandi legacy. Sono numeri del manifest, non misure indipendenti.

Hermes Agent

Che cos’è. Un agente “self-improving” con un loop di apprendimento che crea skill dall’esperienza, le migliora durante l’uso e costruisce un modello dell’utente tra sessioni; supporta più backend di terminale. Unità di confezione. Agente e skill generate. Punto forte. Memoria e apprendimento. Costo e rischio. Autonomia, privacy, evaluation, lock-in. Quando usarlo. Sperimentazione su agenti che devono ricordare. Repository NousResearch/hermes-agent, licenza MIT, oltre 262.000 stelle.

Progetto Licenza Stelle Unità principale Ideale per
Superpowers MIT oltre 316.000 Skill e flusso di sviluppo Processo tracciabile
Caveman Apache-2.0 oltre 119.000 Skill e proxy Ridurre la verbosità
BMAD Da verificare oltre 55.000 Workflow e documenti Progetti strutturati
ECC MIT oltre 301.000 Plugin con manifest Batteria pronta
Hermes Agent MIT oltre 262.000 Agente con apprendimento Memoria tra sessioni

Le stelle misurano popolarità, non qualità. Un progetto con molte stelle può essere ottimo per un caso e inadatto per un altro; un progetto piccolo può essere più adatto al tuo. Prima di adottare un metodo, guarda licenza, manutenzione, compatibilità con il tuo strumento e costo di uscita. E ricorda che un metodo è un insieme di abitudini: se non le condividi, nessun framework le impone.

Sicurezza

Una skill può contenere script eseguibili, leggere file e chiamare la rete. Non è un documento passivo. Le regole sono le stesse che applicheresti a una dipendenza software:

Un controllo che vale la pena fare prima di installare: apri la cartella e guarda i file. Se ci sono script, leggili. Se ci sono URL, guarda dove puntano. Se ci sono istruzioni che chiedono di disattivare controlli, fermati. La maggior parte delle sorprese sta in tre righe che nessuno legge.

Attenzione. Le skill di terzi sono codice di terzi. Una descrizione innocua non garantisce che lo script dentro faccia quello che dice. Se non puoi leggere il codice, trattalo come sconosciuto: sandbox, permessi limitati e nessun accesso ai segreti.

Lessico minimo

Skill
Una procedura impacchettata in una cartella, con metadati e istruzioni, che un agente carica quando serve.
Disclosure progressiva
Il caricamento a livelli: prima i metadati, poi il corpo, poi le risorse, solo quando il compito lo richiede.
Frontmatter
Il blocco di metadati YAML all’inizio di un file Markdown.
Trigger
La richiesta o la situazione che fa attivare una skill.
Harness
Lo strumento che esegue l’agente: interfaccia, modello, tool, permessi.
Plugin
Un pacchetto installabile che può contenere più skill, comandi e configurazione.

Fonti

Fonti consultate l’11 novembre 2026. Stelle, versioni e licenze cambiano: ricontrolla prima di adottare un progetto.