Aangepaste OpenClaw-skills bouwen: een praktische tutorial

De ingebouwde skills van OpenClaw dekken veelvoorkomende workflows, en op ClawHub vind je er nog veel meer. Maar de belangrijkste zijn vaak juist diegene die nog niemand heeft gebouwd: automatiseringen die precies passen bij jouw eigen projecten en tools.

Deze tutorial laat zien hoe je twee aangepaste skills bouwt. De eerste wikkelt een Python-script in dat Jupyter-notebooks omzet naar Word-documenten. Als je in notebooks schrijft maar .docx-bestanden overdraagt aan editors of stakeholders, verandert dit een handmatige export in een slashopdracht. De tweede genereert afbeeldingen met Nano Banana Pro via de Replicate-API, met daarbovenop beheer van inloggegevens en afbakening van de omgeving.

De tutorial behandelt ook Docker-sandboxing, metadata-gating en het publiceren van skills op ClawHub. Voor een breder beeld van het OpenClaw-platform, zie OpenClaw-projecten: wat je kunt bouwen en onze gids met de beste agent-skills. 

Wat zijn OpenClaw-skills?

Skills zijn de manier waarop je nieuw gedrag toevoegt aan de OpenClaw-agent. Een skill kan zo simpel zijn als een slashopdracht die code herformatteert, of zo uitgebreid als een meerstapsworkflow die PR’s reviewt en comments plaatst op Jira of Slack.

Als je MCP (Model Context Protocol) servers hebt gebruikt in Claude Code of vergelijkbare tools, dan vullen skills een andere rol. MCP-servers zijn aparte processen die tools via een gestandaardiseerd protocol aanbieden, wat past bij integraties die persistente status of meerdere tool-endpoints nodig hebben. 

Skills slaan dat allemaal over: je schrijft instructies in gewone taal die de agent tijdens runtime leest en volgt, waardoor ze sneller te bouwen zijn als je maar één ding wilt automatiseren. De vergelijking OpenClaw vs Claude Code gaat dieper in op de afwegingen.

Hooks, het andere extensiepunt, vuren automatisch wanneer er iets gebeurt, zoals het afronden van een tool-call of wanneer het model een response genereert. Skills blijven inactief totdat de gebruiker een slashopdracht typt of de agent beslist dat er één relevant is voor de huidige taak.

OpenClaw levert 49 skills mee voor e-mail, agenda’s, GitHub, browserautomatisering en meer. De community heeft er nog duizenden extra op ClawHub gepubliceerd. Voor achtergrond over hoe het platform is geëvolueerd, zie de geschiedenis van MoltBot naar ClawdBot.

Vereisten

Je hebt nodig:

• OpenClaw geïnstalleerd en draaiend via Telegram (installatiegids). Telegrams BotFather-integratie heeft de beste ondersteuning voor slashopdrachten; daarmee trigger je in deze tutorial de skills.
• uv geïnstalleerd (beide skills in deze tutorial gebruiken dit voor Python-afhankelijkheden)
• Handigheid met de terminal, YAML en Markdown
• Een Replicate API-token voor de afbeeldingsgeneratie-skill (gratis aanmelden, betalen per gebruik)
• Een GitHub-account dat minstens een week oud is, als je wilt publiceren op ClawHub

Als je OpenClaw liever met lokale modellen draait, behandelt de OpenClaw met Ollama-tutorial die setup.

Je eerste OpenClaw-skill bouwen

Deze eerste skill wikkelt een Python-script in dat Jupyter-notebooks omzet naar Word-documenten, met ondersteuning voor markdownopmaak, codeblokken, afbeeldingen, tabellen en hyperlinks zodat de .docx-output de structuur van het originele notebook bewaart. Als je regelmatig notebook-inhoud overdraagt aan mensen die in Word werken, maak je van die handmatige export een enkele slashopdracht.

Maak de skillmap aan in de beheerde skills-map van OpenClaw:

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

Skills in ~/.openclaw/skills zijn beschikbaar in al je sessies. Je kunt ze ook in een project plaatsen op <project>/skills om ze te beperken tot die workspace. Verschijnt een naam op beide locaties, dan wint de workspacekopie van de beheerde, die op zijn beurt een meegeleverde skill met dezelfde naam overschrijft.

De SKILL.md schrijven

Elke skill heeft één bestand nodig: SKILL.md. YAML-frontmatter bovenaan bepaalt hoe OpenClaw de skill laadt, en de markdown-body eronder bevat de instructies die de agent tijdens runtime volgt.

Maak ~/.openclaw/skills/notebook-to-docx/SKILL.md aan en begin met de frontmatter:

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

name fungeert ook als de slashopdracht (/notebook-to-docx). description geeft de agent een oneliner om de relevantie voor de huidige taak te beoordelen. Met user-invocable: true wordt de slashopdracht in je Telegram-chat geregistreerd. De metadata-JSON regelt gating bij het laden: requires.bins vertelt OpenClaw om deze skill over te slaan als uv niet op de systeem-PATH staat, in plaats van pas tijdens runtime te falen. 

Wil je het omgekeerde, waarbij de skill nooit afgaat tenzij je expliciet de slashopdracht typt, zet dan disable-model-invocation: true.

Tip: YAML-frontmatter ondersteunt alleen enkelregelige waarden. Meerdere regels of block scalars veroorzaken parsefouten, daarom is metadata een JSON-object op één regel in plaats van geneste YAML.

Voeg onder de frontmatter de instructietekst toe:

# 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} is een templatevariabele die tijdens runtime naar het pad van de skillmap verwijst, zodat je de locatie niet hardcoded hoeft op te nemen. Dat is handig als iemand jouw skill in een andere map installeert. 

De uv run --with-flags halen de drie libraries op die het script nodig heeft, zodat de skill zelfvoorzienend blijft in plaats van te veronderstellen dat die packages al in de omgeving van de gebruiker staan.

Het bijbehorende script

Het Python-script komt in dezelfde map als SKILL.md. Met zo’n 490 regels is het te lang om hier op te nemen, dus haal het volledige script uit deze gist en plaats het als notebook_to_docx.py in ~/.openclaw/skills/notebook-to-docx/. Het dekt alles wat in de sectie Features van de SKILL.md hierboven staat.

Hier is het entrypoint, zodat je op hoofdlijnen ziet wat het doet:

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

De skill testen

OpenClaw maakt bij de start van een sessie een momentopname van de skill-lijst, maar een ingebouwde filewatcher pikt nieuwe SKILL.md-bestanden binnen ongeveer 250 ms op. Als de skill niet verschijnt, herstart de sessie.

Dit is het notebook dat we als test gebruiken:

Open je Telegram-chat met OpenClaw en typ /notebook-to-docx, en geef aan welk notebook je wilt converteren:

Het resulterende Word-document:

Koppen, codeblokken, inline-opmaak en hyperlinks komen allemaal terecht in de juiste Word-stijlen. Als er iets niet goed uitziet in je output, controleer dan of de features in je SKILL.md overeenkomen met wat het script ondersteunt.

OpenClaw-beveiliging en sandboxing

OpenClaw kan toolexecutie in Docker-containers draaien, wat beperkt wat een slecht functionerende of gecompromitteerde skill op je machine kan aanraken. De instelling staat in agents.defaults.sandbox in ~/.openclaw/openclaw.json, en er zijn drie modi om uit te kiezen:

• "off" is de standaard, waarbij tools direct op de host draaien zonder isolatielaag.
• "non-main" houdt je primaire chatsessie op de host, maar verplaatst achtergrond- en geautomatiseerde sessies naar containers.
• Met "all" draait elke sessie in een container, ongeacht de context.

Boven op de modus kies je een workspace-toegangsniveau dat bepaalt hoeveel van je filesystem de container ziet. De standaard, "none", geeft de sandbox een eigen geïsoleerde map onder ~/.openclaw/sandboxes zonder toegang tot je projectbestanden. 

Met "ro" wordt je workspace read-only gemount op /agent, zodat de agent je code kan lezen maar niets kan wijzigen. "rw" gaat verder en geeft volledige lees-schrijftoegang op /workspace.

Een werkende configuratie die achtergrondsessies sandboxed en ze schrijfrechten geeft, ziet er zo uit:

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

Dit wordt relevant zodra je skills API’s aanroepen of met credentials omgaan. 

Wanneer een skill in een container draait, zijn omgevingsvariabelen van de host daar niet automatisch aanwezig. Een REPLICATE_API_TOKEN die je in .bashrc hebt geëxporteerd, bestaat niet in de sandbox. Secrets moeten dus via het configsysteem van OpenClaw gaan, wat we in de volgende sectie instellen.

Tip: Als je skill requires.bins in de metadata gebruikt om op een CLI-tool te gaten, draait die check bij het laden op de host. Maar als de agent is gesandboxed, moet de binary ook in de container bestaan. Installeer die via sandbox.docker.setupCommand of bak hem in een aangepaste Docker-image.

Sandboxing beperkt ook de schade als bestandsoperaties of shellopdrachten misgaan. Een skill die per ongeluk rm -rf / uitvoert, raakt het filesystem van de container in plaats van je echte machine. Dat is op zichzelf al een goede reden om het aan te zetten, zelfs als je je eigen code vertrouwt. 

Voor meer over hoe AI-agentworkflows veiligheidsgrenzen bewaken, zie AI Agent Workflows met Claude CoWork.

Een API-verbonden skill bouwen

De tweede skill genereert afbeeldingen met Google’s Nano Banana Pro (Gemini 3 Pro Image)-model via de Replicate-API. Dat betekent dat je naast de SKILL.md-basics ook beheer van credentials en omgevingsgating moet inrichten.

Maak de skillmap aan:

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

Maak ~/.openclaw/skills/nano-banana-pro/SKILL.md en begin met de 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"}}
---

De structuur komt overeen met de eerste skill, maar het veld metadata doet meer. Er zitten nu twee gates in: requires.env controleert of REPLICATE_API_TOKEN bestaat vóór het laden van de skill, en requires.bins checkt op uv. Als een van beide ontbreekt, wordt de skill stilletjes overgeslagen. 

Het veld emoji zet een icoon in de Telegram-lijst met slashopdrachten. En primaryEnv koppelt REPLICATE_API_TOKEN aan de apiKey-snelkoppeling in de config (meer daarover in de credential-sectie hieronder).

Wil je dat de macOS Skills-UI one-click-installatie aanbiedt voor vereiste binaries, voeg dan een install-array toe aan de metadata:

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

Op Linux regel je installatie handmatig of via sandbox.docker.setupCommand.

Voeg onder de frontmatter de instructietekst toe:

# 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

De body is korter dan die van de eerste skill omdat het generatiescript het meeste afvangt. De templatevariabele {baseDir} werkt hetzelfde: hij verwijst tijdens runtime naar de skillmap.

Het generatiescript

Voeg toe: ~/.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()

Het parse’t de argumenten, roept replicate.run() aan met de modelnaam en invoerparameters, en downloadt de resulterende afbeelding. De replicate-bibliotheek leest REPLICATE_API_TOKEN automatisch uit de omgeving.

De API-credential configureren

Voeg een entry toe aan ~/.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"
    	}
  	}
	}
  }
}

Er zijn hier twee manieren om de credential aan te leveren. Het veld apiKey is een snelkoppeling die wordt gemapt naar wat primaryEnv in de skillmetadata aangeeft. Het env-blok geeft je meer controle, zodat je meerdere omgevingsvariabelen kunt injecteren als de skill die nodig heeft. 

Beide benaderingen begrenzen de waarden tot de agenrun. Ze worden gezet wanneer de run start en gewist wanneer die eindigt, zodat ze niet lekken naar je globale shellomgeving.

Testen

Start een nieuwe OpenClaw-sessie en roep de skill aan:

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

Hier is het diagram dat de skill via Nano Banana Pro op Replicate produceerde:

De afbeelding kwam door, maar daar ging een omweg aan vooraf. De eerste versie van deze SKILL.md had geen ## Rules-sectie, wat de agent ruimte gaf om te improviseren. Toen Nano Banana Pro een “service unavailable”-fout teruggaf door grote vraag, besloot de agent uit zichzelf google/nano-banana (de niet-Pro-variant) als fallback te proberen en de afbeelding daarmee te genereren.

Vanuit het perspectief van de agent was die keuze logisch: de taak afronden met alle beschikbare middelen. Voor jou was het niet wat je vroeg. De oplossing was gedragsbeperkingen toevoegen aan de instructietekst:

## 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.

De agent behandelt SKILL.md-instructies als leidraad, geen harde grenzen, en vult gaten aan met eigen oordeel. Alles wat je niet verbiedt, kan hij besluiten te proberen. 

Als bepaald gedrag belangrijk voor je is — welk model te gebruiken, waar output naartoe gaat, of er opnieuw geprobeerd moet worden bij falen — zet het expliciet in een Rules-sectie.

Skills publiceren en delen op ClawHub

ClawHub is het openbare register voor OpenClaw-skills, vrij te browsen en te installeren. Publiceren vereist een GitHub-account dat minstens een week oud is.

De CLI instellen

Installeer de ClawHub-CLI globaal:

npm i -g clawhub

Log daarna in:

clawhub login

Dit opent je browser voor GitHub-authenticatie. Na het inloggen kun je vanuit de terminal skills zoeken, installeren en publiceren.

Je skill publiceren

Om de afbeeldingsgeneratie-skill te publiceren:

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

De --slug is de unieke identifier op ClawHub en moet uniek zijn in het hele register. Als iemand al een skill met die slug heeft gepubliceerd, mislukt het commando met “only the owner can publish updates”. Kies in dat geval een andere slug, bijvoorbeeld yourname-nano-banana-pro.

De --version volgt semantische versies. Tel de versie op bij elke update die je publiceert en voeg eventueel een changelog toe:

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

ClawHub bewaart versiegeschiedenis, zodat gebruikers wijzigingen kunnen controleren en indien nodig terugdraaien.

Voor bulkacties scant clawhub sync --all je skills-map en publiceert in één keer alle nieuwe of bijgewerkte skills:

clawhub sync --all --bump patch

Community-skills installeren

Om een skill te installeren die iemand anders heeft gepubliceerd:

clawhub search "calendar"
clawhub install caldav-calendar

Geïnstalleerde skills komen standaard in ./skills terecht, die OpenClaw bij de volgende sessie als workspace-skills oppikt.

Een woord over third-party skills

In januari 2026 ontdekten beveiligingsonderzoekers bij Koi 341 kwaadaardige skills op ClawHub, in wat bekend werd als het ClawHavoc-incident. Aanvallers gebruikten typosquats en valse “vereiste” installatiestappen om de Atomic macOS Stealer (AMOS), reverse shells en payloads voor het exfiltreren van credentials te verspreiden. 

Halverwege februari 2026 was het aantal gegroeid tot meer dan 824 gemarkeerde skills in tientallen categorieën.

Lees vóór installatie van een community-skill het SKILL.md-bestand en de ondersteunende files. Let op verdachte “vereiste” installatiestappen, geobfusceerde code of base64-gecodeerde opdrachten. ClawHub verbergt automatisch skills met drie of meer gebruikersmeldingen, maar nieuwe kwaadaardige skills kunnen sneller verschijnen dan moderatie ze vindt. 

Tools zoals Clawdex kunnen je geïnstalleerde skills scannen tegen een database met bekende malafide pakketten.

Behandel third-party skills met dezelfde voorzichtigheid als elke third-party code: reviewen vóór je runt.

Conclusie

Met het SKILL.md-format, credential-scoping via openclaw.json en de ClawHub-CLI heb je de volledige levenscyclus in handen: van lokale automatisering tot gedeeld pakket. 

Het meeste werk bij het bouwen van een nieuwe OpenClaw-skill is het schrijven van heldere instructies in de markdown-body en bepalen waarop je in de metadata wilt gaten. De eigenlijke code, of dat nu een conversiescript of een API-call is, blijft in aparte bestanden die je zelfstandig kunt testen en itereren.

Wil je verder dan wat deze tutorial beslaat, dan laten de meegeleverde skills in de OpenClaw-repo zien hoe het kernteam meer uitgebreide workflows structureert. De overzicht van Claude Opus 4.6 gaat dieper in op hoe modelkeuzes het gedrag van agents beïnvloeden, en de Introductie tot Claude-modellen-cursus biedt hands-on oefening met de modellen achter agents zoals OpenClaw.