Cómo crear habilidades personalizadas en OpenClaw: tutorial práctico

Las habilidades integradas de OpenClaw cubren flujos de trabajo comunes, y en ClawHub hay muchas más. Pero las que más importan suelen ser las que aún no existen: automatizaciones adaptadas a tus propios proyectos y herramientas.

Este tutorial te muestra cómo crear dos habilidades personalizadas. La primera envuelve un script de Python que convierte cuadernos de Jupyter en documentos de Word. Si escribes en notebooks pero entregas archivos .docx a editores o stakeholders, convierte una exportación manual en un comando de barra. La segunda genera imágenes con Nano Banana Pro a través de la API de Replicate, añadiendo gestión de credenciales y acotación del entorno sobre lo básico.

El tutorial también cubre el aislamiento con Docker, el filtrado por metadatos y cómo publicar habilidades en ClawHub. Para una visión más amplia de la plataforma OpenClaw, consulta OpenClaw Projects: What You Can Build y nuestra guía de las habilidades clave para agentes. 

¿Qué son las habilidades de OpenClaw?

Las habilidades son la forma de añadir nuevos comportamientos al agente de OpenClaw. Una habilidad puede ser tan simple como un comando de barra que re-formatea código, o tan compleja como un flujo de trabajo en varios pasos que revisa PRs y publica comentarios en Jira o Slack.

Si has usado servidores MCP (Model Context Protocol) en Claude Code u otras herramientas similares, las habilidades cumplen otra función. Los servidores MCP son procesos separados que exponen herramientas mediante un protocolo estándar, ideal para integraciones que requieren estado persistente o varios endpoints de herramientas. 

Con las habilidades te saltas todo eso: escribes instrucciones en lenguaje natural que el agente lee y sigue en tiempo de ejecución, lo que acelera su creación cuando solo quieres automatizar una cosa. La comparativa entre OpenClaw y Claude Code profundiza en los pros y contras.

Los hooks, el otro punto de extensión, se disparan automáticamente cuando ocurre algo, como la finalización de una llamada a una herramienta o la generación de una respuesta por el modelo. Las habilidades permanecen en reposo hasta que el usuario escribe un comando de barra o el agente decide que una es relevante para la tarea en curso.

OpenClaw incluye 49 habilidades que cubren email, calendarios, GitHub, automatización del navegador y más. La comunidad ha publicado miles adicionales en ClawHub. Para conocer la evolución de la plataforma, echa un vistazo a la historia de MoltBot a ClawdBot.

Requisitos previos

Vas a necesitar:

• OpenClaw instalado y ejecutándose vía Telegram (guía de instalación). La integración BotFather de Telegram ofrece el mejor soporte para comandos de barra, que es como activarás habilidades a lo largo de este tutorial.
• uv instalado (ambas habilidades del tutorial lo usan para dependencias de Python)
• Soltura con la terminal, YAML y Markdown
• Un token de la API de Replicate para la habilidad de generación de imágenes (registro gratuito, pago por uso)
• Una cuenta de GitHub con al menos una semana de antigüedad si quieres publicar en ClawHub

Si prefieres ejecutar OpenClaw con modelos locales, el tutorial OpenClaw con Ollama cubre esa configuración.

Crea tu primera habilidad de OpenClaw

Esta primera habilidad envuelve un script de Python que convierte cuadernos de Jupyter en documentos de Word, manejando formato de markdown, bloques de código, imágenes, tablas e hipervínculos para que la salida .docx conserve la estructura del notebook original. Si a menudo entregas contenido de notebooks a personas que trabajan en Word, convierte esa exportación manual en un único comando de barra.

Crea la carpeta de la habilidad en el directorio de habilidades gestionadas de OpenClaw:

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

Las habilidades en ~/.openclaw/skills están disponibles en todas tus sesiones. También puedes colocarlas dentro de un proyecto en <project>/skills para acotarlas a ese espacio de trabajo; cuando un nombre aparece en ambas ubicaciones, gana la copia del workspace, que a su vez tiene prioridad sobre cualquier habilidad integrada con el mismo nombre.

Escribir el SKILL.md

Cada habilidad necesita un único archivo: SKILL.md. El frontmatter en YAML de la parte superior define cómo carga OpenClaw la habilidad, y el cuerpo en markdown bajo él contiene las instrucciones que el agente sigue en tiempo de ejecución.

Crea ~/.openclaw/skills/notebook-to-docx/SKILL.md, empezando por el frontmatter:

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

name también funciona como comando de barra (/notebook-to-docx). description le da al agente una línea que usa para juzgar la relevancia con la tarea actual. Al establecer user-invocable: true registras el comando de barra en tu chat de Telegram. El JSON de metadata gestiona el filtrado en carga: requires.bins le dice a OpenClaw que omita esta habilidad si uv no está en el PATH del sistema, en lugar de fallar en tiempo de ejecución. 

Si quieres lo contrario, que la habilidad nunca se ejecute salvo que escribas explícitamente el comando de barra, establece disable-model-invocation: true.

Consejo: el frontmatter en YAML solo admite valores de una línea. Las cadenas multilínea o los bloques escalares causarán errores de parseo; por eso metadata es un objeto JSON de una sola línea y no YAML anidado.

Debajo del frontmatter, añade el cuerpo de instrucciones:

# 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} es una variable de plantilla que se resuelve a la ruta de la carpeta de la habilidad en tiempo de ejecución, así no necesitas codificar la ubicación. Esto importa cuando alguien instala tu habilidad en un directorio diferente. 

Las banderas uv run --with traen las tres librerías que necesita el script, manteniendo la habilidad autocontenida en lugar de asumir que esos paquetes existen en el entorno del usuario.

El script de apoyo

El script de Python va en la misma carpeta que SKILL.md. Con unas 490 líneas, es demasiado largo para incluirlo aquí, así que descarga el script completo desde este gist y colócalo como notebook_to_docx.py en ~/.openclaw/skills/notebook-to-docx/. Cubre todo lo listado en la sección de Features del SKILL.md anterior.

Aquí tienes el punto de entrada para que veas a alto nivel qué hace:

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

Probar la habilidad

OpenClaw hace un snapshot de su lista de habilidades al iniciar la sesión, pero un watcher integrado detecta nuevos archivos SKILL.md en unos 250 ms. Si la habilidad no aparece, reinicia la sesión.

Este es el notebook que usaremos de prueba:

Abre tu chat de Telegram con OpenClaw y escribe /notebook-to-docx, luego indícale qué notebook debe convertir:

El documento de Word resultante:

Encabezados, bloques de código, formato en línea e hipervínculos llegan con los estilos correctos de Word. Si algo no cuadra en tu salida, comprueba que la lista de características en tu SKILL.md coincide con lo que soporta el script.

Seguridad y aislamiento en OpenClaw

OpenClaw puede ejecutar herramientas dentro de contenedores Docker, lo que limita qué puede tocar en tu máquina una habilidad que se porte mal o esté comprometida. El ajuste está en agents.defaults.sandbox dentro de ~/.openclaw/openclaw.json, y hay tres modos:

• "off" es el predeterminado; las herramientas se ejecutan en el host sin capa de aislamiento.
• "non-main" mantiene tu sesión principal en el host pero mueve las sesiones en segundo plano y automatizadas a contenedores.
• Con "all", todas las sesiones se ejecutan dentro de un contenedor, sea cual sea el contexto.

Además del modo, eliges un nivel de acceso al workspace que decide cuánto del sistema de archivos verá el contenedor. El valor por defecto, "none", da a la sandbox su propio directorio aislado en ~/.openclaw/sandboxes sin acceso a tus archivos de proyecto. 

Con "ro", tu workspace se monta en solo lectura en /agent, por lo que el agente puede leer tu código pero no cambiar nada. "rw" va más allá y concede acceso de lectura y escritura en /workspace.

Una configuración funcional que aísla las sesiones en segundo plano y les da acceso de escritura sería así:

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

Esto se vuelve relevante en cuanto tus habilidades empiezan a llamar APIs o gestionar credenciales. 

Cuando una habilidad se ejecuta dentro de un contenedor, las variables de entorno del host no aparecen automáticamente. Un REPLICATE_API_TOKEN que exportaste en .bashrc no existirá dentro de la sandbox, así que los secretos deben pasar por el sistema de configuración de OpenClaw, que es lo que configuraremos en la siguiente sección.

Consejo: si tu habilidad usa requires.bins en sus metadatos para filtrar por una herramienta de CLI, esa comprobación se ejecuta en el host al cargar. Pero cuando el agente está aislado, el binario también debe existir dentro del contenedor. Instálalo vía sandbox.docker.setupCommand o inclúyelo en una imagen de Docker personalizada.

El aislamiento también limita el radio de impacto cuando fallan operaciones de archivos o comandos de shell. Una habilidad que por error ejecute rm -rf / golpea el sistema de archivos del contenedor y no tu máquina real, lo cual es un buen motivo para activarlo incluso si confías en tu propio código. 

Para más información sobre cómo los flujos de trabajo de agentes de IA gestionan límites de seguridad, consulta AI Agent Workflows with Claude CoWork.

Crear una habilidad conectada a una API

La segunda habilidad genera imágenes usando el modelo Nano Banana Pro (Gemini 3 Pro Image) de Google a través de la API de Replicate, lo que implica conectar la gestión de credenciales y el filtrado por entorno además de lo básico del SKILL.md.

Crea la carpeta de la habilidad:

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

Crea ~/.openclaw/skills/nano-banana-pro/SKILL.md, empezando por el 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 estructura coincide con la primera habilidad, pero el campo metadata hace más cosas. Ahora incluye dos filtros: requires.env comprueba que REPLICATE_API_TOKEN exista antes de cargar la habilidad, y requires.bins verifica la presencia de uv. Si falta cualquiera de los dos, la habilidad se omite sin ruido. 

El campo emoji añade un icono en la lista de comandos de barra de Telegram. Y primaryEnv mapea REPLICATE_API_TOKEN al atajo apiKey en la configuración (más sobre esto en la sección de credenciales).

Si quieres que la interfaz de Skills de macOS ofrezca instalación con un clic para los binarios requeridos, añade un array install a los metadatos:

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

En Linux, gestiona la instalación manualmente o vía sandbox.docker.setupCommand.

Debajo del frontmatter, añade el cuerpo de instrucciones:

# 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

El cuerpo es más corto que en la primera habilidad porque el script de generación asume la mayor parte de la complejidad. La variable de plantilla {baseDir} funciona igual: se resuelve a la carpeta de la habilidad en tiempo de ejecución.

El script de generación

Añade ~/.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()

Analiza los argumentos, llama a replicate.run() con el nombre del modelo y los parámetros de entrada, y descarga la imagen resultante. La librería replicate lee REPLICATE_API_TOKEN del entorno automáticamente.

Configurar la credencial de la API

Añade una entrada 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"
    	}
  	}
	}
  }
}

Hay dos formas de proporcionar la credencial aquí. El campo apiKey es un atajo que mapea a lo que declara primaryEnv en los metadatos de la habilidad. El bloque env te da más control fino, permitiendo inyectar múltiples variables de entorno si la habilidad las necesita. 

Ambos enfoques acotan los valores a la ejecución del agente. Se establecen al iniciar la ejecución y se borran cuando termina, así que no se filtran a tu entorno global de la shell.

Pruebas

Inicia una nueva sesión de OpenClaw e invoca la habilidad:

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

Este es el diagrama que generó la habilidad con Nano Banana Pro en Replicate:

La imagen llegó, pero llegar hasta aquí implicó un rodeo. La primera versión de este SKILL.md no tenía sección ## Rules, lo que dio margen al agente para improvisar. Cuando Nano Banana Pro devolvió un error de "servicio no disponible" por alta demanda, el agente decidió por su cuenta probar google/nano-banana (la variante no Pro) como alternativa y generó la imagen con ese modelo.

Desde la perspectiva del agente, la decisión tenía sentido: completar la tarea por cualquier medio disponible. Desde la tuya, no era lo que pediste. La solución fue añadir restricciones de comportamiento al cuerpo de instrucciones:

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

El agente trata las instrucciones del SKILL.md como guía más que como límites duros, y rellenará huecos con su propio criterio. Cualquier cosa que no prohíbas, puede decidir intentarla. 

Si un comportamiento te importa —ya sea qué modelo usar, dónde enviar la salida o si reintentar ante fallos—, déjalo claro en una sección de Rules.

Publicar y compartir habilidades en ClawHub

ClawHub es el registro público de habilidades de OpenClaw, gratuito para explorar e instalar. Para publicar necesitas una cuenta de GitHub con al menos una semana de antigüedad.

Configurar la CLI

Instala la CLI de ClawHub globalmente:

npm i -g clawhub

Luego autentícate:

clawhub login

Esto abrirá tu navegador para autenticarte con GitHub. Una vez autenticado, podrás buscar, instalar y publicar habilidades desde la terminal.

Publicar tu habilidad

Para publicar la habilidad de generación de imágenes:

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

El --slug es el identificador único en ClawHub y debe ser único en todo el registro. Si alguien ya ha publicado una habilidad con ese slug, el comando fallará con un error de "solo el propietario puede publicar actualizaciones". En ese caso, elige otro slug, por ejemplo yourname-nano-banana-pro.

El --version sigue versionado semántico. Cada vez que publiques una actualización, incrementa el número de versión y, opcionalmente, añade 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 conserva el historial de versiones para que los usuarios puedan auditar cambios y, si es necesario, volver atrás.

Para operaciones en lote, clawhub sync --all escanea tu directorio de habilidades y publica de una vez cualquier habilidad nueva o actualizada:

clawhub sync --all --bump patch

Instalar habilidades de la comunidad

Para instalar una habilidad publicada por otra persona:

clawhub search "calendar"
clawhub install caldav-calendar

Las habilidades instaladas van por defecto a ./skills, que OpenClaw detecta como habilidades del workspace en la siguiente sesión.

Una nota sobre habilidades de terceros

En enero de 2026, investigadores de seguridad en Koi descubrieron 341 habilidades maliciosas en ClawHub en lo que se conoció como el incidente ClawHavoc. Los atacantes usaron nombres typosquatted de habilidades y falsos pasos de instalación de "prerrequisitos" para distribuir el ladrón Atomic para macOS (AMOS), shells inversas y cargas para exfiltración de credenciales. 

A mediados de febrero de 2026, el recuento había crecido a más de 824 habilidades marcadas en docenas de categorías.

Antes de instalar cualquier habilidad de la comunidad, lee su SKILL.md y los archivos de soporte. Fíjate en pasos de instalación de "prerrequisitos" sospechosos, código ofuscado o comandos codificados en base64. ClawHub oculta automáticamente habilidades con tres o más reportes de usuarios, pero pueden aparecer habilidades maliciosas nuevas más rápido de lo que llega la moderación. 

Herramientas como Clawdex pueden escanear tus habilidades instaladas contra una base de datos de paquetes maliciosos conocidos.

Trata las habilidades de terceros con la misma cautela que cualquier código de terceros: revisa antes de ejecutar.

Conclusión

Entre el formato SKILL.md, el acotado de credenciales a través de openclaw.json y la CLI de ClawHub, tienes todo el ciclo de vida: de la automatización local al paquete compartido. 

La mayor parte del trabajo al crear una nueva habilidad de OpenClaw está en escribir instrucciones claras en el cuerpo en markdown y decidir qué filtrar en los metadatos. El código en sí, ya sea un script de conversión o una llamada a una API, vive en archivos separados que puedes probar e iterar de forma independiente.

Para ir más allá de lo que cubre este tutorial, las habilidades integradas en el repositorio de OpenClaw muestran cómo el equipo central estructura flujos de trabajo más complejos. La descripción de Claude Opus 4.6 profundiza en cómo las elecciones de modelo afectan al comportamiento del agente, y el curso Introduction to Claude Models ofrece práctica guiada con los modelos detrás de agentes como OpenClaw.