Skills: instalación, uso y configuración
Objetivo en una frase: instala tus primeras OpenClaw Skills (habilidades) en tu Gateway, confirma que se cargan correctamente y completa la configuración básica de gating y allowlist.
Preparación
- Has terminado de leer la página previa «Manual avanzado: Skills y endurecimiento de seguridad», y el Gateway funciona con normalidad (OpenClaw 2.0, es decir, v2026.8.1 o superior; Node requiere 24.16.0+ o 26.1.0+).
- Sabes dónde están tu directorio workspace y tu directorio state.
- Al menos un canal de chat (Discord, Telegram, etc.) está conectado a Claw, para facilitar la verificación mediante conversación.
- Primero, establece los conceptos: una Skill no es un plugin de código, sino un archivo de instrucciones en markdown que enseña al agent cómo y cuándo usar herramientas. Cada habilidad es un directorio que contiene
SKILL.md(frontmatter YAML + cuerpo markdown). OpenClaw carga las habilidades integradas y las anulaciones locales, y al cargar filtra según el entorno, la configuración y la existencia de los binarios.
Hazlo conmigo
Paso 1: instalar una Skill
Explora y elige una habilidad de la comunidad en ClawHub, instálala con la CLI, o bien usa el método local colocando el directorio de habilidades.
openclaw skills install @owner/<slug>Por defecto se instala en skills/ del workspace actual; con --global se instala en el compartido <state-dir>/skills/.
Método local: copia el directorio completo de la habilidad (debe contener SKILL.md) al directorio de carga, por ejemplo <workspace>/skills/ a nivel de workspace, o el gestionado <state-dir>/skills/.
Resultado esperado: el directorio de la habilidad aparece en la ubicación destino y, tras recargar el Gateway, se escanea y carga.
Paso 2: confirmar la carga y la prioridad
Usa la CLI para ver la lista de habilidades cargadas y confirmar que la nueva habilidad aparece; ante conflictos de nombres, revisa según la tabla de prioridades de mayor a menor.
openclaw skills listCuando habilidades con el mismo nombre aparecen en varias ubicaciones, gana la fuente de mayor prioridad:
| Prioridad | Fuente | Ruta |
|---|---|---|
| 1 (la más alta) | Habilidades del Workspace | <workspace>/skills |
| 2 | Habilidades de agent del proyecto | <workspace>/.agents/skills |
| 3 | Habilidades de agent personales | ~/.agents/skills (solo state por defecto) |
| 4 | Habilidades gestionadas/locales | <state-dir>/skills |
| 5 | Habilidades de Workshop | <state-dir>/agents/<agentId>/agent/workshop-skills |
| 6 | Habilidades integradas / de Custodian | Se distribuyen con el paquete de instalación; las habilidades de Custodian solo son visibles bajo el agente del sistema especificado en agents.defaults.systemAgent.agentId |
| 7 (la más baja) | Directorios adicionales | Especificados por la configuración skills.* |
Resultado esperado: la nueva habilidad aparece en la lista; ante conflictos de nombres, gana la fuente de mayor prioridad.
Paso 3: configurar gating y allowlist
En el archivo de configuración (por defecto ~/.openclaw/openclaw.json), el gating de habilidades y la inyección de entorno se configuran en la sección skills.*, y la allowlist de agentes (que limita qué agentes pueden usar qué habilidades) en la sección agents.*. Guarda los cambios y ejecuta openclaw gateway restart para recargar el Gateway.
skills.* Claves habituales: skills.entries.<技能名>.enabled (interruptor para habilitar una habilidad individual), skills.entries.<技能名>.env y apiKey (inyección de entorno), skills.load.extraDirs (directorios de carga adicionales), skills.install.* (comportamiento de instalación), skills.allowBundled (lista blanca de habilidades integradas). Reglas de la allowlist: omitir agents.defaults.skills significa sin restricciones; agents.entries.<agentId>.skills es el conjunto final de habilidades de ese agent (reemplazo total, no fusión), y [] significa sin habilidades.
Resultado esperado: las habilidades con gating dejan de aplicarse a todos los agentes; los agentes dentro de la allowlist funcionan con normalidad.
Verificación
En el canal de chat, dile a Claw algo que active esa habilidad y observa si llama a las herramientas y ejecuta el flujo según lo descrito en SKILL.md. Luego renombra temporalmente el directorio de la habilidad y recarga, y confirma que la habilidad desaparece de la lista: esto demuestra que la carga proviene realmente del directorio donde la colocaste, y no de una habilidad integrada con el mismo nombre.
Errores comunes
- Habilidad con el mismo nombre se sobrescribe en silencio: la fuente de mayor prioridad gana directamente, sin error. Al investigar, busca capa por capa según la tabla de prioridades anterior.
- La habilidad no se carga de ninguna manera: OpenClaw filtra al cargar según el entorno, la configuración y la existencia de los binarios. Si la herramienta de línea de comandos de la que depende la habilidad no está instalada, puede que se filtre directamente. Usa
openclaw skills checkpara distinguir entre los tres tipos de problemas: inventory/readiness/visibility. - Directorio colocado en la capa equivocada:
~/.agents/skillssolo actúa como fuente de habilidades de agent personales bajo el state por defecto; las habilidades de la biblioteca personal en un Gateway compartido se seleccionan por identidad y revisión, no escaneando los archivos de cada usuario. - Escribir una Skill como si fuera un programa: es solo un archivo de instrucciones en markdown que enseña al agent a usar herramientas. Si quieres que Claw desarrolle habilidades por sí mismo, consulta Skill Workshop: desde 2.0 recopila proposals/checks/decisions, y desde v2026.10.5 admite historial de versiones y deshacer.
Próxima lección
Una vez que la skill funcione, entra en «Escribe tu propia Skill: SKILL.md y publicación en ClawHub» para escribir un SKILL.md desde cero y publicarlo en ClawHub. Lecturas complementarias: «Skill Workshop: deja que Claw aprenda skills por sí mismo», «Integración de MCP: dale a Claw una caja de herramientas externa».