
Una "agent skill" è una cartella versionata, costruita attorno a un file SKILL.md, che descrive quando e come eseguire un compito ripetibile: le istruzioni possono essere condivise fra agenti diversi — Copilot, Claude Code, Cursor — ma l'accesso a strumenti, credenziali e permessi resta sempre responsabilità dell'ambiente in cui l'agente gira.
GitHub ha pubblicato una guida pratica su questo tema, presentata durante GitHub Universe 2026 in una sessione tenuta insieme a Shishir Tewari, Senior Manager di Data Engineering presso Procore. Il documento non si limita alla teoria: mostra due esempi concreti — Proof Agent e Data Forge — e un metodo in tre passaggi per progettare skill che funzionino davvero su più agenti senza doverle riscrivere ogni volta.
In breve
- Una agent skill è una cartella versionata con un file SKILL.md che descrive un compito ripetibile: non concede accesso a strumenti o dati, si limita a spiegare come usarli.
- Il contesto di progetto (nomi delle tabelle, schemi, convenzioni) va tenuto separato dalle istruzioni della skill, in un manifest condiviso che le skill correlate leggono invece di duplicare.
- Le skill correlate dovrebbero condividere un unico percorso di accesso alla piattaforma dati, così il comportamento resta uniforme e verificabile su ogni client.
- I passaggi che richiedono giudizio umano — approvazioni, revisione delle decisioni proposte — vanno inseriti esplicitamente nel flusso di lavoro, non lasciati all'agente.
- Uno script di packaging può generare automaticamente i file specifici per ciascun client AI a partire da un'unica fonte di istruzioni.
Cos'è davvero una agent skill?
Una agent skill è, in sostanza, la versione scritta e riutilizzabile di una spiegazione che altrimenti si ripeterebbe ogni volta a voce o in chat. La guida di GitHub la descrive come una cartella versionata centrata su un file SKILL.md, che racconta quando applicare un compito e come eseguirlo passo per passo. È importante distinguere due piani: la skill descrive il come — per esempio come interrogare un database — ma non concede l'accesso a quel database. Credenziali, permessi e strumenti restano una responsabilità dell'ambiente che ospita l'agente, non della skill stessa.
Questa distinzione è il primo concetto da interiorizzare prima di scrivere qualsiasi SKILL.md: separare le istruzioni dall'autorizzazione evita che una skill diventi fragile o insicura quando viene spostata da un agente all'altro.
Come si definisce una skill che funziona bene?
Una skill funziona meglio quando ha un compito chiaro, un input definito e un output riconoscibile. La guida consiglia di partire proprio da qui, prima ancora di scrivere la prima riga di istruzioni: cosa deve succedere, da dove parte il lavoro, dove si ferma e cosa deve vedere chi revisiona il risultato.
L'esempio portato è Proof Agent, una skill dedicata alla verifica adversariale del lavoro generato da un'altra intelligenza artificiale. Il principio alla base è semplice ma spesso trascurato: l'auto-verifica non è verifica. Se lo stesso agente che ha prodotto una modifica valuta anche la propria correttezza, la sua spiegazione può influenzare il giudizio. Per questo Proof Agent usa un verificatore indipendente, separato dall'agente che ha generato le modifiche, che esamina i cambiamenti e fornisce prove a sostegno delle proprie conclusioni. Nel file SKILL.md, la sezione "When to Verify" indica quando invocare la skill, mentre il resto delle istruzioni specifica cosa deve essere esaminato e quali evidenze includere nei risultati.
Come si coordinano più skill in un unico flusso di lavoro?
Quando il giudizio che rende corretta una pipeline di dati vive nella testa di quattro persone diverse, quelle quattro persone diventano, di fatto, la roadmap del progetto: ogni modifica dipende dalla loro disponibilità e dalla loro conoscenza dei dati. Data Forge, il secondo esempio della guida, mostra come catturare parte di quel giudizio in skill che lavorano insieme.
Nel caso descritto — una pipeline di supporto che conta gli incidenti creati e risolti — il percorso parte dalla skill forge-init, che scopre i dettagli del progetto (tabelle sorgente, convenzioni di naming) e li scrive in un manifest condiviso. Le altre skill leggono quel manifest per ottenere il contesto di progetto di cui hanno bisogno, senza doverlo riscoprire da sole. La skill forge-builder coordina poi il lavoro dall'apertura dell'issue fino alla pull request, usando forge-dbx per interrogare la piattaforma dati e forge-lint per applicare gli standard del team durante la progettazione. Una persona rivede le decisioni proposte lungo il percorso, e la pull request finale contiene il codice della pipeline, le modifiche allo schema e i test.
Il vantaggio di questa struttura è che ogni skill ha una responsabilità definita e tutte condividono lo stesso contesto di progetto: quando cambia un passaggio, si modifica una sola skill e le altre restano intatte. La guida avverte però che le skill sono adatte a lavoro delimitato e ripetibile che beneficia di un giudizio riutilizzabile — una checklist, un rilascio, una migrazione, una pipeline di metriche. Se un flusso di lavoro richiede un'interfaccia stabile, uno stato condiviso, una traccia di controllo (audit trail), un'esecuzione di lunga durata o permessi applicati fuori dal modello, la scelta più adatta diventa un'applicazione vera e propria, non una skill.
Perché separare il contesto di progetto dalle istruzioni?
Il contesto di progetto non va mai scritto a mano dentro ogni skill, perché altrimenti ogni nome di tabella, ogni schema e ogni convenzione andrebbe duplicato — e aggiornato — in più punti. Nell'esempio di Data Forge, un manifest descrive il progetto, il metric store e la piattaforma dati, così le altre skill possono usare i dettagli corretti senza doverli integrare nelle proprie istruzioni.
Un punto sottile, ma rilevante, riguarda la differenza tra ciò che viene scoperto automaticamente e ciò che rappresenta uno standard del team: la skill forge-init può ispezionare schemi e pattern di codice esistenti, ma è forge-lint a fornire le regole da seguire prima che il codice venga generato. Un pattern trovato in un repository non è automaticamente una regola da preservare: per questo i dettagli scoperti vanno resi verificabili, lasciando alle persone la possibilità di confermarli o modificarli dove serve giudizio di business. Un buon test di portabilità, suggerito dalla guida, è chiedersi: un altro team potrebbe usare queste skill con il proprio manifest, senza doverle riscrivere?
Come si condivide l'accesso alla piattaforma dati tra più skill?
Le skill correlate dovrebbero avere un unico modo di interagire con la piattaforma dati, invece di definire ciascuna la propria logica di connessione. Nell'esempio Data Forge, la skill forge-dbx offre alle altre skill un solo percorso di accesso: legge il manifest e seleziona l'adattatore adeguato, Databricks o DuckDB a seconda del caso.
È importante notare cosa il manifest non fa: può scegliere il motore — per esempio DuckDB per una demo locale — ma non può installare il client DuckDB né concedere l'accesso al database. Queste restano responsabilità di configurazione dell'ambiente e di chi lo gestisce. In sintesi: il manifest sceglie il motore, l'ambiente ospitante fornisce l'accesso.
Dove vanno inseriti i controlli umani?
I controlli umani vanno collocati nei passaggi dove serve giudizio, non lasciati alla discrezione dell'agente. Il flusso di lavoro Data Forge per la pipeline di supporto prevede sette fasi, ciascuna con un punto di controllo umano: prima che una fase proceda, il sistema verifica che quella precedente sia completa, e prima che vengano eseguite modifiche allo schema viene richiesta un'approvazione esplicita.
Lo stesso principio si applica a Proof Agent nella revisione del codice: un flusso basato su GitHub Actions fornisce al verificatore la richiesta originale e le modifiche al codice, ma non la valutazione che l'agente che ha scritto il codice dà di se stesso. Il verificatore restituisce un esito — PASS, FAIL o PARTIAL — e deve citare prove concrete nei file modificati. L'azione esegue una revisione statica del diff, senza eseguire codice né lanciare test: l'obiettivo resta mantenere i risultati dei test e i requisiti di merge nelle regole e nei controlli CI del repository. Nella demo descritta, l'opzione block-on-fail era impostata su false, rendendo i risultati solo indicativi; per impostazione predefinita, invece, un esito FAIL blocca il controllo e di conseguenza il merge, se quel controllo è richiesto dalle regole del repository.
Come si rende una skill portabile su Copilot, Claude Code e Cursor?
Gestire più client AI significa, senza un metodo, tenere sincronizzate manualmente più copie delle stesse istruzioni — un lavoro ripetitivo e soggetto a errori. Nell'esempio Data Forge, i file skills/*/SKILL.md restano l'unica fonte di verità, mentre uno script di packaging genera i file specifici per ciascun client: il plugin per Claude Code, quello per Cursor e gli agenti in formato Markdown per GitHub Copilot. Lo script include anche una modalità di verifica pensata per l'integrazione continua (CI), così eventuali disallineamenti vengono intercettati prima che la skill venga distribuita.
Una volta installata, ogni skill va comunque controllata singolarmente sul client scelto: i client differiscono per modelli disponibili, strumenti, credenziali e permessi. Dopo l'installazione conviene verificare che il client riconosca la skill per il compito previsto, carichi correttamente i suoi riferimenti, possa usare gli strumenti richiesti e restituisca le evidenze che la skill stessa richiede.
Tre pratiche da portare a casa
- Metti il contesto di business in un unico file. Nomi di progetto, schemi e convenzioni vanno in un manifest che ogni skill legge, invece di essere duplicati: un solo punto visibile da aggiornare per tutto il team.
- Dai alle skill correlate un modo coerente di usare la piattaforma. Query, job e modifiche allo schema passano per lo stesso percorso di accesso, così il comportamento del flusso di lavoro resta comprensibile e verificabile su ogni client.
- Usa le istruzioni per guidare, i controlli per verificare. Una skill può dire quali standard seguire e quando chiedere approvazione; la revisione umana va inserita dove serve giudizio e contesto, mentre test e controlli CI intercettano i problemi prima che una modifica avanzi.
Il punto di partenza suggerito dalla guida è pratico: scegliere il compito che si è stanchi di rispiegare ogni volta, annotare cosa richiede, dove si ferma e cosa deve vedere chi lo revisiona, provarlo con un altro agente e migliorarlo in base a ciò che si impara.
Domande frequenti
Una agent skill sostituisce un'applicazione vera e propria? No. Le skill sono adatte a lavoro delimitato e ripetibile che beneficia di un giudizio riutilizzabile, come una checklist, un rilascio o una pipeline di metriche. Se serve un'interfaccia stabile, uno stato condiviso, una traccia di controllo, un'esecuzione di lunga durata o permessi applicati fuori dal modello, la scelta più adatta è un'applicazione.
Una skill può accedere da sola a un database o a un sistema aziendale? No: la skill descrive come eseguire un'operazione, ma l'accesso effettivo — credenziali, permessi, strumenti — resta una responsabilità dell'ambiente che ospita l'agente, non della skill stessa.
Perché serve un verificatore separato invece che far controllare all'agente il proprio lavoro? Perché l'auto-verifica non è verifica: se lo stesso agente valuta ciò che ha prodotto, la sua spiegazione può influenzare il giudizio. Un verificatore indipendente esamina le modifiche e deve citare prove concrete a sostegno dei propri risultati.
Come si mantiene una skill aggiornata su più client AI contemporaneamente? Tenendo i file SKILL.md come unica fonte di verità e generando i formati specifici per ciascun client tramite uno script di packaging, con una modalità di verifica dedicata da inserire nei controlli di integrazione continua.
Fonti
- GitHub Blog — Build once, run on any agent: A practical guide to agent skills — https://github.blog/ai-and-ml/github-copilot/build-once-run-on-any-agent-a-practical-guide-to-agent-skills
Se il tema delle agent skills ti ha fatto venire in mente un processo che spieghi ogni volta a parole a qualcuno in azienda, può valere la pena capire come renderlo riutilizzabile: iNexus affronta questo tipo di progettazione quando costruisce agenti su misura, e un confronto sui servizi o una scrittura diretta tramite i contatti è il modo più semplice per iniziare a ragionarci.