Condividere le competenze degli agenti tra repository

Come condividere le competenze degli agenti tra repository

Per condividere le competenze degli agenti tra repository, smettete di copiare il file e iniziate a gestirlo come una dipendenza. Mantenete un unico repository delle competenze, create un tag e consentite a ogni progetto di fissare un tag specifico. Aggiungete quindi uno smoke test per ogni competenza e verificate ogni aggiornamento con lo stesso processo usato per l'aggiornamento di una dipendenza.

Il processo comprende quattro parti: una fonte autorevole condivisa, una versione fissata per ogni repository, uno smoke test per ogni competenza e un processo di revisione. Le sezioni seguenti spiegano perché esiste ogni parte, come gli strumenti rilasciati nel 2026 gestiscono questo aspetto e come realizzare l'intero sistema su un remote Git self-hosted, senza usare servizi esterni.

Una competenza dell'agente è una directory che contiene un file SKILL.md, oltre agli script e ai file di riferimento necessari. Se questa unità è nuova, leggete prima che cos'è una competenza dell'agente e come funziona SKILL.md. Questa pagina descrive la supply chain che gestisce tale unità.

Dove si trova una skill e perché condividerla è difficile

Claude Code carica le skill da tre posizioni, indicate nella documentazione sulle skill.

• ~/.claude/skills/<skill-name>/SKILL.md è personale. Viene caricata in tutti i tuoi progetti, ma in quelli degli altri utenti.
• .claude/skills/<skill-name>/SKILL.md è a livello di progetto. Viene caricata da chiunque effettui il checkout del repository.
• <plugin>/skills/<skill-name>/SKILL.md è inclusa in un plugin. Viene caricata ovunque il plugin sia abilitato.

La seconda opzione è quella utile per un team, perché viene sottoposta a commit e chiunque cloni il repository la riceve. È anche il punto in cui iniziano i problemi. Una skill in .claude/skills/ appartiene a un solo repository. Se hai otto repository, la skill viene copiata otto volte.

Il frontmatter non aiuta. La specifica Agent Skills consente sei chiavi e i percorsi di distribuzione che la applicano stampano l'elenco quando ne usi un'altra:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Nota che manca version: non esiste alcuna chiave con questo nome. Nel file non viene registrata alcuna informazione su quale copia sia più recente. È ragionevole, perché una skill è un documento, non un pacchetto. Questo significa però che il versionamento deve essere gestito dal livello esterno al file, e quel livello è di tua responsabilità.

Problema uno: otto copie che divergono senza farsi notare

Il copia e incolla funziona il primo giorno. Al sessantesimo giorno fallisce. Qualcuno corregge un'istruzione errata nel repository payments e non aggiorna gli altri sette. Un'altra persona aggiunge una regola sull'impaginazione in orders. Ora lo stesso nome di skill produce due revisioni diverse, a seconda della directory da cui è stato avviato l'agent, e nessuno dei due sviluppatori se ne accorge.

Il problema resta invisibile perché non esiste uno stato di errore. Una skill è testo descrittivo. Un'istruzione obsoleta produce una risposta sicura ma errata, cioè il tipo di errore più costoso. L'agent non confronta la tua copia con quelle degli altri; l'unico segnale è che una persona si accorga che due repository non corrispondono.

Problema due: nessun riferimento fissa una versione

Anche quando un team mantiene le competenze in un unico punto, il metodo di condivisione più comune consiste in un passaggio di copia: uno script di configurazione, una riga curl nella documentazione di onboarding oppure un alias della shell che sincronizza una directory. Tutti questi metodi installano la versione che in quel momento si trova all'ultimo commit del branch.

Di conseguenza, due sviluppatori che usano lo stesso commit della stessa applicazione possono eseguire istruzioni diverse, perché hanno eseguito la sincronizzazione in giorni diversi. Inoltre, dopo un'esecuzione errata dell'agente, non è possibile rispondere alla domanda più importante: quale versione della competenza l'ha prodotta? Senza una revisione registrata, l'esecuzione non è riproducibile e la segnalazione del bug non consente di intervenire.

Problema tre: nessuno sa se la skill funziona ancora

Una skill non ha un compilatore. È un insieme di istruzioni rivolte a un modello, quindi può smettere di funzionare anche se il file rimane identico byte per byte. Un aggiornamento del modello modifica il grado di aderenza alle istruzioni lunghe. Uno strumento a riga di comando richiamato dalla skill rinomina un flag. Un URL in un file di riferimento inizia a restituire 404 e l’agente elabora le risposte usando la pagina di errore.

In nessuno di questi casi si verifica un errore evidente. L’agente continua a rispondere. Semplicemente, la risposta è peggiore rispetto al mese scorso, ed è difficile accorgersene una pull request alla volta.

Cosa risolvono gli strumenti distribuiti nel 2026

Le risposte stanno arrivando proprio ora e non concordano su dove debba risiedere la versione.

Lockfile. Lo strumento da riga di comando skills di Vercel Labs (vercel-labs/skills, distribuito con licenza MIT, versione v1.5.22 al 5 agosto 2026) installa le skill da un repository git nella directory prevista dal proprio agent e conosce la struttura di oltre settanta agent. npx skills add <repo> installa, npx skills update aggiorna e npx skills list mostra ciò che è presente. Il registro delle installazioni viene mantenuto una volta per utente, non una volta per repository. Una richiesta ancora aperta nel progetto (issue 283) chiede un comando skills install che reinstalli ogni skill registrata nel lockfile, in modo che una seconda macchina disponga dello stesso insieme. Considerate questa richiesta come un indicatore dello stato attuale. L'idea del lockfile è ormai definita. La parte relativa al singolo progetto è ancora in fase di sviluppo.

Specifiche e test. SkillSpec adotta l'approccio opposto. Tratta una SKILL.md come un contratto da verificare, non come testo da accettare senza controlli, con l'obiettivo dichiarato di rendere le skill «seguibili, testabili e dimostrabili». skillspec doctor <path> segnala i punti in cui è probabile che un agent perda il filo. skillspec boundary map <path> indica quali risorse la skill può raggiungere e skillspec boundary assess <path> ordina i risultati in base al rischio. È un crate Rust, distribuito con doppia licenza MIT o Apache 2.0, alla versione 0.2.2 al 29 luglio 2026. Installate la versione bloccata invece di quella più recente:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked esegue la compilazione usando le versioni delle dipendenze con cui il crate è stato pubblicato, evitando che la compilazione cambi in modo imprevisto. skillspec --version dovrebbe stampare 0.2.2. Un numero diverso indica che un binario più vecchio presente prima nel proprio PATH ha la precedenza.

Prassi dei vendor. Google ha descritto come realizza le skill in google/skills in un articolo su come realizza, testa e porta su larga scala le skill per agent. Eliminando il fattore di scala, il meccanismo è la normale integrazione continua (CI). Prima dell'integrazione, ogni skill supera i linter per i metadati frontmatter, il conteggio delle righe, la struttura delle directory e la denominazione. Un link checker interrompe la compilazione per qualsiasi URL che restituisca 404; in questo modo rileva anche i link plausibili inventati da un agent. Gli autori devono fornire insieme alla skill una suite di prompt per la valutazione e una griglia di punteggio. I processi di valutazione pianificati vengono quindi eseguiti ogni settimana sull'intera libreria per rilevare regressioni. Ogni skill ha inoltre un responsabile assegnato, che deve intervenire quando la qualità diminuisce.

Il modello alla base di tutte e tre le risposte

Non devi sceglierne una. Alla base c’è una struttura unica, e git in forma semplice ti mette a disposizione tutti gli elementi necessari.

1. Un’unica fonte autorevole. La skill ha una sola posizione di riferimento e ogni repository fa riferimento a quella posizione invece di conservarne una copia.
2. Una versione bloccata per repository. Ogni progetto registra la revisione esatta che utilizza. Un aggiornamento diventa così un commit in quel progetto, con autore e data.
3. Un test di verifica per ogni skill. Un controllo eseguibile dimostra che la skill continua a produrre il risultato previsto.
4. Un percorso di revisione. Una modifica a una skill condivisa passa dalla revisione e ogni consumer visualizza un diff prima di adottarla.

Questa è la struttura di una dipendenza. Le skill sono diventate artefatti condivisi più rapidamente di quanto siano cresciuti gli strumenti che le supportano. Per questo, la scelta più sicura è usare gli strumenti di cui già ti fidi.

Un’organizzazione per un piccolo team su un repository Git self-hosted

Un repository contiene le competenze. Non contiene altro, quindi la cronologia funziona come un changelog delle istruzioni.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Le release sono tag. Usate tag annotati, perché includono un messaggio e una data. Scrivete il messaggio indicando il motivo per cui un utilizzatore dovrebbe voler adottare l’aggiornamento:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Se il remote è Gitea, Forgejo, GitLab oppure un repository bare accessibile tramite SSH sul vostro VPS, quanto segue non cambia. Qui servono soltanto Git e un symlink.

Pinning con un sottomodulo git

Un sottomodulo registra nel repository un commit preciso di un altro repository. Questo riferimento è il pin. In ogni progetto che lo utilizza:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

Il link simbolico è l'elemento che rende possibile questo meccanismo. Una voce skill a livello di progetto può essere un link simbolico a una directory situata altrove nel filesystem, e Claude Code lo segue e legge SKILL.md dalla destinazione. La skill viene quindi caricata come una normale skill di progetto, mentre i file risiedono nel sottomodulo al commit scelto.

Verifica il pin:

git submodule status

Una riga corretta inizia con uno spazio, poi riporta il commit, il percorso e infine il tag più vicino:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Un - iniziale indica che il sottomodulo non è mai stato inizializzato, quindi .claude/skills/api-review non punta a nulla e la skill non viene caricata senza produrre messaggi. Risolvi il problema con git submodule update --init. Un + iniziale indica che il commit estratto è diverso da quello registrato, quindi lo sviluppatore sta usando istruzioni che nessun altro ha. I nuovi cloni richiedono git clone --recurse-submodules, e questa riga deve essere presente nel README, perché un clone semplice lascia vendor/agent-skills vuoto e non visualizza alcun errore.

L'aggiornamento è deliberato, ed è proprio questo lo scopo:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

La riga diff è il percorso di revisione. Mostra la stessa modifica che vedranno tutti gli altri repository che utilizzano il sottomodulo e può essere inclusa in una pull request.

In alternativa, usa il pinning con un marketplace di plugin

Se preferisci non chiedere a ogni sviluppatore di imparare a usare i submodule, il sistema di plugin di Claude Code gestisce la distribuzione al posto tuo e funziona anche con un repository remoto self-hosted. Inserisci un catalogo in .claude-plugin/marketplace.json nel repository delle skill:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

In questo caso entrano in gioco due origini diverse, ed è facile confonderle. L’origine del marketplace, cioè il repository da cui viene recuperato il catalogo, accetta ref per un branch o un tag, ma non accetta sha. Un’origine di plugin all’interno del catalogo accetta entrambe le opzioni; quando sono impostate entrambe, sha determina il pin effettivo. Il pin sul commit esatto deve quindi essere inserito nella voce del catalogo.

Ogni repository che utilizza il plugin dichiara poi il marketplace nel file .claude/settings.json versionato:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Un membro del team che considera attendibile la cartella del progetto riceve la richiesta di installare il marketplace e il plugin viene abilitato senza dover consultare una pagina wiki con le istruzioni. Le skill sono quindi disponibili tramite /team-skills:api-review, perché le skill dei plugin usano il namespace del nome del plugin e non possono entrare in conflitto con una skill di progetto omonima. Dopo il push di un nuovo tag, i consumer aggiornano il marketplace con /plugin marketplace update acme-agents e poi eseguono /reload-plugins se il riepilogo dell’installazione lo richiede.

Scrivere uno smoke test per una skill

Uno smoke test è un’esecuzione scriptata dell’agente su una fixture con un errore noto, accompagnata da un’unica asserzione. Claude Code viene eseguito in modalità non interattiva con -p, e in questo contesto funziona anche una skill invocata dall’utente: inserire /skill-name nella stringa del prompt; verrà espanso prima dell’avvio dell’esecuzione.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md è un file breve con un solo errore intenzionale. L’asserzione verifica che la skill lo identifichi. jq -e restituisce un codice diverso da zero quando il relativo filtro produce null; quindi, se una skill smette di rilevare l’errore inserito nella fixture, lo script fallisce. claude restituisce a sua volta un codice diverso da zero quando l’esecuzione fallisce, mentre set -euo pipefail trasforma uno dei due errori in un test fallito.

Un modello riformula le risposte tra un’esecuzione e l’altra. Non eseguire quindi asserzioni sull’intera frase. Verificare invece un identificatore che la skill deve produrre oppure un campo dello schema richiesto. Mantenere inoltre la fixture piccola, così l’esecuzione resta economica.

In CI, aggiungere --bare. Senza questa opzione, claude -p carica lo stesso contesto di una sessione interattiva, inclusi hook, plugin e CLAUDE.md presenti sul computer da cui viene eseguito. La configurazione personale di un membro del team può quindi modificare il risultato. La modalità bare ignora ogni rilevamento automatico. Di conseguenza, ignora anche la skill da testare, che deve essere caricata esplicitamente. La modalità bare non legge neppure il login dell’abbonamento. Impostare quindi prima ANTHROPIC_API_KEY nell’ambiente:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

Con --output-format stream-json, il primo evento dell’esecuzione indica quali plugin sono stati caricati e contiene un array plugin_errors per quelli che non lo sono stati. Fare fallire il job CI se plugin_errors non è vuoto. Questo rileva un pin diretto a una revisione che non esiste più, una situazione che altrimenti si manifesta come un agente che ignora silenziosamente le regole interne.

Una skill condivisa è un'istruzione eseguibile

Due funzionalità rendono letterale questa definizione, e entrambe sono importanti quando il file proviene da un altro team.

Per prima cosa, una SKILL.md può eseguire comandi shell prima che il modello legga qualsiasi contenuto. Una riga come questa nel corpo del file è una fase di pre-elaborazione:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

Il comando viene eseguito sulla macchina che carica la skill e il relativo output sostituisce il segnaposto nel testo ricevuto dal modello. Un blocco delimitato aperto da tre backtick seguiti da ! esegue più comandi nello stesso modo. Nessuno approva queste operazioni durante l'esecuzione. Leggere una skill condivisa significa leggere anche le sostituzioni dei comandi che contiene.

In secondo luogo, il frontmatter può autorizzare preventivamente gli strumenti. allowed-tools concede gli strumenti elencati senza mostrare una richiesta di autorizzazione per il turno che ha invocato la skill. Per una skill di progetto, questa concessione diventa effettiva quando qualcuno accetta la finestra di dialogo relativa all'attendibilità dell'area di lavoro per la cartella. La documentazione di Claude Code descrive chiaramente la conseguenza: esaminare le skill di progetto prima di considerare attendibile un repository, perché una skill può concedersi un accesso esteso agli strumenti.

Gestire l'aggiornamento di una skill richiede quindi la stessa attenzione riservata all'aggiornamento di una dipendenza. Usare, quando il meccanismo lo consente, il pin su un commit preciso, perché un tag può essere spostato e un branch cambia per definizione. Su una macchina soggetta a restrizioni, "disableSkillShellExecution": true nelle impostazioni sostituisce ogni sostituzione di comando con il testo letterale [shell command execution disabled by policy] invece di eseguirla; se applicata tramite impostazioni gestite, l'utente non può ignorarla. Le skill incluse e quelle gestite sono escluse da questa impostazione.

La stessa attenzione è necessaria per i dati letti da una skill. Una skill che esegue env o apre un file di configurazione importa nel contesto del modello tutto ciò che trova. Questo è il problema descritto in mantenere i secret fuori dagli agent che esegui. Una skill che recupera una pagina o esegue una query espone gli stessi dati verso l'esterno: il testo recuperato finisce nel contesto e appare esattamente come le istruzioni scritte dall'utente. È un confine da comprendere prima di indirizzare un agent verso la propria istanza SearXNG per la ricerca web.

Cosa leggere quando si aggiorna una versione

• Il diff del corpo di ogni SKILL.md, perché quel testo contiene le istruzioni che l’agente seguirà.
• Ogni sostituzione di comando, perché viene eseguita sulla macchina quando la skill viene caricata.
• Qualsiasi modifica a allowed-tools, perché quella riga concede strumenti senza richiedere una conferma.
• L’esecuzione dei test associata al tag. Se il repository condiviso esegue i propri smoke test in CI, il tag a cui si sta fissando la versione deve avere un’esecuzione completata con esito positivo.

Un reviewer che non riesce a leggere l’intero diff in dieci minuti sta esaminando una skill diventata troppo grande. Dividetela. Lo stesso principio vale per i documenti del repository che gli agenti leggono: mantenete le regole persistenti nei file descritti in la suddivisione tra AGENTS.md e HUMAN.md e il ragionamento architetturale in un DESIGN.md scritto per gli agenti, lasciando alle skill procedure circoscritte.

Quando un modello o uno strumento modifica il comportamento di una skill

Diverse componenti alla base di una skill possono cambiare senza che nessuno la modifichi. Un aggiornamento del modello può ridurre l'affidabilità con cui viene seguita un'istruzione lunga. Di conseguenza, una skill che dipendeva dal raggiungimento del passaggio nove da parte del modello può interrompersi prima. Uno strumento da riga di comando può rinominare un flag. L'agente esegue quindi il flag precedente, legge l'errore e procede in modo improvvisato. Un URL di riferimento può iniziare a restituire 404. Un harness dell'agente può cambiare il modo in cui seleziona le skill. In questo caso, un description che prima prevaleva nella corrispondenza potrebbe non essere più selezionato. Quando una procedura inizia a terminare prima del previsto, nessun incremento di versione risolve il problema. Le istruzioni devono invece avere una struttura che obblighi a eseguire gli ultimi passaggi. Questo è l'approccio alla base di la skill unlazy e del relativo metodo Depth Tree.

Per questo, in questa configurazione, il test smoke è il componente più importante. Esegui il test di ogni skill secondo una pianificazione e anche a ogni push. Google esegue ogni settimana i propri job di valutazione sull'intera libreria proprio per questo motivo. Per un team con dieci skill è sufficiente un cron job settimanale su un piccolo VPS. È l'unico modo per rilevare il problema prima che se ne accorga uno sviluppatore.

Anche la portabilità è utile. La specifica Agent Skills limita il frontmatter a sei chiavi. Una skill scritta secondo questa specifica viene quindi caricata da strumenti diversi da quello per cui è stata creata. Ogni chiave specifica dell'harness che aggiungi è invece una scelta legata a un singolo vendor. Scrivere skill che continuino a funzionare dopo la sostituzione del modello è una disciplina autonoma, descritta in come far funzionare una skill su qualsiasi modello.

FAQ

Come posso condividere la stessa skill dell'agent tra più repository?

Inserisci la skill in un repository git dedicato, assegna tag alle release e fai in modo che ogni progetto che la utilizza faccia riferimento a un tag invece di copiare il file. Sono disponibili due meccanismi. Un git submodule registra un commit esatto e un symlink da .claude/skills/<name> al submodule consente di caricarlo come una normale skill di progetto. Un plugin marketplace svolge la stessa funzione tramite /plugin, con il pin dichiarato nel repository che lo utilizza, in .claude/settings.json. In entrambi i casi, la versione viene registrata nella cronologia git, quindi puoi determinare quali istruzioni hanno prodotto una determinata esecuzione dell'agent.

Posso fissare una skill dell'agent a una versione specifica?

Non dall'interno di SKILL.md, perché quel frontmatter non contiene una chiave version. Il pin deve provenire dal livello che gestisce il file. Un git submodule fissa per progettazione un commit esatto. In un plugin marketplace di Claude Code, una sorgente di plugin accetta ref per un branch o un tag e sha per un commit esatto; se sono presenti entrambi, prevale sha. La sorgente del marketplace accetta invece soltanto ref. Preferisci il pin al commit, perché un tag può essere spostato dopo la revisione.

Che cosa deve verificare uno smoke test della skill?

Verifica un elemento stabile. Esegui la skill in modalità non interattiva su un fixture che contiene un errore noto, quindi controlla che nell'output compaia un identificatore specifico, ad esempio l'ID di una regola che la skill deve segnalare. Richiedere un output strutturato con --output-format json e --json-schema rende il controllo esatto, mentre jq -e interrompe lo script se il valore manca. Non verificare mai una frase completa, perché un modello può riformulare le risposte tra un'esecuzione e l'altra.

È sicuro installare una skill condivisa dal repository di un altro team?

Trattala come una dipendenza di codice, perché consiste in istruzioni eseguibili. Una SKILL.md può eseguire comandi shell al caricamento tramite la forma di sostituzione dei comandi !, mentre il campo allowed-tools del frontmatter può autorizzare in anticipo gli strumenti senza richiedere una conferma. Esamina il diff a ogni aggiornamento, usa un pin su un commit esatto invece di un branch e preferisci una sorgente gestita dal tuo team. Sulle macchine gestite, "disableSkillShellExecution": true nelle impostazioni impedisce del tutto l'esecuzione delle sostituzioni dei comandi.

Una skill condivisa funziona anche con agent diversi da Claude Code?

Dipende dal frontmatter utilizzato. La specifica Agent Skills definisce sei chiavi: name, description, license, compatibility, metadata e allowed-tools. Una skill limitata a queste chiavi viene caricata dagli strumenti che implementano la specifica e viene caricata anche in Claude Code senza modifiche. Le chiavi specifiche dell'harness e le funzionalità del corpo che non fanno parte della specifica vengono ignorate o rifiutate dagli altri strumenti; quindi, tienile fuori da qualsiasi skill che intendi condividere ampiamente.