1. Cos'è una skill, in trenta secondi

Una skill è un pacchetto di integrazione: descrive come usare un servizio o una famiglia di funzioni. Il punto d'ingresso è SKILL.md; accanto possono esserci script e documenti di riferimento. L'importazione è un'operazione amministrativa. Metnos trasforma quanto dichiarato nella skill in executor con nomi, argomenti, capacità e provenienza espliciti.

Il file contiene un'intestazione con i metadati e un corpo leggibile, nel quale trovano posto funzioni, prerequisiti, comandi ed esempi. Il parser ne ricava una struttura controllabile; non considera la prosa un'autorizzazione ad ampliare il vocabolario o le capacità del sistema.

Metnos può importare il sorgente di una skill: legge il file, ne ricava una serie di executor nel proprio formato e sottopone ciascuno ai controlli di ammissione. Quelli ammessi entrano nello stesso catalogo degli altri executor. Diventano utilizzabili quando sono anche firmati, abilitati e non risultano inattivi per una dipendenza mancante. Il manifest continua a registrarne l'origine esterna.

Perché non eseguire direttamente la skill

Un file SKILL.md non porta con sé la firma e il contratto di un executor Metnos. L'importazione genera un wrapper, dichiara capacità e argomenti nel manifest, applica i controlli di ammissione e prova a firmare ciascun executor accettato. Il wrapper può poi richiamare gli script del pacchetto, ma lo fa entro il normale percorso di esecuzione di Metnos. Questo rende l'autorità concessa più circoscritta e osservabile; non dimostra però che il codice di terzi sia innocuo.

2. Dal file SKILL al catalogo

Il comando di importazione avvia una sequenza di passaggi distinti. Questa separazione è importante: una traduzione riuscita non equivale ancora all'ammissione nel catalogo.

1. Acquisizione. Metnos risolve il percorso o l'URL, recupera la sorgente e calcola l'impronta del solo file SKILL.md.
2. Lettura. Il parser estrae metadati, dipendenze, script, file di credenziali richiesti e sotto-comandi con i relativi argomenti.
3. Traduzione. Ogni sotto-comando viene ricondotto a un nome canonico nel formato azione_oggetto_qualificatore. Il nome del fornitore qualifica gli executor importati e le collisioni interne alla skill vengono rifiutate.
4. Generazione. Template controllati producono il wrapper Python, il manifest TOML e lo stato linguistico. Un modello linguistico può proporre le descrizioni in italiano e inglese e una lista di espressioni di affinità; se non è disponibile, il generatore usa un testo deterministico. La lista di affinità non è ancora separata per lingua: è il limite seguito dal TODO prioritario AFF-I18N-001.
5. Ammissione. Il runtime verifica unicità del binding, nome canonico, sovrapposizioni di affinità, instradamento e coerenza semantica fra manifest e codice.
6. Firma. Le cartelle rifiutate vengono eliminate. Gli executor accettati vengono firmati con Ed25519; senza una firma valida il loader non li rende disponibili.
7. Registrazione. L'esito entra nel registro dell'importazione e, per i casi mappabili, nella batteria persistente di prove di instradamento. Il catalogo li vede al successivo caricamento valido.

La traduzione di nomi e argomenti è procedurale rispetto alla sorgente e al vocabolario correnti. L'intera importazione, invece, non promette un output identico byte per byte: la provenienza contiene l'istante di importazione, le descrizioni possono essere generate da un modello e l'ammissione dipende dal catalogo già installato e dal verificatore semantico disponibile.

Il vocabolario chiuso

Metnos accetta soltanto azioni e oggetti definiti nel vocabolario del runtime. Una skill che parla di append rows to spreadsheet non può inventare append_rows: deve essere ricondotta a un nome canonico compatibile. Se non esiste una corrispondenza semanticamente corretta, il sotto-comando viene rifiutato. In questo modo sinonimi e formule proprie della skill non introducono nuovi verbi in modo implicito.

3. Sorgenti supportate

La skill può arrivare da tre posti:

• Locale: un file SKILL.md o una cartella che lo contiene. Gli eventuali scripts/ e references/ adiacenti vengono conservati insieme alla sorgente.
• agentskills.io: un indirizzo del tipo agentskills.io/<autore>/<skill>; l'importatore lo risolve nel file SKILL.md pubblicato nella radice del repository atteso.
• GitHub diretto: l'URL completo di un repository viene clonato con i file di supporto; un URL raw scarica invece soltanto il file indicato.

Se una skill invoca script propri, occorre quindi importare una cartella locale completa o il repository, non il solo file raw. Le sorgenti remote presenti nella cache vengono riutilizzate per sette giorni per impostazione predefinita. Dopo la scadenza Metnos le recupera di nuovo, ma non le elimina automaticamente dalla memoria di massa; l'operatore può comunque forzare un nuovo recupero o pulire la cache.

4. File generati e provenienza

La sorgente viene conservata separatamente dagli executor generati. Con i percorsi predefiniti, entrambi gli alberi appartengono all'utente che esegue l'importazione:

~/.local/share/metnos/skills/google-workspace/
 SKILL.md
 scripts/
 references/

~/.local/share/metnos/executors/skills/google-workspace/
 read_events_google_workspace/
  read_events_google_workspace.py
  manifest.toml
  manifest.lang_state.json
  manifest.toml.sig
 send_messages_google_workspace/
  …

Prima della firma, ogni cartella contiene tre file generati: wrapper, manifest e stato linguistico. La firma aggiunge manifest.toml.sig. Script e riferimenti restano nel pacchetto sorgente e vengono richiamati dal wrapper. I vincoli della sandbox sono applicati dal runtime a partire dal contratto e dalle capacità dichiarate, senza un altro file per executor.

Il manifest conserva il legame con la sorgente:

[provenance]
synthesized       = true
imported_from     = "<origine della skill>"
source_version    = "1.1.0"
source_section    = "<sezione>"
source_subcommand = "calendar list"
imported_at       = "<istante UTC>"
source_sha256     = "<impronta del file SKILL.md>"
importer_version  = "<versione>"

Posizione, provenienza, sorgente conservata e audit distinguono un executor importato da uno curato direttamente nel prodotto. Firma, contratto e policy di esecuzione sono invece requisiti comuni: la provenienza non sostituisce nessuno di questi controlli.

Che cosa coprono davvero le impronte. source_sha256 identifica il file SKILL.md. La firma dell'executor protegge il manifest e il codice del wrapper dichiarato nel manifest. Gli script e i riferimenti copiati accanto alla skill non ricevono oggi una distinta impronta di provenienza: devono quindi essere verificati come parte del pacchetto prima dell'importazione.

5. Traduzione e controlli di ammissione

La pipeline separa i rifiuti di traduzione da quelli di ammissione. Il registro finale riporta entrambe le categorie.

I piani indipendenti possono avere esiti diversi: quelli rifiutati vengono rimossi e gli altri proseguono. La collisione globale del binding costituisce l'eccezione e interrompe l'intera importazione. Le opzioni che saltano L2, L5 o L6 servono a sviluppo e CI; usarle riduce le garanzie e non equivale a una certificazione per l'esercizio.

Il report dell'importazione è l'autorità per quella specifica esecuzione: elenca piani tradotti, nomi accettati e rifiuti con le rispettive motivazioni. Un nome accettato non dimostra, da solo, che ogni possibile asserzione L5 sia stata eseguita, perché alcuni pattern ammettono esplicitamente lo skip.

6. Credenziali e dialoghi con l'utente

L'importazione non raccoglie credenziali. Se, durante l'uso, un fornitore segnala che manca l'autenticazione, il wrapper generato restituisce decision = "needs_inputs" e conserva gli argomenti necessari a riprendere l'operazione.

1. Metnos presenta nella chat il dialogo previsto dal manifest; la chat web può aprire il modulo protetto e gli altri canali forniscono le indicazioni per raggiungerlo.
2. Per OAuth l'utente indica il file del client e l'ambito dei servizi, quindi completa l'autorizzazione nel browser.
3. Il server scambia il codice e conserva il token nell'archivio cifrato dell'utente, per impostazione predefinita sotto ~/.config/metnos/credentials/.
4. Se un fornitore compatibile richiede anche un file in una posizione propria, il manifest può dichiarare una copia locale protetta con permessi 0600.
5. Al termine Metnos riprende l'executor con gli argomenti originari.

I collegamenti e i valori delle credenziali sono isolati per utente. Il manifest dichiara soltanto il nome del binding e lo schema del dialogo: i segreti non entrano nel manifest, nel codice generato o nel testo inviato al pianificatore. Gli executor find_credentials, set_credentials e delete_credentials espongono rispettivamente metadati, scrittura protetta e cancellazione; le loro risposte al pianificatore non contengono i valori in chiaro.

7. Google Workspace: esempio completo

Per l'utente, una skill importata si presenta come qualsiasi altra capacità di Metnos. Può chiedere, per esempio: «Che appuntamenti ho domani nel calendario di lavoro?». Se Google Workspace è stato importato, ammesso, abilitato e collegato al suo account, il catalogo propone l'executor per gli eventi. Allo stesso modo può chiedere «Trova le email non lette di Anna», «Leggi il contenuto di questo file su Drive» o «Aggiungi queste righe al foglio Spese».

L'importazione è un'operazione amministrativa distinta. Il pacchetto Google Workspace incluso con Metnos contiene anche gli script necessari, per cui il comando usa la cartella completa:

metnos-skills import <install-root>/executors/skills/google-workspace

La sorgente dichiara 24 sotto-comandi. La verifica procedurale corrente dimostra 24 piani canonici distinti e nessun rifiuto di traduzione. Alcune distinzioni semantiche decisive sono:

Il dato 24/24 riguarda traduzione, unicità dei nomi e generazione dei manifest. Non autorizza a dichiarare in anticipo «24 ammessi»: L2 confronta il catalogo dell'utente, L5 dipende dalle prove eseguibili e L6 dal verificatore semantico. Il report prodotto da quella importazione indica quanti executor sono stati accettati; soltanto quelli firmati e validi possono entrare nel catalogo. L'autorizzazione OAuth avviene poi per il singolo utente e non fa parte del conteggio di importazione.

8. Confine di fiducia e controlli durante l'uso

Importare una skill non significa attestare che il suo codice sia innocuo. L'importatore controlla il wrapper e il contratto che genera, ma non analizza in modo completo ogni script ricevuto. Prima dell'importazione l'operatore deve quindi verificare l'origine dell'intero pacchetto, leggere gli script e concedere soltanto le capacità e le credenziali necessarie.

Quando bwrap è disponibile, il runtime costruisce una sandbox dal manifest e dalle capacità ammesse. Se non è disponibile o la sandbox è stata disattivata esplicitamente, l'executor resta un processo separato e continuano ad applicarsi i controlli del runtime, ma manca l'isolamento del filesystem e della rete fornito da bwrap.

Gli executor curati direttamente da Metnos seguono revisione, prove, firma e policy del rilascio; quelli importati aggiungono provenienza, ammissione e audit specifici. Nessuna delle due origini è «fidata per definizione». Nel flusso ordinario, inoltre, L6 non approva quando il verificatore è indisponibile: il piano viene rifiutato con un motivo esplicito.

9. Per andare più a fondo

Metnos — importazione delle skill