Condividere skill tra repository senza divergenze
Scopri come gestire le skill come dipendenze: un repository condiviso, tag fissati per progetto, smoke test e revisione degli aggiornamenti.
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 dei tag e fate in modo che ogni progetto fissi un tag. Aggiungete quindi uno smoke test per ogni competenza e sottoponete ogni aggiornamento alla stessa revisione prevista per l'aggiornamento di una dipendenza.
Il processo si articola in quattro parti: una fonte di riferimento condivisa, una versione fissata per ogni repository, uno smoke test per ogni competenza e un processo di revisione. Le sezioni seguenti spiegano perché esiste ciascuna parte, come gli strumenti rilasciati nel 2026 gestiscono questo aspetto e come realizzare l'intero sistema su un server git self-hosted, senza usare servizi git esterni né un registro di pacchetti. Gli smoke test sono l'unica eccezione. Eseguono Claude Code, che invia ogni richiesta a un'API del modello; questo passaggio quindi esce ancora dal server.
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 riguarda la catena di fornitura che supporta tale unità.
Dove risiede una skill e perché condividerla è difficile
Claude Code carica le skill dalle seguenti posizioni, tra le altre, e la documentazione sulle skill elenca ogni percorso.
.claude/skills/<skill-name>/SKILL.mdnella directory delle impostazioni gestite è la posizione aziendale. Viene caricata per ogni utente sui computer in cui un'organizzazione la distribuisce.~/.claude/skills/<skill-name>/SKILL.mdè personale. Viene caricata in tutti i tuoi progetti e in nessun progetto di altri utenti..claude/skills/<skill-name>/SKILL.mdè a livello di progetto. Viene caricata da chiunque effettui il checkout di quel repository.<plugin>/skills/<skill-name>/SKILL.mdè inclusa in un plugin. Viene caricata ovunque quel plugin sia abilitato.
Claude Code carica inoltre le skill dalle directory di progetto annidate, dalle directory fornite con --add-dir e dalle skill abilitate per il tuo account claude.ai.
Quella a livello di progetto è la soluzione utile per un team, perché viene inclusa nel repository e tutti gli utenti che ne eseguono il clone la ricevono. È 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 è utile. 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, nameNota cosa manca: non esiste alcuna chiave version. Una versione può essere registrata in metadata, ma la specifica non definisce alcun meccanismo per bloccare le dipendenze o aggiornarle. È ragionevole, perché una skill è un documento, non un pacchetto. Questo significa però che il versionamento deve provenire dal livello che circonda il 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 rilasciati nel 2026
In questo periodo stanno arrivando diverse soluzioni, ma non concordano su dove debba risiedere la versione.
File di lock. Lo strumento da riga di comando skills di Vercel Labs (vercel-labs/skills, con licenza MIT, v1.7.2 al 9 ottobre 2026) installa le skill da un repository git nella directory prevista dall'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. Mantiene due file di lock. Quello globale, in ~/.agents/.skill-lock.json, registra ciò che è stato installato da un utente. Dalla v1.4.1 (20 febbraio 2026), l'installazione a livello di progetto scrive anche skills-lock.json nella directory radice del progetto, e il codice sorgente dello strumento indica che questo file deve essere incluso nel controllo versione. npx skills experimental_install ripristina le skill di un progetto da questo file. L'issue 283, che richiedeva un comando skills install per ripristinare il file di lock globale su un altro computer, è stata chiusa come non pianificata il 5 novembre 2026; il maintainer la identifica come la stessa richiesta dell'issue 549. Considerate entrambe come un'indicazione dello stato attuale. Il file di lock per progetto esiste. Nella v1.8.1 rilasciata, il comando di ripristino è ancora contrassegnato come sperimentale nell'help, ma npx skills install senza indicare una sorgente ripristina comunque il file di lock del progetto.
Specifiche e test. SkillSpec segue l'approccio opposto. Considera 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> mostra il contenuto della skill, mentre skillspec boundary assess <path> segnala ciò che può raggiungere, ordinato per livello di rischio. È un crate Rust con doppia licenza MIT o Apache 2.0. La versione 0.2.2 è stata pubblicata il 29 luglio 2026 ed è ancora la più recente su crates.io al 10 ottobre 2026. Installate la versione fissata invece di quella più recente:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionA partire da Cargo 1.100, rilasciato il 12 novembre 2026, cargo install usa per impostazione predefinita il file di lock incluso nel pacchetto e --locked non esegue alcuna operazione. skillspec --version dovrebbe stampare 0.2.2. Un numero diverso indica che nel vostro PATH è presente un binario più vecchio che ha la precedenza.
Pratiche dei vendor. Google ha descritto come crea le skill in google/skills in un post su come crea, testa e porta su larga scala le skill per agent. Eliminando il fattore scala, il meccanismo è la normale integrazione continua (CI). Prima del merge, ogni skill supera i linter per i metadati frontmatter, il numero di righe, la struttura delle directory e la denominazione. Un link checker interrompe la build per qualsiasi URL che restituisce 404, intercettando così 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 job di valutazione pianificati vengono quindi eseguiti ogni settimana sull'intera libreria per rilevare le regressioni, e ogni skill ha un owner nominato 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.
- 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.
- 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.
- Un test di verifica per ogni skill. Un controllo eseguibile dimostra che la skill continua a produrre il risultato previsto.
- 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.mdLe 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.0Se 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 statusUna 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 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 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"
}
}
]
}Qui entrano in gioco due origini diverse, e confonderle è l’errore più comune. L’origine del marketplace, cioè il punto da cui viene recuperato il catalogo, accetta ref per un branch o un tag e, in Claude Code v2.1.324 o versioni successive, un commit SHA completo in minuscolo; non accetta un campo sha separato. Un’origine di plugin all’interno del catalogo accetta entrambi e, quando sono impostati entrambi, sha è il pin effettivo. Fissa il catalogo tramite ref nell’origine del marketplace e il plugin tramite sha nella voce del catalogo. Anche i nomi dei tipi sono diversi. Nel catalogo, url indica un repository git da clonare. In un’origine del marketplace, url indica un collegamento diretto a un file marketplace.json, mentre un repository git è git.
Ogni repository che utilizza il plugin dichiara quindi il marketplace nel proprio .claude/settings.json versionato:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code registra il marketplace per un membro del team quando accetta la finestra di dialogo per considerare attendibile l’area di lavoro relativa alla cartella del progetto, senza che una pagina wiki debba spiegargli come farlo. La voce del catalogo punta a un URL git anziché a un percorso relativo, quindi il plugin non viene installato soltanto dalle impostazioni del repository. Ogni membro del team esegue claude plugin install team-skills@acme-agents --scope project una volta; fino a quel momento Claude Code segnala che il plugin è abilitato nelle impostazioni del progetto, ma non è installato. Le skill rispondono quindi a /team-skills:api-review, perché le skill dei plugin usano uno spazio dei nomi basato sul nome del plugin e non possono entrare in conflitto con una skill di progetto con lo stesso nome. Dopo avere pubblicato un nuovo tag e aggiornato i pin nel catalogo e nei repository che utilizzano il plugin, i consumer eseguono /plugin marketplace update acme-agents, quindi /reload-plugins se il riepilogo dell’installazione lo richiede.
Scrivere uno smoke test per una skill
Uno smoke test è un'esecuzione scriptata dell'agent su un fixture con un errore noto, più un'asserzione. Claude Code viene eseguito in modalità non interattiva tramite -p e una skill invocata dall'utente funziona anche in questo contesto: inserisci /skill-name nella stringa del prompt, dove viene espansa 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/nullfixtures/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 non rileva più l'errore inserito nel fixture, lo script fallisce. Anche claude restituisce un codice diverso da zero quando l'esecuzione fallisce e set -euo pipefail converte uno dei due errori in un test fallito.
Tra un'esecuzione e l'altra, un modello riformula le risposte. Non verificare quindi una frase completa. Verifica invece un identificatore che la skill deve produrre oppure un campo dello schema richiesto. Mantieni il fixture ridotto, così l'esecuzione resta economica.
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 in cui viene eseguito. La configurazione personale di un membro del team può quindi modificare il risultato. La modalità bare ignora l'auto-discovery, ad eccezione delle skill presenti in .claude/skills/ sotto una directory fornita esplicitamente con --add-dir; per questo salta la skill del progetto che stai testando e devi caricarla in modo esplicito. La modalità bare non legge nemmeno 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 jsonUn plugin caricato con --plugin-dir ricava il proprio nome da .claude-plugin/plugin.json. Se quel manifest manca, il plugin viene denominato in base alla directory. Esegui il commit di un plugin.json con "name": "team-skills" accanto al catalogo nel repository delle skill; in alternativa, il comando precedente deve chiamare /agent-skills:api-review.
Con --output-format stream-json, l'evento system/init indica quali plugin sono stati caricati e include un array plugin_errors per quelli che non sono stati caricati. L'evento apre lo stream, a meno che non venga preceduto dagli eventi di avvio. Fai fallire il job CI quando plugin_errors non è vuoto. In questo modo rilevi un pin indirizzato a una revisione che non esiste più, situazione che altrimenti si manifesta con un agent che ignora silenziosamente le regole interne.
Un’abilità condivisa è un’istruzione eseguibile
Due funzionalità lo rendono letteralmente vero, 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 esegue una fase di pre-elaborazione:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Il comando viene eseguito sulla macchina che carica l’abilità 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. Durante l’esecuzione non viene richiesto alcun consenso. Claude Code verifica ogni comando in base alle regole di autorizzazione. Al di fuori della modalità automatica, un comando non consentito da tali regole interrompe l’abilità, a meno che l’abilità non lo abbia pre-approvato tramite la seconda funzionalità descritta di seguito. Le regole di negazione e di richiesta di conferma hanno comunque la precedenza su tale pre-approvazione. Leggere un’abilità condivisa significa quindi leggere anche le sostituzioni dei comandi.
In secondo luogo, il frontmatter può pre-approvare gli strumenti. allowed-tools concede gli strumenti elencati senza mostrare una richiesta di autorizzazione per il turno che ha invocato l’abilità. La considerazione dell’attendibilità del workspace non limita questa concessione: Claude Code applica allowed-tools di un’abilità di progetto anche durante un’esecuzione -p in una directory che nessuno ha contrassegnato come attendibile. La documentazione di Claude Code descrive chiaramente la conseguenza: un’abilità può concedersi un accesso ampio agli strumenti, quindi esamina allowed-tools delle abilità archiviate in un repository prima di eseguire Claude Code al suo interno. Un’organizzazione può impedire l’uso di questo campo nelle abilità di progetto e personali impostando allowManagedPermissionRulesOnly nelle impostazioni gestite; questa opzione richiede Claude Code v2.1.282 o versioni successive.
Tratta quindi un aggiornamento di un’abilità esattamente come un aggiornamento di una dipendenza. Quando il meccanismo lo consente, usa il commit esatto come riferimento, perché un tag può essere spostato e un branch cambia per definizione. Su una macchina con accesso limitato, "disableSkillShellExecution": true nelle impostazioni sostituisce ogni sostituzione di comando con il testo letterale [shell command execution disabled by policy] invece di eseguirla; se l’impostazione viene applicata tramite le impostazioni gestite, l’utente non può sovrascriverla. Le abilità integrate e gestite sono escluse da questa impostazione.
La stessa cautela si applica ai contenuti letti da un’abilità. Un’abilità che esegue env o apre un file di configurazione porta nel contesto del modello tutto ciò che trova; è il problema descritto in mantenere i secret fuori dagli agenti che esegui. Un’abilità che recupera una pagina o esegue una query espone lo stesso contesto verso l’esterno, perché il testo recuperato viene inserito nel contesto e appare esattamente come le istruzioni scritte dall’utente. È 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 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 una skill dell'agente 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 sottomodulo git registra un commit esatto e un symlink da .claude/skills/<name> al sottomodulo fa sì che la skill venga caricata come una normale skill del progetto. Un marketplace di plugin 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 resta nella cronologia git, quindi puoi stabilire quali istruzioni hanno prodotto una determinata esecuzione dell'agente.
Posso associare una skill dell'agente a una versione specifica?
Non dall'interno di SKILL.md, perché quel frontmatter non dispone di una chiave version. Il pin deve provenire dal livello che gestisce il file. Un sottomodulo git associa per sua natura un commit esatto. In un marketplace di plugin Claude Code, una sorgente del 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 ref per un branch, un tag oppure, in Claude Code v2.1.324 o versioni successive, uno SHA completo del commit in lettere minuscole. È 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 qualcosa di stabile. Esegui la skill in modalità non interattiva su un fixture che contiene un problema noto, quindi controlla che nell'output compaia un identificatore specifico, ad esempio l'ID di una regola che la skill dovrebbe segnalare. Richiedere un output strutturato con --output-format json e --json-schema rende il controllo esatto, mentre jq -e fa fallire lo script se il valore manca. Non verificare mai una frase completa, perché il modello può riformulare le risposte tra un'esecuzione e l'altra.
È sicuro installare una skill condivisa dal repository di un altro team?
Considerala una dipendenza software, 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 in anticipo gli strumenti senza richiedere una conferma. Esamina il diff a ogni aggiornamento, assegna il pin a un commit esatto invece che a un branch e preferisci una sorgente controllata dal tuo team. Sulle macchine gestite, "disableSkillShellExecution": true nelle impostazioni impedisce l'esecuzione delle sostituzioni dei comandi nelle skill utente, di progetto, dei plugin e delle directory aggiuntive; le skill incluse e gestite sono escluse.
Una skill condivisa funzionerà in 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; perciò, escludile dalle skill che intendi condividere ampiamente.