Agent skills: cosa sono e perché quelle dei fornitori non sono neutre

Google ha pubblicato su GitHub un repository ufficiale di agent skills per i propri prodotti cloud, e lo ha reso compatibile con Claude Code, Codex e Antigravity CLI. Le agent skills sono cartelle con dentro un file markdown che spiega a un agente di coding come si fa una cosa specifica, e che l'agente carica soltanto quando gli serve. Il repository si chiama google/skills, è distribuito con licenza Apache 2.0 e al momento in cui scrivo ha raccolto quasi diciassettemila stelle.

Dentro ci sono più di settanta skill divise per categoria. Le due che contano di più per chi costruisce prodotti sono AI/ML, sedici skill che coprono Gemini API e BigQuery AI & ML, e Databases and analytics, nove skill su AlloyDB, BigQuery, Bigtable, Cloud SQL e Spanner. Il resto va dalle prime configurazioni di Google Cloud all'infrastruttura su GKE. Il repository è dichiarato in sviluppo attivo, quindi quel conteggio è destinato a salire.

La notizia però non è che Google abbia scritto della documentazione. È che l'ha scritta in un formato nato dentro Claude Code, cioè dentro il prodotto di un concorrente diretto, e che lo dichiara apertamente nel proprio README. Quando il fornitore di cloud più grande dopo Amazon adotta il formato di qualcun altro invece di inventarsi il proprio, quel formato ha smesso di essere una feature ed è diventato un canale di distribuzione.

Come si installano le agent skills di Google

Il comando è uno solo e sta nel README del repository:

npx skills add google/skills

Dalla riga di comando si scelgono le skill specifiche da installare invece di prendere tutto il pacchetto. Chi usa Claude Code ha una seconda strada, che passa dai plugin: si aggiunge il marketplace con claude plugin marketplace add google/skills e poi si installa il singolo pezzo con claude plugin install <plugin>@google-plugins, dove google-plugins è il nome del marketplace dichiarato da Google.

I plugin disponibili sono nominati per servizio, non per area: bigquery, spanner, alloydb, cloud-sql-postgresql, firestore-native, google-cloud-storage, looker, dataproc, bigtable, oracledb. C'è anche un data-agent-kit-starter-pack pensato per chi lavora su pipeline dati, dbt, Spark e BigQuery. Installare il singolo plugin invece dell'intero repository è la scelta giusta nel novantanove per cento dei casi, e il motivo è nella sezione qui sotto.

Cosa c'è dentro il file di una agent skill

Una skill è un file SKILL.md con un frontmatter di tre campi e un corpo in markdown. Nella skill google-cloud-recipe-auth, che è quella dedicata all'autenticazione su Google Cloud, il frontmatter dichiara name: google-cloud-recipe-auth, una metadata.category che vale GettingStarted e una description lunga una frase, che elenca cosa la skill copre: utenti umani, identità di servizio, Application Default Credentials e buone pratiche di accesso.

Il campo description è la parte che conta e quasi nessuno legge. È il testo che l'agente usa per decidere se caricare quella skill oppure no, quindi descrive con precisione in quali momenti la skill si attiverà da sola nel mezzo del tuo lavoro. Aprire quel campo prima di installare costa dieci secondi e ti dice quando quella cartella prenderà la parola.

Il corpo della skill di autenticazione fa una cosa che vale la pena copiare anche fuori da Google Cloud: prima di consigliare qualcosa fa domande di chiarimento all'utente, chi o cosa si sta autenticando, dove gira il codice, su quale risorsa, se ci sono librerie client di alto livello. È il contrario della skill che sputa la ricetta uguale in ogni situazione.

Perché una skill scritta dal fornitore non è neutra

Una skill entra dentro le decisioni dell'agente, non dentro la documentazione che leggi tu. È una differenza che cambia tutto. La skill google-cloud-recipe-auth non ti dà una pagina da consultare quando hai un dubbio sull'autenticazione: fa in modo che l'agente, la prossima volta che tocca quell'argomento, ragioni con i criteri scritti da Google. Il codice che esce da lì sarà corretto, e sarà anche il codice che usa il modo di fare le cose di quel fornitore.

Non è uno scandalo ed è esattamente il servizio che una skill deve rendere. È però il motivo per cui installare settanta skill di un solo fornitore assomiglia a mettere in squadra un consulente bravo e pagato da qualcun altro. Il criterio pratico è banale: si installa il plugin del servizio che stai già usando, uno alla volta, e non si aggiunge mai un intero marketplace con un comando solo. Se stai valutando se passare a Spanner, la skill di Spanner non è l'oggetto giusto a cui chiedere il parere.

Vale anche il contrario, ed è la parte buona della storia. Se il tuo agente deve lavorare con BigQuery e la skill ufficiale esiste, scriverla da zero è tempo buttato: quella cartella contiene la conoscenza che il fornitore ha del proprio prodotto, aggiornata da chi lo costruisce. Il lavoro tuo non è più scrivere le procedure standard, è decidere quali far entrare.

Come uso le agent skills su questo blog

Il repository di questo sito ha una cartella .claude/skills/articolo/ che contiene cinque file: uno SKILL.md che fa da indice, e poi linee-guida.md per la voce e le trappole grammaticali, seo-geo.md per come si scrive un passaggio che un motore AI può citare, ricerca-keyword.md per la ricerca fatta prima di scrivere e taglio-business.md per gli articoli rivolti agli imprenditori. Nessuno di quei file sta nel contesto quando lavoro ad altro. Entrano quando serve un articolo, e chi scrive il pezzo, io a mano o la routine che gira ogni mattina, legge le stesse identiche regole.

Quella struttura non è un vezzo, è la stessa logica del pacchetto di Google: un indice corto e i dettagli su file separati che si caricano su richiesta. Ne ho scritto il criterio completo in quando conviene creare una skill invece di una regola nel prompt, e la versione applicata al risparmio di contesto in ridurre i token di un agente di coding. Se parti da zero con lo strumento, prima serve come configurare Claude Code.

La cosa da fare oggi, se lavori su un progetto che tocca uno dei servizi coperti, è una sola: apri il repository google/skills, leggi la description della skill che ti interessa e installa quel plugin, non il resto. Se invece il problema è più a monte, cioè decidere quali procedure aziendali vale la pena mettere dentro un agente e quali no, quello è un lavoro di progettazione e lo tratto nella pagina sugli agenti AI su misura.

Il formato skill ha vinto senza che nessuno lo annunciasse. Da qui in avanti la domanda interessante non è più come si scrive una skill, ma di chi ti fidi abbastanza da lasciargliene scrivere una che il tuo agente leggerà mentre tu guardi da un'altra parte.