Creare skill personalizzate per OpenClaw: un tutorial pratico

Le skill integrate di OpenClaw coprono i flussi di lavoro più comuni, e su ClawHub ne trovi molte altre. Ma spesso quelle che contano di più sono proprio quelle che ancora non esistono: automazioni modellate sui tuoi progetti e strumenti.

Questo tutorial mostra come creare due skill personalizzate. La prima incapsula uno script Python che converte i notebook Jupyter in documenti Word. Se scrivi nei notebook ma consegni file .docx a editor o stakeholder, trasforma un'esportazione manuale in un comando slash. La seconda genera immagini con Nano Banana Pro tramite l'API di Replicate, aggiungendo gestione delle credenziali e scoping dell'ambiente oltre alle basi.

Il tutorial copre anche il sandboxing con Docker, il gating via metadati e la pubblicazione delle skill su ClawHub. Per una panoramica più ampia della piattaforma OpenClaw, vedi OpenClaw Projects: cosa puoi costruire e la nostra guida alle migliori skill per agent. 

Cosa sono le skill di OpenClaw?

Le skill sono il modo in cui aggiungi nuovi comportamenti all'agente OpenClaw. Una skill può essere semplice come un comando slash che riformatta il codice, o complessa come un flusso di lavoro multi-step che rivede le PR e pubblica commenti su Jira o Slack.

Se hai usato server MCP (Model Context Protocol) in Claude Code o strumenti simili, le skill coprono un ruolo diverso. I server MCP sono processi separati che espongono tool tramite un protocollo standard, ideale per integrazioni che richiedono stato persistente o più endpoint di tool. 

Le skill saltano tutto questo: scrivi istruzioni in linguaggio naturale che l'agente legge e segue a runtime, risultando più rapide da creare quando ti serve automatizzare una singola cosa. Il confronto OpenClaw vs Claude Code approfondisce i compromessi.

Gli hook, l'altro punto di estensione, si attivano automaticamente quando accade qualcosa, ad esempio quando una chiamata a un tool si completa o il modello genera una risposta. Le skill restano inattive finché l'utente non digita un comando slash o l'agente non decide che una skill è rilevante per l'attività corrente.

OpenClaw include 49 skill che coprono email, calendari, GitHub, automazione del browser e altro. La community ne ha pubblicate migliaia su ClawHub. Per capire come la piattaforma si è evoluta, vedi la storia da MoltBot a ClawdBot.

Prerequisiti

Ti serviranno:

• OpenClaw installato e in esecuzione via Telegram (guida all'installazione). L'integrazione con BotFather di Telegram offre il miglior supporto ai comandi slash, che userai per attivare le skill in tutto il tutorial.
• uv installato (entrambe le skill in questo tutorial lo usano per le dipendenze Python)
• Familiarità con terminale, YAML e Markdown
• Un token API di Replicate per la skill di generazione immagini (registrazione gratuita, pagamento a consumo)
• Un account GitHub con almeno una settimana di anzianità, se vuoi pubblicare su ClawHub

Se preferisci eseguire OpenClaw con modelli locali, il tutorial OpenClaw con Ollama copre quella configurazione.

Creare la tua prima skill OpenClaw

Questa prima skill incapsula uno script Python che converte i notebook Jupyter in documenti Word, gestendo formattazione markdown, blocchi di codice, immagini, tabelle e hyperlink così che l'output .docx preservi la struttura del notebook originale. Se passi regolarmente contenuti dei notebook a persone che lavorano in Word, trasformi quell'esportazione manuale in un singolo comando slash.

Crea la cartella della skill nella directory delle skill gestite di OpenClaw:

mkdir -p ~/.openclaw/skills/notebook-to-docx

Le skill in ~/.openclaw/skills sono disponibili in tutte le sessioni. Puoi anche metterle dentro un progetto in <project>/skills per limitarle a quel workspace; quando un nome compare in entrambe le posizioni, la copia nel workspace ha la precedenza su quella gestita, che a sua volta sovrascrive qualsiasi skill inclusa con lo stesso nome.

Scrivere lo SKILL.md

Ogni skill richiede un file: SKILL.md. Lo YAML frontmatter in cima definisce come OpenClaw carica la skill, e il corpo markdown sotto contiene le istruzioni che l'agente segue a runtime.

Crea ~/.openclaw/skills/notebook-to-docx/SKILL.md, iniziando dal frontmatter:

---
name: notebook-to-docx
description: Convert Jupyter notebooks to Word documents with proper formatting
user-invocable: true
metadata: {"openclaw": {"requires": {"bins": ["uv"]}}}
---

name funge anche da comando slash (/notebook-to-docx). description dà all'agente una riga che usa per valutarne la pertinenza rispetto al compito corrente. Impostare user-invocable: true registra il comando slash nella tua chat Telegram. Il JSON metadata gestisce il gating al caricamento: requires.bins indica a OpenClaw di ignorare questa skill se uv non è nel PATH di sistema, invece di fallire a runtime. 

Se vuoi il comportamento opposto, in cui la skill non si attiva mai a meno che tu non digiti esplicitamente il comando slash, imposta disable-model-invocation: true.

Suggerimento: lo YAML frontmatter supporta solo valori su singola riga. Stringhe multi-riga o block scalar causeranno errori di parsing, motivo per cui metadata è un oggetto JSON su una riga invece di YAML annidato.

Sotto il frontmatter, aggiungi il corpo con le istruzioni:

# Notebook to DOCX Converter
 
Converts Jupyter notebooks (.ipynb) to Word documents (.docx) with proper formatting.
 
## Usage
 
Run the conversion script:
 
	uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py <notebook_path> [output_path]
 
If output_path is not specified, creates a .docx file with the same name as the notebook.
 
## Features
 
- Markdown formatting preserved as Word styles (bold, italics, headings)
- Backticks preserved around inline code with monospace font
- Code blocks show triple backticks and language name, use Courier New font
- Non-code text uses Poppins font
- Images embedded with alt text
- Hyperlinks preserved and clickable
- Markdown tables converted to Word tables
 
## Requirements
 
- nbformat
- python-docx
- Pillow

{baseDir} è una variabile template che a runtime si risolve nel percorso della cartella della skill, così non devi inserire il percorso hardcoded. Questo è importante quando qualcun altro installa la tua skill in una directory diversa. 

I flag uv run --with scaricano le tre librerie necessarie allo script, mantenendo la skill auto-contenuta invece di presumere che quei pacchetti esistano già nell'ambiente dell'utente.

Lo script di supporto

Lo script Python va nella stessa cartella di SKILL.md. Con circa 490 righe, è troppo lungo per essere incluso qui, quindi scarica lo script completo da questo gist e salvalo come notebook_to_docx.py in ~/.openclaw/skills/notebook-to-docx/. Copre tutto ciò elencato nella sezione Features dello SKILL.md sopra.

Ecco l'entry point per capire a grandi linee cosa fa:

def convert_notebook_to_docx(notebook_path, output_path=None):
	notebook_path = Path(notebook_path)
	if output_path is None:
    	output_path = notebook_path.with_suffix('.docx')
	else:
    	output_path = Path(output_path)
 
	with open(notebook_path, 'r', encoding='utf-8') as f:
    	nb = nbformat.read(f, as_version=4)
 
	doc = Document()
	create_styles(doc)
 
	style = doc.styles['Normal']
	style.font.name = 'Poppins'
	style.font.size = Pt(11)
 
	base_path = notebook_path.parent
 
	for cell in nb.cells:
    	if cell.cell_type == 'markdown':
        	process_markdown_cell(doc, cell.source, base_path)
    	elif cell.cell_type == 'code':
        	process_code_cell(doc, cell.source, cell.get('outputs', []))
 
	doc.save(output_path)
	print(f'Converted: {notebook_path} -> {output_path}')
	return output_path

Testare la skill

OpenClaw crea uno snapshot della lista delle skill all'avvio della sessione, ma un file watcher integrato rileva i nuovi file SKILL.md in circa 250 ms. Se la skill non compare, riavvia la sessione.

Ecco il notebook che useremo come test:

Apri la chat Telegram con OpenClaw e digita /notebook-to-docx, poi indica quale notebook convertire:

Il documento Word risultante:

Titoli, blocchi di codice, formattazione inline e hyperlink finiscono tutti negli stili Word corretti. Se qualcosa non torna nell'output, verifica che la lista delle funzionalità nel tuo SKILL.md corrisponda a ciò che lo script supporta.

Sicurezza e sandboxing in OpenClaw

OpenClaw può eseguire i tool all'interno di container Docker, limitando ciò che una skill malfunzionante o compromessa può toccare sulla tua macchina. L'impostazione si trova in agents.defaults.sandbox dentro ~/.openclaw/openclaw.json, e ci sono tre modalità tra cui scegliere:

• "off" è il default, con i tool che girano direttamente sull'host e senza livello di isolamento.
• "non-main" mantiene la tua sessione chat principale sull'host ma sposta le sessioni in background e automatizzate nei container.
• Con "all", ogni sessione gira dentro un container a prescindere dal contesto.

Oltre alla modalità, scegli un livello di accesso al workspace che decide quanto del tuo filesystem vede il container. Il default, "none", dà al sandbox una propria directory isolata sotto ~/.openclaw/sandboxes senza accesso ai file del tuo progetto. 

Con "ro", il tuo workspace è montato in sola lettura su /agent, così l'agente può leggere il tuo codice ma non modificarlo. "rw" va oltre e garantisce pieno accesso in lettura-scrittura su /workspace.

Una configurazione funzionante che isola le sessioni in background dando loro accesso in scrittura è questa:

{
  "agents": {
	"defaults": {
  	"sandbox": {
    	"mode": "non-main",
    	"scope": "session",
    	"workspaceAccess": "rw"
  	}
	}
  }
}

Questo diventa rilevante non appena le tue skill iniziano a chiamare API o gestire credenziali. 

Quando una skill gira dentro un container, le variabili d'ambiente dell'host non sono presenti automaticamente. Un REPLICATE_API_TOKEN che hai esportato in .bashrc non esisterà dentro il sandbox, quindi i segreti devono passare attraverso il sistema di configurazione di OpenClaw, che imposteremo nella prossima sezione.

Suggerimento: se la tua skill usa requires.bins nei metadata per vincolarsi a un tool CLI, quel controllo gira sull'host al caricamento. Ma quando l'agente è sandboxato, il binario deve esistere anche nel container. Installalo tramite sandbox.docker.setupCommand o includilo in un'immagine Docker personalizzata.

Il sandboxing limita anche il raggio d'azione quando operazioni sui file o comandi shell vanno storti. Una skill che esegue per errore rm -rf / colpisce il filesystem del container e non la tua macchina reale, che è già un buon motivo per attivarlo anche se ti fidi del tuo codice. 

Per approfondire come i flussi di lavoro degli agent AI gestiscono i confini di sicurezza, vedi AI Agent Workflows with Claude CoWork.

Creare una skill connessa a un'API

La seconda skill genera immagini usando il modello Nano Banana Pro (Gemini 3 Pro Image) di Google tramite l'API di Replicate, il che significa configurare gestione delle credenziali e gating dell'ambiente oltre alle basi dello SKILL.md.

Crea la cartella della skill:

mkdir -p ~/.openclaw/skills/nano-banana-pro

Crea ~/.openclaw/skills/nano-banana-pro/SKILL.md, iniziando dal frontmatter:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image on Replicate
user-invocable: true
metadata: {"openclaw": {"emoji": "🎨", "requires": {"env": ["REPLICATE_API_TOKEN"], "bins": ["uv"]}, "primaryEnv": "REPLICATE_API_TOKEN"}}
---

La struttura è simile alla prima skill, ma il campo metadata fa di più. Ora include due vincoli: requires.env verifica che REPLICATE_API_TOKEN esista prima di caricare la skill, e requires.bins controlla la presenza di uv. Se manca uno dei due, la skill viene ignorata in silenzio. 

Il campo emoji imposta un'icona nella lista dei comandi slash di Telegram. E primaryEnv associa REPLICATE_API_TOKEN alla scorciatoia apiKey nella config (maggiori dettagli nella sezione sulle credenziali qui sotto).

Se vuoi che la UI delle Skill su macOS offra l'installazione in un clic per i binari richiesti, aggiungi un array install ai metadata:

metadata: {"openclaw": {"requires": {"bins": ["uv"]}, "install": [{"id": "brew", "kind": "brew", "formula": "uv", "bins": ["uv"], "label": "Install uv (brew)"}]}}

Su Linux, gestisci l'installazione manualmente o tramite sandbox.docker.setupCommand.

Sotto il frontmatter, aggiungi il corpo con le istruzioni:

# Nano Banana Pro Image Generator
 
Generate and edit images using Google's Nano Banana Pro model via the Replicate API.
 
## Usage
 
Run the generation script:
 
	uv run --with replicate python {baseDir}/generate.py --prompt "<user prompt>" [--aspect-ratio 1:1] [--output image.png]
 
## Options
 
- --prompt: The image description (required)
- --aspect-ratio: Ratio like 1:1, 4:3, 16:9 (default: 1:1)
- --output: Output file path (default: generated_image.png)
 
## Tips
 
- For text in images, be specific about fonts, size, and placement
- The model supports resolutions up to 2K
- Safety filtering is on by default

Il corpo è più breve rispetto alla prima skill perché lo script di generazione gestisce gran parte della complessità. La variabile template {baseDir} funziona allo stesso modo, risolvendo nel percorso della cartella della skill a runtime.

Lo script di generazione

Aggiungi ~/.openclaw/skills/nano-banana-pro/generate.py:

import replicate
import urllib.request
import argparse
 
def main():
	parser = argparse.ArgumentParser()
	parser.add_argument("--prompt", required=True)
    parser.add_argument("--aspect-ratio", default="1:1")
	parser.add_argument("--output", default="generated_image.png")
	args = parser.parse_args()
 
	output = replicate.run(
    	"google/nano-banana-pro",
    	input={
        	"prompt": args.prompt,
        	"aspect_ratio": args.aspect_ratio,
        	"output_format": "png",
        	"safety_filter_level": "block_only_high",
    	},
	)
 
	# Replicate returns a FileOutput; download the image
	url = str(output[0]) if isinstance(output, list) else str(output)
	urllib.request.urlretrieve(url, args.output)
	print(f"Image saved to {args.output}")
 
if __name__ == "__main__":
	main()

Analizza gli argomenti, chiama replicate.run() con il nome del modello e i parametri di input, e scarica l'immagine risultante. La libreria replicate legge REPLICATE_API_TOKEN dall'ambiente automaticamente.

Configurare la credenziale API

Aggiungi una voce a ~/.openclaw/openclaw.json:

{
  "skills": {
	"entries": {
  	"nano-banana-pro": {
    	"enabled": true,
    	"apiKey": "r8_your_replicate_token_here",
    	"env": {
      	"REPLICATE_API_TOKEN": "r8_your_replicate_token_here"
    	}
  	}
	}
  }
}

Qui ci sono due modi per fornire la credenziale. Il campo apiKey è una scorciatoia che mappa a quanto dichiarato in primaryEnv nei metadata della skill. Il blocco env ti dà un controllo più fine, permettendoti di iniettare più variabili d'ambiente se la skill ne ha bisogno. 

Entrambi gli approcci limitano i valori alla singola esecuzione dell'agente. Sono impostati quando l'esecuzione inizia e azzerati quando termina, quindi non finiscono nel tuo ambiente shell globale.

Test

Avvia una nuova sessione di OpenClaw e invoca la skill:

/nano_banana_pro generate a beautiful and accurate diagram of how backpropagation works

Ecco il diagramma prodotto dalla skill tramite Nano Banana Pro su Replicate:

L'immagine è arrivata, ma per arrivarci abbiamo dovuto fare una deviazione. La prima versione di questo SKILL.md non aveva una sezione ## Rules, lasciando margine all'agente per improvvisare. Quando Nano Banana Pro ha restituito un errore "service unavailable" per alta domanda, l'agente ha deciso autonomamente di provare google/nano-banana (la variante non-Pro) come fallback e ha generato l'immagine con quel modello.

Dal punto di vista dell'agente, la scelta aveva senso: completare il compito con qualsiasi mezzo disponibile. Dal tuo, non era ciò che avevi chiesto. La soluzione è stata aggiungere vincoli comportamentali al corpo delle istruzioni:

## Rules
 
- Only use the google/nano-banana-pro model. Never fall back to other models like google/nano-banana or any alternative. If the model is unavailable or rate-limited, report the error to the user and stop.
- After generating an image, send the image file directly in the chat. Do not just save it to the workspace silently.

L'agente tratta le istruzioni in SKILL.md come linee guida più che come limiti rigidi, e colmerà le lacune con il proprio giudizio. Qualsiasi cosa tu non vieti, potrebbe decidere di provarla. 

Se un comportamento per te è importante, che sia quale modello usare, dove inviare l'output o se ritentare in caso di errore, esplicitalo in una sezione Rules.

Pubblicare e condividere skill su ClawHub

ClawHub è il registro pubblico per le skill di OpenClaw, libero da consultare e installare. Per pubblicare serve un account GitHub con almeno una settimana di anzianità.

Configurare la CLI

Installa la CLI di ClawHub globalmente:

npm i -g clawhub

Poi autentìcati:

clawhub login

Si aprirà il browser per l'autenticazione con GitHub. Una volta autenticato, puoi cercare, installare e pubblicare skill dal terminale.

Pubblicare la tua skill

Per pubblicare la skill di generazione immagini:

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --name "Nano Banana Pro" \
  --version 1.0.0 \
  --tags latest

Lo --slug è l'identificatore univoco su ClawHub e deve essere unico in tutto il registro. Se qualcun altro ha già pubblicato una skill con quello slug, il comando fallirà con l'errore "only the owner can publish updates". In tal caso, scegli uno slug diverso, ad esempio yourname-nano-banana-pro.

L'opzione --version segue il versioning semantico. Ogni volta che pubblichi un aggiornamento, incrementa il numero di versione e, se vuoi, aggiungi un changelog:

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --version 1.1.0 \
  --changelog "Added image editing with --image-input flag"

ClawHub mantiene la cronologia delle versioni così gli utenti possono controllare le modifiche ed eventualmente effettuare il rollback.

Per operazioni in bulk, clawhub sync --all analizza la tua directory delle skill e pubblica in una volta sola tutte le skill nuove o aggiornate:

clawhub sync --all --bump patch

Installare skill della community

Per installare una skill pubblicata da qualcun altro:

clawhub search "calendar"
clawhub install caldav-calendar

Le skill installate finiscono in ./skills per impostazione predefinita, che OpenClaw rileva come skill del workspace alla successiva sessione.

Una nota sulle skill di terze parti

Nel gennaio 2026, i ricercatori di sicurezza di Koi hanno scoperto 341 skill malevole su ClawHub, in quello che è diventato noto come incidente ClawHavoc. Gli attaccanti hanno usato nomi di skill typosquattati e finti passaggi di installazione "prerequisiti" per distribuire Atomic macOS Stealer (AMOS), reverse shell e payload per l'esfiltrazione di credenziali. 

A metà febbraio 2026, il conteggio era salito a oltre 824 skill segnalate in dozzine di categorie.

Prima di installare qualsiasi skill della community, leggi il suo SKILL.md e i file di supporto. Fai attenzione a sospetti passaggi di installazione "prerequisiti", codice offuscato o comandi codificati in base64. ClawHub nasconde automaticamente le skill con tre o più segnalazioni degli utenti, ma nuove skill malevole possono comparire più velocemente della moderazione. 

Strumenti come Clawdex possono analizzare le skill installate confrontandole con un database di pacchetti malevoli noti.

Tratta le skill di terze parti con la stessa cautela che applichi a qualsiasi codice di terze parti: rivedile prima di eseguirle.

Conclusione

Tra il formato SKILL.md, il perimetro delle credenziali definito in openclaw.json e la CLI di ClawHub, hai l'intero ciclo di vita che va dall'automazione locale al pacchetto condiviso. 

La maggior parte del lavoro nel creare una nuova skill OpenClaw sta nello scrivere istruzioni chiare nel corpo markdown e nel decidere cosa vincolare nei metadata. Il codice vero e proprio, che sia uno script di conversione o una chiamata API, resta in file separati che puoi testare e iterare in modo indipendente.

Per andare oltre l'ambito trattato in questo tutorial, le skill incluse nel repo OpenClaw mostrano come il team core struttura flussi di lavoro più complessi. L' overview di Claude Opus 4.6 approfondisce come le scelte di modello influenzano il comportamento dell'agente, e il corso Introduction to Claude Models offre pratica hands-on con i modelli dietro agent come OpenClaw.