skillscript

Automazione sicura e riutilizzabile, creata da agenti.

skillscript.ai  •   documentazione 

TL;DR — npm install -g skillscript-runtime && skillfile init && skillfile dashboard. Vedi Avvio rapido.

Cos'è Skillscript?

Skillscript nasce dalla domanda: come sarebbe un Makefile se costruisse competenze invece di binari? La risposta è un linguaggio vincolato, ispirato a Make, e un runtime che trasforma il ragionamento di un agente in automazione persistente e ispezionabile. L'agente scrive la competenza, tu approvi ciò che può fare, e viene eseguita sempre allo stesso modo.

È pensato per team che vogliono che gli agenti creino ed eseguano flussi di lavoro ricorrenti senza concedere loro accesso illimitato alla shell, installazione arbitraria di pacchetti o controllo diretto delle credenziali di produzione.

Un agente scrive una competenza. Un umano la rivede e la approva. Il runtime la esegue attraverso connettori configurati, liste bianche e policy di sicurezza.

npm install -g skillscript-runtime
skillfile init
skillfile dashboard

Poi collega il tuo agente al MCP: http://localhost:7878/rpc e chiedigli di creare una competenza.

Perché usarlo?

Di solito gli agenti re-derivano compiti di routine partendo da zero. Questo aumenta costi, latenza e deriva comportamentale.

Skillscript permette a un agente di cristallizzare una procedura appresa in un artefatto nominato e riutilizzabile che può essere:

• eseguito ripetutamente senza ri-pianificare l'intero compito
• ispezionato e versionato dagli umani
• validato prima di essere ammesso
• limitato a strumenti, file, comandi e credenziali approvati
• composto con altre competenze

Skillscript è solo orchestrazione. Il calcolo rimane all'interno di strumenti e connettori; le competenze coordinano queste capacità tramite una piccola grammatica dichiarativa. Questo può ridurre significativamente l'uso di token di modelli frontier nei flussi di lavoro ricorrenti: il costo del ragionamento viene pagato una volta quando la competenza viene creata, e ogni esecuzione successiva avviene in modo deterministico, con sotto-attività di routine affidate a modelli locali più economici.

Perché non Python o Bash?

Python e Bash rimangono utili per il lavoro d'implementazione. Il rischio è permettere a script creati da agenti di essere eseguiti senza supervisione con accesso illimitato al sistema.

Skillscript restringe quella superficie di esecuzione:

• niente import arbitrari, installazione di pacchetti, eval o fuga da subprocess
• accesso ai sistemi esterni mediato da connettori
• liste bianche per shell e filesystem con negazione predefinita
• validazione statica prima dell'esecuzione
• firme opzionali dell'operatore per competenze con effetti collaterali
• credenziali gestite dal runtime, non incorporate nella competenza

L'obiettivo non è sostituire gli script. È mettere script e API dietro capacità che l'operatore espone esplicitamente.

C'è anche un motivo legato alla scalabilità. Rivedere codice arbitrario significa controllare tutto ciò che potrebbe fare, il che richiede un lettore esperto. Una skillscript mette l'intera superficie degli effetti sulla pagina, quindi l'approvazione rimane gestibile anche quando gli agenti scrivono più velocemente di quanto chiunque possa leggere il codice, e l'operatore che sa cosa i propri sistemi dovrebbero permettere può approvare basandosi sugli effetti dichiarati piuttosto che rileggere la logica.

Una competenza

Una competenza è un flusso di lavoro dichiarativo tipizzato con variabili, operazioni, dipendenze e un modello di output.

# Skill: ciao
# Status: Approvata
# Description: Saluta qualcuno per nome.
# Vars: CHI=mondo

Ciao, ${CHI}!

Questa è una competenza completa ed eseguibile. Il corpo viene renderizzato come output.

Le competenze possono anche chiamare connettori, ramificare, iterare, eseguire altre competenze, rispondere a eventi ed eseguire su pianificazioni:

# Skill: controllo-disco-giornaliero
# Status: Approvata
# Triggers: cron:"0 6 * * *"
# Autonomous: true

Istantanea scritta per ${NOW}.

istantanea:
    shell(command="df -h --output=source,pcent,target") -> USO
    file_write(
        path="/var/log/skillscript/disk-${EVENT.fired_at_unix}.txt",
        content="${USO}"
    )

default: istantanea

Il runtime rifiuterà il comando shell e la scrittura su file finché l'operatore non autorizza il binario e il percorso.

Come funziona

1. Creazione: Un agente connesso via MCP scopre gli strumenti disponibili, scrive una competenza e la analizza. In modalità protetta arriva come Bozza, inerte fino a quando non la approvi.
2. Revisione: Un umano ispeziona e approva la competenza. In modalità protetta, l'approvazione firma il contenuto approvato con una chiave detenuta dall'operatore.
3. Esecuzione: La competenza viene eseguita da CLI, MCP, cron, un evento HTTP o un'altra competenza.
4. Osservazione: Il runtime registra tracce, output, fallimenti e operazioni bloccate.

Le competenze possono svolgere tre ruoli:

Avvio rapido

1. Installa e avvia il runtime

npm install -g skillscript-runtime
skillfile init
skillfile dashboard --host 127.0.0.1 --port 7878

Apri http://localhost:7878.

Usa --host 0.0.0.0 solo quando un altro container o macchina deve raggiungere il runtime, e proteggi l'ingresso esposto in modo appropriato.

2. Aggiungi il server MCP al tuo agente

{
  "mcpServers": {
    "skillscript": {
      "type": "http",
      "url": "http://localhost:7878/rpc"
    }
  }
}

3. Chiedi all'agente di creare una competenza

Crea una competenza che saluti qualcuno per nome.

L'agente scrive la competenza tramite MCP. Approvata nella dashboard o da CLI:

skillfile approve ciao
skillfile execute ciao

Connettori e sicurezza

Le competenze accedono ai sistemi esterni attraverso connettori configurati, non tramite credenziali dirette. I connettori possono esporre strumenti MCP, archivi dati, modelli locali, canali di consegna degli agenti o capacità personalizzate del runtime.

Importanti controlli per l'operatore:

I segreti vengono risolti dal runtime e passati solo a destinazioni approvate. Le competenze non possono stampare o ispezionare i loro valori grezzi.

Vedi la guida alla configurazione e il riferimento ai connettori.

Comandi comuni

skillfile lint <competenza>
skillfile compile <competenza>
skillfile execute <competenza>
skillfile approve <competenza>
skillfile diagram <competenza>
skillfile fires <competenza>
skillfile replay <trace_id>
skillfile health

Esegui skillfile <comando> --help per le opzioni.

Documentazione

• Riferimento del linguaggio
• Configurazione
• Manuale per l'adozione
• Guida per l'agente adottante
• Contratti dei connettori
• Aggiornamento
• Esempi
• Esempi aggiuntivi sul sito web

Stato

Skillscript è pre-1.0. Il linguaggio core e i contratti dei connettori si stanno stabilizzando; l'adozione esterna e il lavoro di distribuzione sono in corso.

Contributi

Segnalazioni di bug e richieste di funzionalità sono benvenute tramite Issues. Apri una Issue prima di proporre modifiche grammaticali in modo che il design possa essere discusso prima.

Licenza

MIT. Vedi LICENSE.