Come funziona

#Come funzionano gli aggiornamenti

mestiere fissa ogni skill a un commit del registry, come fanno i lockfile dei pacchetti. Chi scrive un registry non deve taggare le versioni.

• add risolve il ref del registry e fissa le nuove skill a quel commit.
• outdated scarica il registry ed elenca le skill il cui contenuto è cambiato. Un nuovo commit che non tocca una skill non viene segnalato.
• update sposta in avanti il lock, per tutto o solo per i target che indichi. Aggiornare un namespace prende anche le skill aggiunte e toglie quelle cancellate.
• sync installa esattamente quello che dice il lock. sync --frozen fallisce se install e lock non coincidono, ed è quello che deve eseguire la CI.

Fissa un intero progetto con ref: v2026.10 (un tag) o con l'ID di un commit.

#Modello di sicurezza

Il lock è l'unico stato che mestiere conserva. Non ci sono database nascosti o file marker che possono andare fuori sync. Prima di sostituire o cancellare una cartella, mestiere controlla la cartella stessa:

1. Calcola l'hash del tree git della cartella su disco, saltando i file nascosti come .DS_Store e i file di swap degli editor.
2. Cerca la skill del registry che corrisponde al nome della cartella, e ogni versione che quella skill ha avuto nella storia del registry.
3. Solo se l'hash corrisponde a una di quelle versioni la cartella è un'installazione intatta, e solo allora si può sostituire o rimuovere senza rischi.

Per ogni cartella in una directory di skill:

• Nel lock, l'hash corrisponde alla versione nel lock: niente da fare.
• Nel lock, l'hash corrisponde a una versione pubblicata più vecchia: aggiornata alla versione nel lock.
• Nel lock, l'hash non corrisponde a nessuna versione pubblicata: sync si ferma. La cartella ha modifiche locali; usa --force o eject.
• Non nel lock, nome e contenuto corrispondono a una skill pubblicata: rimossa, perché è stata tolta da skills.yaml.
• Non nel lock, qualsiasi altro caso: lasciata com'è. È una tua skill.

--force è sempre una scelta esplicita. Lo stesso controllo fa funzionare i flussi di lavoro abituali del team senza passaggi in più:

#Architettura

• Registry (git): skills/<namespace>/<skill>/SKILL.md e skills/<namespace>/_shared/.
• Cache locale: un mirror git bare per ogni registry, riempito con git fetch.
• Progetto: skills.yaml (install e lock), .agents/skills/<namespace>-<skill>/ con i file veri, e symlink da .claude/skills/ e .kiro/skills/.

add e update risolvono install sul mirror del registry e scrivono lock. sync confronta il lock con le cartelle delle skill su disco e applica solo i passaggi che può dimostrare sicuri: install, upgrade, link, unlink, remove.

#Scelte di progettazione

• Il binario git di sistema, non una libreria git in Go, così l'autenticazione funziona esattamente come per il tuo git.
• Gli hash dei tree git come identità del contenuto. L'identità di una skill è il tree ID della sua cartella installata, quindi le modifiche si rilevano per singola skill. Per le skill senza link condivisi è il tree ID del registry stesso.
• La storia come prova di proprietà. La proprietà non viene mai registrata in un file di stato. Si decide in base al fatto che il contenuto di una cartella sia mai stato pubblicato.
• Installazioni piatte, registry con namespace. Gli harness trovano le skill a un solo livello di profondità, quindi i namespace esistono nel registry e nei nomi installati, non come cartelle.
• Le scritture passano per una cartella temporanea accanto a quella finale, che poi viene rinominata al suo posto, così un'esecuzione interrotta non lascia mai una skill scritta a metà.