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à:
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.Regole degli elenchi di autorizzazione
Regole degli elenchi di autorizzazione
- Ometti
agents.defaults.skillsper lasciare tutte le skill senza limitazioni per impostazione predefinita. - Ometti
agents.list[].skillsper ereditareagents.defaults.skills. - Imposta
agents.list[].skills: []per non esporre alcuna skill a tale agente. - Un elenco
agents.list[].skillsnon 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 directoryskills 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 inSKILL.md. Esamini e approvi la proposta
prima che venga apportata qualsiasi modifica.
Installazione da ClawHub
ClawHub è il registro pubblico delle skill. Usa i comandiopenclaw skills per l’installazione e l’aggiornamento oppure la CLI clawhub per
la pubblicazione e la sincronizzazione.
Dettagli dell'installazione
Dettagli dell'installazione
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.Verifica e scansione di sicurezza
Verifica e scansione di sicurezza
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>.Installazioni da archivi privati
Installazioni da archivi privati
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
Contenimento dei percorsi
Contenimento dei percorsi
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.Criteri di installazione dell'operatore
Criteri di installazione dell'operatore
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.Ambito di inserimento dei segreti
Ambito di inserimento dei segreti
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.Formato di SKILL.md
Ogni skill richiede almenoname 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 usandometadata.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:Regole di selezione dello strumento di installazione
Regole di selezione dello strumento di installazione
- 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.nodeManagerinopenclaw.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.
Dettagli per ciascuno strumento di installazione
Dettagli per ciascuno strumento di installazione
- 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
gonon è presente e Homebrew è disponibile, OpenClaw installa prima Go tramite Homebrew; su Linux senza Homebrew può invece usareapt-getcome root o tramitesudosenza password, quando il candidatogolang-goaggiornato soddisfa la versione minima. Il comandogo installeffettivo per la dipendenza usa sempre una directory dedicata per i binari gestita da OpenClaw (bindi Homebrew per una nuova installazione, altrimenti~/.local/bin), anziché il valoreGOBINconfigurato: le tue variabili d’ambienteGOBIN,GOPATHeGOTOOLCHAINvengono 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>).
Note sull'isolamento
Note sull'isolamento
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 inskills.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.
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.
Monitoraggio delle skill
Monitoraggio delle skill
Per impostazione predefinita, OpenClaw monitora le cartelle delle skill e
aggiorna l’istantanea quando cambiano i file Usa
SKILL.md. Configura il
comportamento in skills.load: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.Node macOS remoti (Gateway Linux)
Node macOS remoti (Gateway Linux)
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,descriptionelocation. - 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.
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.