pnpm 12.11.0: test pratico delle autorizzazioni Skills — che cosa significa davvero «approvare una volta»?

Descrizione: sulla base del codice sorgente di pnpm v12.11.0 e della documentazione relativa a quella versione, esamino dove vengono individuate le Skills, come funzionano l’approvazione e il collegamento e verifico i rami principali con un modello sintetico indipendente. L’obiettivo è aiutare gli sviluppatori a valutare gli aggiornamenti delle dipendenze e le modalità di gestione delle autorizzazioni.

Ambito di rilevamento e limiti delle autorizzazioni

All’inizio avevo semplificato troppo la questione: se una dipendenza contiene un file SKILL.md, pnpm lo installa nella directory dell’Agent oppure lo ignora del tutto. Seguendo il codice sorgente della versione esatta pnpm 12.11.0, ho scoperto che nel mezzo ci sono diversi passaggi: rilevamento, verifica delle autorizzazioni e collegamento. Sono proprio questi confini a determinare che cosa significhi «approvare una volta».

Per prima cosa ho seguito la logica di rilevamento, pensando che bastasse trovare un file Skill nell’albero delle dipendenze per avviare il flusso di approvazione. Ho invece scoperto che la scansione è più circoscritta: pnpm controlla le dipendenze dirette di ogni importer del workspace nel lockfile e scansiona un solo livello di directory Skills. Le dipendenze indirette non rientrano in questo percorso di rilevamento, quindi «un file è presente nell’albero delle dipendenze» non equivale a «pnpm lo rileva».

Poi ho esaminato separatamente installazione, collegamento e caricamento da parte dell’Agent. I file del pacchetto possono essere già presenti nella directory delle dipendenze; lo stato delle autorizzazioni determina se pnpm crea un collegamento simbolico alla directory di destinazione; in seguito, spetta a Claude Code o agli altri Agent decidere se leggere quei file e come gestirli. Il codice sorgente di pnpm si occupa dei collegamenti: non interpreta né esegue il contenuto delle Skills.

I rami delle autorizzazioni comprendono gli stati in attesa di approvazione, rifiutato e approvato. L’approvazione viene gestita a livello di pacchetto: pnpm approve riguarda sia gli script di build sia le autorizzazioni Skills. Questo non equivale a esaminare ogni singolo file. Le autorizzazioni per gli script di build e permissions.skills sono ambiti distinti: approvare gli script di build di un pacchetto non significa che il contenuto delle Skills sia stato sottoposto a una revisione separata.

Il punto su cui mi sono soffermato di più è l’ambito dell’approvazione. La documentazione ufficiale di v12.11.0 chiarisce che un’approvazione a livello di pacchetto copre tutte le Skills di quella dipendenza e resta valida anche per le sue versioni successive. In fase di aggiornamento, quindi, bisogna prestare attenzione alle modifiche delle istruzioni introdotte dalle nuove versioni: lo stato di approvazione precedente potrebbe continuare ad applicarsi, mentre la nuova versione potrebbe aggiungere o modificare una Skill.

Se nel workspace sono presenti più versioni utilizzabili, il codice sorgente seleziona la versione più alta tra quelle idonee del registry che risultano installate. Questo può determinare quale contenuto viene effettivamente collegato, quindi non basta controllare l’intervallo di versioni in package.json. Per capire che cosa potrebbe leggere l’Agent dopo un aggiornamento, occorre verificare anche la versione del pacchetto effettivamente selezionata e le Skills che contiene.

Anche la directory di destinazione è soggetta a condizioni precise. In v12.11.0 vengono considerate le variabili d’ambiente CLAUDECODE, CURSOR_AGENT e GEMINI_CLI, oppure le directory Agent Skills già presenti nel workspace; skills.dirs consente di specificarle esplicitamente. Una configurazione esplicita vuota disabilita le Skills; se al momento dell’approvazione non viene rilevata automaticamente alcuna directory di destinazione, viene generato un errore per destinazione mancante.

# pnpm-workspace.yaml
skills:
  dirs:
    - .claude/skills
    - .cursor/skills

Pensavo anche che revocare le autorizzazioni avrebbe eliminato i contenuti nelle directory interessate. Il codice sorgente e il modello indipendente del file system mostrano un perimetro più ristretto: nel modello vengono rimossi i collegamenti creati da esso, mentre le Skills locali create manualmente restano intatte; inoltre, un percorso di destinazione già occupato da una directory reale non viene sostituito. Anche i casi di rimozione del pacchetto e di directory di destinazione mancante vanno interpretati secondo le rispettive logiche di pulizia dei collegamenti e gestione degli errori.

Modello sintetico e risultati dei test

Per rendere concreti questi rami, ho realizzato con la libreria standard di Node 22.16.0 un modello indipendente di file system sintetico: crea dipendenze fittizie temporanee, file SKILL.md sintetici e collegamenti simbolici, quindi calcola le impronte digitali dei contenuti. Otto scenari coprono, rispettivamente, l’attesa di approvazione, il rifiuto, l’approvazione, una Skill aggiunta dopo l’aggiornamento, la revoca, un conflitto di percorso, una dipendenza esclusivamente indiretta e l’assenza di una directory di destinazione rilevata automaticamente.

Tutti e otto gli scenari del modello sono stati superati. Nel caso dell’aggiornamento, ho osservato un cambiamento dell’impronta digitale del contenuto e la comparsa di un secondo collegamento a una Skill. Alla prima esecuzione, uno scenario non è riuscito perché usavo «il numero di collegamenti attesi è zero» per stabilire se fosse presente una Skill approvata: così ho classificato erroneamente il caso «nessuna directory di destinazione». Dopo aver individuato il problema, ho modificato il controllo per verificare separatamente il numero di Skills approvate; alla nuova esecuzione, tutti e otto gli scenari sono stati superati.

Verifiche nel repository e ambito di applicazione

Per verificare un repository, si può iniziare con pnpm permissions o pnpm permissions list per controllare le autorizzazioni, quindi confrontare i risultati con la configurazione del workspace. Dopo l’aggiornamento di una dipendenza, è opportuno controllare i file Skills della nuova versione e le relative differenze. Nei progetti più attenti alle modifiche delle istruzioni, si può fissare la versione della dipendenza e confrontare SKILL.md in CI.

pnpm permissions
pnpm permissions list

Limiti / restrizioni

Questa analisi si basa sul codice sorgente di pnpm v12.11.0 e sulla documentazione relativa alla versione esatta; i test usano un modello sintetico eseguito separatamente con Node e riguardano il comportamento del file system. Il modello non integra la CLI di pnpm, installazioni o aggiornamenti reali, né alcun Agent. Le regole di rilevamento ed esecuzione dei client possono inoltre variare a seconda delle rispettive versioni. Le modifiche al rilevamento dell’ambiente introdotte in pnpm 12.11.1 non vanno attribuite retroattivamente a v12.11.0. La fiducia nelle versioni successive derivante dall’approvazione a livello di pacchetto è un limite progettuale da tenere presente durante la revisione degli aggiornamenti.

Riferimenti: codice sorgente di pnpm v12.11.0 · documentazione di pnpm v12.11.0