1. Cos'è una skill, in trenta secondi

Una skill è un pacchetto che descrive come usare un servizio o una famiglia di funzioni. Il suo punto d'ingresso è SKILL.md; il pacchetto può includere anche script e riferimenti necessari all'esecuzione. Metnos non lo esegue direttamente: lo traduce 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 e possono essere richiamati in linguaggio naturale; il manifest continua però 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 firma il risultato. Questo riduce e rende osservabile l'autorità concessa, ma non certifica come innocuo il codice di terzi: provenienza e sorgente restano da valutare.

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 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 descrizioni e termini di affinità in italiano e in inglese; se non è disponibile, il generatore usa un testo deterministico di riserva.
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 di audit 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 sono conservate nella cache locale per un massimo predefinito di sette giorni; l'operatore può forzare un nuovo recupero.

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.

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

Chiedi a Metnos con una richiesta come quella di questo esempio: «Che appuntamenti ho domani nel calendario di lavoro?» Se la capacità Google Workspace è ammessa, abilitata e collegata all'account dell'utente, il catalogo rende disponibile l'executor specifico per gli eventi. Altri esempi sono «Trova le email non lette di Anna», «Leggi il contenuto di questo file su Drive» e «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 esegue un'analisi statica completa di ogni script ricevuto. Prima dell'importazione l'operatore deve verificare origine e impronta, leggere gli script e concedere soltanto capacità e credenziali necessarie.

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