Condividere le skill tra repository senza differenze

Come condividere le skill degli agenti tra repository

Per condividere le skill degli agenti tra repository, smettete di copiare il file e iniziate a gestirlo come dipendenza. Mantenete un unico repository delle skill, assegnategli dei tag e fate in modo che ogni progetto blocchi una versione tramite un tag. Aggiungete quindi uno smoke test per ogni skill e revisionate ogni aggiornamento come fareste con l’aggiornamento di una dipendenza.

Il processo comprende quattro elementi: una fonte autorevole condivisa, una versione bloccata per ogni repository, uno smoke test per ogni skill e un processo di revisione. Le sezioni seguenti spiegano perché esiste ciascun elemento, come gestiscono il problema gli strumenti distribuiti nel 2026 e come realizzare l’intero sistema su un remote git self-hosted, senza usare servizi esterni.

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

Dove risiede una skill e perché condividerla è difficile

Claude Code carica le skill da tre posizioni e la documentazione sulle skill elenca ciascun percorso.

• ~/.claude/skills/<skill-name>/SKILL.md è personale. Viene caricato in tutti i tuoi progetti e in nessun progetto di altri utenti.
• .claude/skills/<skill-name>/SKILL.md è a livello di progetto. Viene caricato per chiunque esegua il checkout di quel repository.
• <plugin>/skills/<skill-name>/SKILL.md viene distribuito all'interno di un plugin. Viene caricato 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 repository. Hai otto repository. Quindi la skill viene copiata otto volte.

Il frontmatter non è d'aiuto. La specifica Agent Skills consente sei chiavi e i percorsi di distribuzione che applicano questo vincolo 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 cosa manca: non esiste alcuna chiave version. Nel file non viene registrato quale copia sia più recente. È ragionevole, perché una skill è un documento e non un pacchetto. Questo significa però che il versionamento deve provenire dal livello che circonda il file, e quel livello è di tua responsabilità.

Problema 1: otto copie che divergono senza segnali

Il copia-incolla funziona il primo giorno. Fallisce al sessantesimo. Qualcuno corregge un'istruzione errata nel repository payments e non aggiorna gli altri sette. Qualcun altro aggiunge una regola sull'impaginazione in orders. A questo punto, lo stesso nome di skill produce revisioni diverse a seconda della directory da cui è stato avviato l'agent, senza che nessuno degli sviluppatori se ne accorga.

Il problema rimane silenzioso 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, quindi l'unico segnale è che una persona noti che due repository non coincidono.

Problema due: nessun elemento fissa una versione

Anche quando un team conserva le competenze in un unico punto, il metodo di condivisione abituale 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 attualmente presente all'estremità 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 problematica dell'agent, non è possibile rispondere alla domanda più importante: quale versione della competenza l'ha prodotta? Senza una revisione registrata, l'esecuzione non è riproducibile e il report del bug non è utilizzabile.

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 resta identico byte per byte. Un aggiornamento del modello modifica la precisione con cui viene seguita un'istruzione lunga. Uno strumento da riga di comando utilizzato dalla skill rinomina un flag. Un URL in un file di riferimento inizia a restituire 404 e l'agente utilizza la pagina di errore come base di lavoro.

In nessuno di questi casi si verifica un errore evidente. L'agente continua a rispondere. La risposta è semplicemente peggiore rispetto al mese precedente, ma questo è difficile da rilevare una pull request alla volta.

Cosa risolvono gli strumenti disponibili 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, 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 più di settanta agent. npx skills add <repo> installa, npx skills update aggiorna e npx skills list mostra ciò che è installato. Il record delle installazioni viene mantenuto una sola volta per utente, non una volta per repository. Una richiesta aperta in quel progetto (issue 283) chiede un comando skills install che reinstalli tutte le skill registrate nel lockfile, in modo che una seconda macchina ottenga lo stesso insieme. Considerate questa richiesta come un indicatore dello stato attuale. L'idea del lockfile è ormai consolidata. La componente per 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 "followable, testable, and provable". skillspec doctor <path> segnala i punti in cui è probabile che un agent perda il filo. skillspec boundary map <path> segnala le risorse che la skill può raggiungere e skillspec boundary assess <path> ordina i risultati in base al rischio. È un crate Rust con doppia licenza MIT o Apache 2.0, alla versione 0.2.2 al 29 luglio 2026. Installate la versione fissata invece di quella più recente:

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

--locked esegue la build usando le versioni delle dipendenze con cui il crate è stato pubblicato, evitando che la build cambi in modo imprevisto. skillspec --version dovrebbe stampare 0.2.2. Un numero diverso indica che nel proprio PATH sta prevalendo un binario precedente.

Prassi del fornitore. 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 gli aspetti legati alla scala, il meccanismo è la normale integrazione continua (CI). Prima del merge, ogni skill supera linter che verificano i metadati frontmatter, il numero di righe, la struttura delle directory e la denominazione. Un link checker interrompe la build per qualsiasi URL che restituisca 404 e rileva così i link plausibili inventati da un agent. Gli autori devono fornire, insieme alla skill, una suite di prompt di valutazione e una griglia di scoring. I job di valutazione pianificati vengono poi eseguiti ogni settimana sull'intera libreria per rilevare le regressioni. Ogni skill ha inoltre un responsabile nominativo, che deve intervenire quando la qualità diminuisce.

Lo schema alla base di tutte e tre le risposte

Non è necessario sceglierne una. Alla base c’è un’unica struttura, e git in forma semplice mette a disposizione tutto ciò che serve.

1. Un’unica fonte autorevole. La skill ha una sola posizione, e ogni repository fa riferimento a quella posizione invece di conservarne una copia.
2. Una versione fissata per repository. Ogni progetto registra la revisione esatta che utilizza. L’aggiornamento consiste quindi in un commit eseguito nel progetto, con autore e data.
3. Un test di fumo per ogni skill. Un singolo controllo eseguibile dimostra che la skill produce ancora il risultato previsto.
4. Un percorso di revisione. Una modifica a una skill condivisa passa dalla revisione, e ogni utilizzatore vede 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 dedicati. Per questo, la scelta più sicura è usare gli strumenti di cui già ti fidi.

Un layout per un piccolo team su un remote Git self-hosted

Un repository contiene le competenze operative. 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 utente dovrebbe voler eseguire 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 bare repository accessibile tramite SSH sul vostro VPS, quanto segue non cambia. In questo caso servono soltanto git e un symlink.

Pinning con un sottomodulo Git

Un sottomodulo registra nel repository un commit esatto 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 collegamento simbolico è l'elemento che rende possibile questo meccanismo. Una voce skill a livello di progetto può essere un collegamento simbolico a una directory in un'altra posizione del disco; 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.

Controlla il pin:

git submodule status

Una riga corretta inizia con uno spazio, quindi mostra 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; di conseguenza .claude/skills/api-review non punta a nulla e la skill non viene caricata, senza messaggi di errore. Correggi il problema con git submodule update --init. Un + iniziale indica che il commit estratto è diverso da quello registrato; pertanto quel developer esegue istruzioni che nessun altro ha. I nuovi cloni richiedono git clone --recurse-submodules. Questa riga deve essere inclusa nel README, perché un clone normale lascia vendor/agent-skills vuoto e non visualizza errori.

L'aggiornamento è intenzionale, ed è proprio questo lo scopo del pin:

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 sarà applicata in tutti gli altri repository che utilizzano il sottomodulo e può essere inclusa in una pull request.

Impostare il pinning tramite 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 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"
      }
    }
  ]
}

Qui intervengono due origini diverse e confonderle è l’errore più comune. 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 nel catalogo accetta entrambe le opzioni. Quando sono impostate entrambe, sha è il pin effettivo. Il pin sull’esatto commit deve quindi trovarsi nella voce del catalogo.

Ogni repository che utilizza il marketplace lo dichiara nel proprio .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 collega che considera attendibile la cartella del progetto riceve la richiesta di installare il marketplace. Il plugin viene quindi abilitato senza dover consultare una pagina wiki che spiega come farlo. Le skill rispondono quindi a /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 avente lo stesso nome. Dopo aver pubblicato un nuovo tag, i consumer aggiornano il marketplace con /plugin marketplace update acme-agents. Eseguono quindi /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 un 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: inserisci /skill-name nella stringa del prompt, dove 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 unico errore intenzionale. L'asserzione verifica che la skill lo identifichi. jq -e termina con codice diverso da zero quando il relativo filtro produce null; pertanto, lo script non supera il test se la skill smette di rilevare l'errore inserito nel fixture. claude termina con codice diverso da zero quando l'esecuzione non riesce, mentre set -euo pipefail converte entrambe le condizioni di errore in un test non superato.

Il modello riformula le risposte tra un'esecuzione e l'altra. Non verificare quindi una frase completa. Verifica invece un identificatore che la skill deve emettere oppure un campo dello schema richiesto, e mantieni il fixture di dimensioni ridotte per contenere il costo dell'esecuzione.

In CI, aggiungi --bare. Senza questa opzione, claude -p carica lo stesso contesto di una sessione interattiva, inclusi hook, plugin e CLAUDE.md presenti sulla macchina da cui viene eseguito. La configurazione personale di un membro del team può quindi modificare il risultato. La modalità bare disabilita tutta la discovery automatica e, di conseguenza, esclude anche la skill che stai testando: carica esplicitamente quella skill. La modalità bare non legge neppure il login dell'abbonamento, quindi imposta 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. Interrompi il job CI se plugin_errors non è vuoto. In questo modo rilevi un pin indirizzato a una revisione che non esiste più; altrimenti l'agente potrebbe ignorare silenziosamente le regole interne.

Una skill condivisa è un’istruzione eseguibile

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

Per prima cosa, un 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 accenti gravi 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 autorizzazione diventa effettiva quando qualcuno accetta la finestra di dialogo relativa all’attendibilità dell’area di lavoro per la directory. La documentazione di Claude Code indica chiaramente la conseguenza: esaminare le skill di progetto prima di considerare attendibile un repository, perché una skill può concedersi un accesso ampio agli strumenti.

Gestisci quindi l’aggiornamento di una skill esattamente come l’aggiornamento di una dipendenza. Blocca il riferimento a un commit preciso quando il meccanismo lo consente, perché un tag può essere spostato e un branch cambia per definizione. Su una macchina con restrizioni, "disableSkillShellExecution": true nelle impostazioni sostituisce ogni sostituzione di comando con il testo letterale [shell command execution disabled by policy] invece di eseguirla; se viene applicata tramite impostazioni gestite, l’utente non può ignorarla. Le skill incluse e quelle gestite sono escluse da questa impostazione.

La stessa cautela vale per i contenuti letti da una skill. Una skill che esegue env o apre un file di configurazione inserisce nel contesto del modello tutto ciò che trova; questo è il problema descritto in tenere i secret fuori dagli agent che esegui. Una skill che recupera una pagina o esegue una query espone lo stesso contenuto verso l’esterno: il testo recuperato finisce nel contesto e appare esattamente come le istruzioni scritte da te. È un confine che conviene comprendere prima di indirizzare un agent verso la propria istanza SearXNG per le ricerche web.

Cosa leggere quando si aggiorna una versione

• Il diff del corpo di ogni SKILL.md, perché quel testo contiene le istruzioni che seguirà l'agente.
• Ogni sostituzione di comando, perché viene eseguita sul computer in uso quando viene caricata la skill.
• 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 fa riferimento dovrebbe avere un'esecuzione completata correttamente.

Se un revisore non riesce a leggere l'intero diff in dieci minuti, la skill è diventata troppo grande. Dividetela. Lo stesso vale per i documenti del repository che gli agenti leggono: mantenete le regole durature nei file descritti in la separazione tra AGENTS.md e HUMAN.md, le motivazioni architetturali in un DESIGN.md scritto per gli agenti e limitate le skill a procedure circoscritte.

Quando una modifica al modello o allo strumento rompe una skill

Diversi elementi alla base di una skill possono cambiare senza che nessuno la modifichi. Un aggiornamento del modello può ridurre l'affidabilità con cui vengono seguite istruzioni lunghe. Di conseguenza, una skill che dipendeva dal raggiungimento del passaggio nove da parte del modello potrebbe non arrivarci più. Uno strumento a riga di comando può rinominare un flag. L'agente esegue quindi il flag precedente, legge l'errore e improvvisa. Un URL indicato nella skill può iniziare a restituire 404. Un harness dell'agente può cambiare il modo in cui seleziona le skill. Di conseguenza, un description che prima prevaleva nella corrispondenza potrebbe non essere più selezionato.

Per questo, in questa configurazione, il test smoke è essenziale. Eseguite il test di ogni skill secondo una pianificazione e anche dopo 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 job cron settimanale su un piccolo VPS. È l'unico modo per rilevare il problema prima che lo segnali 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 aggiungete, invece, è una scelta vincolata a un singolo vendor. Scrivere skill che continuano a funzionare dopo la sostituzione del modello è una disciplina distinta, descritta in creare una skill compatibile con qualsiasi modello.

FAQ

Come posso condividere una skill dell'agente tra più repository?

Inserisci la skill in un repository git dedicato, assegna un 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 .claude/settings.json del repository che lo utilizza. In entrambi i casi, la versione viene registrata nella cronologia git, quindi è possibile determinare quali istruzioni hanno prodotto una determinata esecuzione dell'agente.

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

Non dall'interno di SKILL.md, perché quel frontmatter non dispone della 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 del plugin accetta ref per un branch o un tag e sha per un commit esatto; quando sono presenti entrambi, prevale sha. La sorgente del marketplace accetta soltanto ref. È preferibile usare il pin del commit, perché un tag può essere spostato dopo la revisione.

Che cosa deve verificare uno smoke test di una 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 preciso, mentre jq -e interrompe lo script quando 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é contiene istruzioni eseguibili. Una SKILL.md può eseguire comandi shell al momento del caricamento tramite la forma di sostituzione dei comandi !, mentre il campo allowed-tools del frontmatter può autorizzare preventivamente gli strumenti senza mostrare una richiesta di conferma. Esamina il diff a ogni aggiornamento, usa un commit esatto invece di un branch e preferisci una sorgente sotto il controllo del tuo team. Sulle macchine gestite, "disableSkillShellExecution": true nelle impostazioni impedisce del tutto l'esecuzione delle sostituzioni dei comandi.

Una skill condivisa funziona anche con agenti 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. Per questo motivo, rimuovile dalle skill che intendi condividere ampiamente.