Skip to main content
Skills sono file di istruzioni in Markdown che insegnano all’agente come e quando usare gli strumenti. Ogni skill risiede in una directory contenente un file SKILL.md con frontmatter YAML e un corpo in Markdown. OpenClaw carica le skill incluse insieme alle eventuali sostituzioni locali e le filtra al momento del caricamento in base all’ambiente, alla configurazione e alla presenza dei binari.

Creazione di skill

Crea e testa una skill personalizzata da zero.

Laboratorio delle skill

Esamina e approva le proposte di skill redatte dall’agente.

Configurazione delle skill

Schema completo della configurazione skills.* ed elenchi di autorizzazione degli agenti.

ClawHub

Esplora e installa le skill della comunità.

Ordine di caricamento

OpenClaw esegue il caricamento dalle seguenti fonti, iniziando da quella con la precedenza più alta. Quando lo stesso nome di skill compare in più posizioni, prevale la fonte con la precedenza più alta. Le directory radice delle skill supportano strutture raggruppate. OpenClaw rileva una skill ogni volta che un file SKILL.md compare in qualsiasi punto sotto una directory radice configurata, fino a 6 livelli di profondità:
Il percorso della cartella serve solo per l’organizzazione. Il nome e il comando slash della skill derivano dal campo name del frontmatter oppure, se name è assente, dal nome della directory. Anche gli elenchi di autorizzazione degli agenti descritti di seguito eseguono la corrispondenza su questo name.
La directory nativa $CODEX_HOME/skills di Codex CLI non è una directory radice delle skill di OpenClaw. Usa openclaw migrate plan codex per inventariare tali skill, quindi openclaw migrate codex per copiarle nell’area di lavoro di OpenClaw.

Skill ospitate su Node

Un Node headless connesso può pubblicare le skill installate nella propria directory attiva delle skill di OpenClaw (~/.openclaw/skills per impostazione predefinita; si applicano le sostituzioni dell’ambiente del profilo). Compaiono nel normale elenco delle skill dell’agente mentre il Node è connesso e scompaiono quando si disconnette. In caso di collisione, una skill locale o del Gateway mantiene il proprio nome; la skill del Node riceve un nome deterministico con prefisso relativo al Node. La versione 1 delle skill ospitate su Node richiede che il nome della directory corrisponda al campo name del frontmatter della skill. La voce della skill include il localizzatore del Node. I relativi file, riferimenti relativi e binari risiedono sul Node, quindi caricala ed eseguila con exec host=node node=<node-id>. Riavvia l’host del Node dopo aver modificato i file della skill. Consulta Node per l’associazione e le opzioni di disattivazione.

Skill per agente e condivise

Nelle configurazioni multi-agente, ogni agente dispone della propria area di lavoro. Usa il percorso che corrisponde alla visibilità desiderata:

Elenchi di autorizzazione degli agenti

La posizione della skill, che ne determina la precedenza, e la sua visibilità, che determina quale agente può usarla, sono controlli distinti. Usa gli elenchi di autorizzazione per limitare le skill visibili a un agente, indipendentemente dalla fonte da cui vengono caricate.
  • Ometti agents.defaults.skills per lasciare tutte le skill senza limitazioni per impostazione predefinita.
  • Ometti agents.list[].skills per ereditare agents.defaults.skills.
  • Imposta agents.list[].skills: [] per non esporre alcuna skill a tale agente.
  • Un elenco agents.list[].skills non vuoto costituisce l’insieme finale e non viene unito ai valori predefiniti.
  • L’elenco di autorizzazione effettivo si applica alla creazione dei prompt, al rilevamento dei comandi slash, alla sincronizzazione della sandbox e alle istantanee delle skill.
  • Questo non costituisce un confine di autorizzazione della shell host. Se lo stesso agente può usare exec, limita separatamente tale shell mediante sandboxing, isolamento dell’utente del sistema operativo, elenchi di autorizzazione/blocco per l’esecuzione e credenziali specifiche per risorsa.

Plugin e skill

I plugin possono includere le proprie skill elencando le directory skills in openclaw.plugin.json, con percorsi relativi alla directory radice del plugin. Le skill dei plugin vengono caricate quando il plugin è abilitato; ad esempio, il plugin del browser include una skill browser-automation per il controllo del browser in più passaggi. Le directory delle skill dei plugin vengono unite allo stesso livello di precedenza bassa di skills.load.extraDirs; pertanto, una skill omonima inclusa, gestita, dell’agente o dell’area di lavoro ha la precedenza. Regola l’idoneità specifica di una skill del plugin tramite metadata.openclaw.requires nel relativo frontmatter, come per qualsiasi altra skill. Consulta Plugin e Strumenti per il sistema completo dei plugin.

Laboratorio delle skill

Il Laboratorio delle skill è una coda di proposte tra l’agente e i file delle skill attive. Quando l’agente individua del lavoro riutilizzabile, prepara una proposta anziché scrivere direttamente in SKILL.md. Esamini e approvi la proposta prima che venga apportata qualsiasi modifica.
Consulta Laboratorio delle skill per il ciclo di vita completo, il riferimento della CLI e la configurazione.

Installazione da ClawHub

ClawHub è il registro pubblico delle skill. Usa i comandi openclaw skills per l’installazione e l’aggiornamento oppure la CLI clawhub per la pubblicazione e la sincronizzazione.
Per impostazione predefinita, openclaw skills install installa nella directory skills/ dell’area di lavoro attiva. Aggiungi --global per installare nella directory condivisa ~/.openclaw/skills, visibile a tutti gli agenti locali salvo restrizioni imposte dagli elenchi di autorizzazione degli agenti.Le installazioni da Git e da fonti locali richiedono SKILL.md nella directory radice della fonte. Lo slug deriva dal campo name del frontmatter di SKILL.md, se valido, e in caso contrario dal nome della directory o del repository. Usa --as <slug> per sostituirlo. openclaw skills update tiene traccia solo delle installazioni da ClawHub: reinstalla le fonti Git o locali per aggiornarle.
openclaw skills verify @owner/<slug> richiede a ClawHub il perimetro di attendibilità clawhub.skill.verify.v1 della skill. Le skill ClawHub installate vengono verificate rispetto alla versione e al registro riportati in .clawhub/origin.json. Gli slug senza proprietario restano accettati per le skill esistenti installate o non ambigue, ma i riferimenti qualificati con il proprietario evitano ambiguità sull’editore.Le pagine delle skill di ClawHub mostrano lo stato dell’ultima scansione di sicurezza prima dell’installazione, con pagine dettagliate per VirusTotal, ClawScan e l’analisi statica. Il comando termina con un codice diverso da zero quando ClawHub contrassegna la verifica come non riuscita. Gli editori possono risolvere i falsi positivi tramite la dashboard di ClawHub o clawhub skill rescan @owner/<slug>.
I client Gateway che richiedono una distribuzione esterna a ClawHub possono preparare un archivio ZIP della skill con skills.upload.begin, skills.upload.chunk e skills.upload.commit, quindi installarlo con skills.install({ source: "upload", ... }). Questo percorso è disattivato per impostazione predefinita e richiede skills.install.allowUploadedArchives: true in openclaw.json. Le normali installazioni da ClawHub non richiedono mai tale impostazione.

Sicurezza

Considera le skill di terze parti come codice non attendibile. Esaminale prima di abilitarle. Preferisci esecuzioni in sandbox per input non attendibili e strumenti rischiosi. Consulta Sandboxing per i controlli lato agente.
Il rilevamento delle skill dell’area di lavoro, dell’agente del progetto e delle directory aggiuntive accetta solo directory radice delle skill il cui percorso reale risolto rimane all’interno della directory radice configurata, a meno che skills.load.allowSymlinkTargets non consideri esplicitamente attendibile una directory radice di destinazione. Il Laboratorio delle skill scrive attraverso tali destinazioni attendibili solo quando skills.workshop.allowSymlinkTargetWrites è abilitato. Le directory gestite ~/.openclaw/skills e personali ~/.agents/skills possono contenere cartelle di skill collegate simbolicamente, ma il percorso reale di ogni SKILL.md deve comunque rimanere all’interno della relativa directory della skill risolta.
Configura security.installPolicy per eseguire un comando locale attendibile relativo ai criteri prima di proseguire con l’installazione delle skill. Il criterio riceve i metadati e il percorso della fonte preparata, si applica ai percorsi ClawHub, caricamento, Git, locale, aggiornamento e installazione delle dipendenze e blocca l’operazione quando il comando non può restituire una decisione valida.
skills.entries.*.env e skills.entries.*.apiKey inseriscono i segreti nel processo host solo per quel turno dell’agente, non nella sandbox. Non includere i segreti nei prompt e nei registri.
Per il modello di minaccia più ampio e gli elenchi di controllo della sicurezza, consulta Sicurezza.

Formato di SKILL.md

Ogni skill richiede almeno name e description nel frontmatter:
OpenClaw segue la specifica AgentSkills. Il frontmatter viene prima analizzato come YAML; se l’operazione non riesce, viene usato come ripiego un parser che supporta solo una singola riga. I blocchi metadata annidati (incluse le mappature YAML su più righe) vengono convertiti in una stringa JSON e rianalizzati come JSON5, quindi il formato a blocchi mostrato in Controllo dei requisiti funziona. Usa {baseDir} nel corpo per fare riferimento al percorso della cartella della skill.

Chiavi facoltative del frontmatter

string
URL mostrato come “Website” nell’interfaccia Skills di macOS. È supportato anche tramite metadata.openclaw.homepage.
boolean
predefinito:"true"
Quando è true, la skill è esposta come comando slash invocabile dall’utente.
boolean
predefinito:"false"
Quando è true, OpenClaw esclude le istruzioni della skill dal prompt normale dell’agente. La skill rimane disponibile come comando slash quando anche user-invocable è true.
"tool"
Quando è impostato su tool, il comando slash ignora il modello e viene inoltrato direttamente a uno strumento registrato.
string
Nome dello strumento da invocare quando è impostato command-dispatch: tool.
"raw"
predefinito:"raw"
Per l’inoltro allo strumento, passa allo strumento la stringa grezza degli argomenti senza analisi da parte del core. Lo strumento riceve { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Controllo dei requisiti

OpenClaw filtra le skill al momento del caricamento usando metadata.openclaw (oggetto JSON5 incorporato nel frontmatter; consulta la nota sull’analisi riportata sopra). Una skill senza un blocco metadata.openclaw è sempre idonea, a meno che non sia esplicitamente disabilitata.
boolean
Quando è true, include sempre la skill e ignora tutti gli altri controlli.
string
Emoji facoltativa mostrata nell’interfaccia Skills di macOS.
string
URL facoltativo mostrato come “Website” nell’interfaccia Skills di macOS.
("darwin" | "linux" | "win32")[]
Filtro per piattaforma. Quando è impostato, la skill è idonea solo su uno dei sistemi operativi elencati.
string[]
Ogni binario deve esistere in PATH.
string[]
Almeno un binario deve esistere in PATH.
string[]
Ogni variabile d’ambiente deve esistere nel processo o essere fornita tramite la configurazione.
string[]
Ogni percorso di openclaw.json deve avere un valore valutato come vero.
string
Nome della variabile d’ambiente associata a skills.entries.<name>.apiKey.
object[]
Specifiche facoltative degli strumenti di installazione usate dall’interfaccia Skills di macOS (brew / node / go / uv / download).
I blocchi legacy metadata.clawdbot sono ancora accettati quando metadata.openclaw è assente, così le skill meno recenti già installate mantengono i controlli delle dipendenze e i suggerimenti per l’installazione. Le nuove skill devono usare metadata.openclaw.

Specifiche degli strumenti di installazione

Le specifiche degli strumenti di installazione indicano all’interfaccia Skills di macOS come installare una dipendenza:
  • Quando sono elencati più strumenti di installazione, il Gateway sceglie un’opzione preferita (brew, se disponibile; altrimenti node).
  • Se tutti gli strumenti di installazione sono download, OpenClaw elenca ogni voce in modo che sia possibile vedere tutti gli artefatti disponibili.
  • Le specifiche possono includere os: ["darwin"|"linux"|"win32"] per applicare un filtro in base alla piattaforma.
  • Le installazioni Node rispettano skills.install.nodeManager in openclaw.json (predefinito: npm; opzioni: npm / pnpm / yarn / bun). Ciò influisce solo sulle installazioni delle skill; il runtime del Gateway deve continuare a essere Node.
  • Ordine di preferenza degli strumenti di installazione del Gateway: Homebrew → uv → gestore Node configurato → go → download.
  • Homebrew: OpenClaw non installa automaticamente Homebrew né converte le formule brew in comandi del gestore di pacchetti di sistema. Nei container Linux senza brew, gli strumenti di installazione basati solo su brew sono nascosti; usa un’immagine personalizzata o installa manualmente la dipendenza.
  • Go: OpenClaw richiede Go 1.21 o versioni successive per le installazioni automatiche delle skill. Se go non è presente e Homebrew è disponibile, OpenClaw installa prima Go tramite Homebrew; su Linux senza Homebrew può invece usare apt-get come root o tramite sudo senza password, quando il candidato golang-go aggiornato soddisfa la versione minima. Il comando go install effettivo per la dipendenza usa sempre una directory dedicata per i binari gestita da OpenClaw (bin di Homebrew per una nuova installazione, altrimenti ~/.local/bin), anziché il valore GOBIN configurato: le tue variabili d’ambiente GOBIN, GOPATH e GOTOOLCHAIN vengono lette ma mai sovrascritte.
  • Download: url (obbligatorio), archive (tar.gz | tar.bz2 | zip), extract (predefinito: automatico quando viene rilevato un archivio), stripComponents, targetDir (predefinito: ~/.openclaw/tools/<skillKey>).
requires.bins viene verificato sull’host al momento del caricamento della skill. Se un agente viene eseguito in un ambiente isolato, il binario deve esistere anche all’interno del container. Installalo tramite agents.defaults.sandbox.docker.setupCommand o un’immagine personalizzata. setupCommand viene eseguito una volta dopo la creazione del container e richiede accesso in uscita alla rete, un file system radice scrivibile e un utente root nell’ambiente isolato.

Sostituzioni della configurazione

Abilita e configura le skill incluse o gestite in skills.entries all’interno di ~/.openclaw/openclaw.json:
boolean
false disabilita la skill anche quando è inclusa o installata. La skill inclusa coding-agent è facoltativa: imposta skills.entries.coding-agent.enabled: true e assicurati che claude, codex, opencode o un’altra CLI supportata sia installata e autenticata.
string | { source, provider, id }
Campo di utilità per le skill che dichiarano metadata.openclaw.primaryEnv. Supporta una stringa di testo non cifrato o un oggetto SecretRef.
Record<string, string>
Variabili d’ambiente inserite per l’esecuzione dell’agente. Vengono inserite solo quando la variabile non è già impostata nel processo.
object
Raccolta facoltativa di campi di configurazione personalizzati per la singola skill.
string[]
Elenco facoltativo di elementi consentiti solo per le skill incluse. Quando è impostato, sono idonee solo le skill incluse presenti nell’elenco. Le skill gestite e quelle dell’area di lavoro non sono interessate.
Per impostazione predefinita, le chiavi di configurazione corrispondono al nome della skill. Se una skill definisce metadata.openclaw.skillKey, usa invece tale chiave in skills.entries. Racchiudi tra virgolette i nomi con trattini: JSON5 consente chiavi racchiuse tra virgolette.

Inserimento delle variabili d’ambiente

Quando inizia l’esecuzione di un agente, OpenClaw:
1

Legge i metadati delle skill

OpenClaw determina l’elenco effettivo delle skill per l’agente, applicando le regole di controllo dei requisiti, gli elenchi di elementi consentiti e le sostituzioni della configurazione.
2

Inserisce le variabili d'ambiente e le chiavi API

skills.entries.<key>.env e skills.entries.<key>.apiKey vengono applicati a process.env per la durata dell’esecuzione.
3

Crea il prompt di sistema

Le skill idonee vengono compilate in un blocco XML compatto e inserite nel prompt di sistema.
4

Ripristina l'ambiente

Al termine dell’esecuzione, viene ripristinato l’ambiente originale.
L’inserimento delle variabili d’ambiente è limitato all’esecuzione dell’agente sull’host, non all’ambiente isolato. All’interno di un ambiente isolato, env e apiKey non hanno effetto. Consulta Configurazione delle Skills per informazioni su come passare dati segreti alle esecuzioni isolate.
Per il backend incluso claude-cli, OpenClaw materializza anche la stessa istantanea delle skill idonee come Plugin temporaneo di Claude Code e la passa tramite --plugin-dir. Gli altri backend CLI usano solo il catalogo del prompt.

Istantanee e aggiornamento

OpenClaw crea un’istantanea delle skill idonee all’avvio di una sessione e riutilizza tale elenco per tutti i turni successivi della sessione. Le modifiche alle skill o alla configurazione hanno effetto nella nuova sessione successiva. Le Skills vengono aggiornate durante una sessione in due casi:
  • Il monitoraggio delle skill rileva una modifica a SKILL.md.
  • Si connette un nuovo Node remoto idoneo.
L’elenco aggiornato viene acquisito al turno successivo dell’agente. Se l’elenco effettivo degli elementi consentiti per l’agente cambia, OpenClaw aggiorna l’istantanea per mantenere allineate le skill visibili.
Per impostazione predefinita, OpenClaw monitora le cartelle delle skill e aggiorna l’istantanea quando cambiano i file SKILL.md. Configura il comportamento in skills.load:
Usa allowSymlinkTargets per strutture intenzionali con collegamenti simbolici, nelle quali un collegamento simbolico alla radice di una skill punta all’esterno della radice configurata, ad esempio <workspace>/skills/manager -> ~/Projects/manager/skills. Abilita skills.workshop.allowSymlinkTargetWrites solo quando Skill Workshop deve anche applicare le proposte tramite tali percorsi con collegamenti simbolici considerati attendibili.
Se il Gateway viene eseguito su Linux, ma è connesso un Node macOS con system.run consentito, OpenClaw può considerare idonee le skill disponibili solo su macOS quando i binari richiesti sono presenti su tale Node. L’agente deve eseguire tali skill tramite lo strumento exec con host=node.I Node non in linea non rendono visibili le skill disponibili solo in remoto. Se un Node smette di rispondere ai controlli dei binari, OpenClaw cancella dalla cache le corrispondenze dei binari per tale Node.

Impatto sui token

Quando le skill sono idonee, OpenClaw inserisce un blocco XML compatto nel prompt di sistema. Il costo è deterministico e cresce linearmente per ogni skill:
  • Costo di base (solo quando è idonea almeno una skill): un blocco fisso di testo introduttivo più l’elemento contenitore <available_skills>.
  • Per skill: circa 97 caratteri più la lunghezza dei campi name, description e location.
  • L’escape XML converte & < > " ' in entità, aggiungendo alcuni caratteri per ogni occorrenza.
  • Con circa 4 caratteri per token, 97 caratteri ≈ 24 token per skill, prima delle lunghezze dei campi.
Se il blocco sottoposto a rendering supera il budget configurato per il prompt (skills.limits.maxSkillsPromptChars), OpenClaw conserva innanzitutto il maggior numero possibile di identità delle Skills (nome, posizione e versione) consentito dal formato compatto senza descrizioni. Quindi utilizza il budget rimanente per descrizioni abbreviate. Se non rimane alcun budget per le descrizioni, queste vengono omesse. Il prompt include una nota che rimanda a openclaw skills check ogni volta che è necessario usare la formattazione compatta o troncare l’elenco. Mantieni le descrizioni brevi ed esplicative per ridurre al minimo il sovraccarico del prompt.

Correlati

Creazione di Skills

Guida dettagliata alla creazione di una skill personalizzata.

Laboratorio delle Skills

Coda delle proposte per le Skills redatte dagli agenti.

Configurazione delle Skills

Schema di configurazione completo di skills.* ed elenchi di autorizzazione degli agenti.

Comandi slash

Come vengono registrati e instradati i comandi slash delle Skills.

ClawHub

Esplora e pubblica Skills nel registro pubblico.

Plugin

I Plugin possono includere Skills insieme agli strumenti che documentano.