Skills (OpenClaw)

OpenClaw usa carpetas de skills compatibles con AgentSkills para enseñar al agente cómo usar herramientas. Cada skill es un directorio que contiene un SKILL.md con frontmatter YAML e instrucciones. OpenClaw carga skills incluidos de fábrica más sobreescrituras locales opcionales, y los filtra al cargar según el entorno, la configuración y la presencia de binarios.

Ubicaciones y precedencia

Los skills se cargan desde tres lugares:

  1. Skills incluidos: distribuidos con la instalación (paquete npm u OpenClaw.app)
  2. Skills gestionados/locales: ~/.openclaw/skills
  3. Skills de workspace: <workspace>/skills

Si un nombre de skill entra en conflicto, la precedencia es:

<workspace>/skills (más alta) -> ~/.openclaw/skills -> skills incluidos (más baja)

Adicionalmente, puedes configurar carpetas extra de skills (prioridad más baja) mediante skills.load.extraDirs en ~/.openclaw/openclaw.json.

Skills por agente vs compartidos

En configuraciones multi-agente, cada agente tiene su propio workspace. Esto significa:

  • Los skills por agente viven en <workspace>/skills solo para ese agente.
  • Los skills compartidos viven en ~/.openclaw/skills (gestionados/locales) y son visibles para todos los agentes en la misma máquina.
  • Las carpetas compartidas también se pueden agregar con skills.load.extraDirs (prioridad más baja) si deseas un paquete de skills común usado por múltiples agentes.

Si el mismo nombre de skill existe en más de un lugar, la precedencia habitual aplica: workspace gana, luego gestionados/locales, luego incluidos.

Plugins + skills

Los plugins pueden incluir sus propios skills listando directorios skills en openclaw.plugin.json (rutas relativas a la raíz del plugin). Los skills de plugins se cargan cuando el plugin está habilitado y participan en las reglas normales de precedencia de skills. Puedes controlarlos con metadata.openclaw.requires.config en la entrada de configuración del plugin. Consulta Plugins para descubrimiento/configuración y Herramientas para la superficie de herramientas que esos skills enseñan.

ClawHub (instalar + sincronizar)

ClawHub es el registro público de skills para OpenClaw. Navega en https://clawhub.com. Úsalo para descubrir, instalar, actualizar y respaldar skills. Guía completa: ClawHub.

Flujos comunes:

  • Instalar un skill en tu workspace:
    • clawhub install <skill-slug>
  • Actualizar todos los skills instalados:
    • clawhub update --all
  • Sincronizar (escanear + publicar actualizaciones):
    • clawhub sync --all

Por defecto, clawhub instala en ./skills dentro de tu directorio de trabajo actual (o recurre al workspace configurado de OpenClaw). OpenClaw lo detecta como <workspace>/skills en la siguiente sesión.

Notas de seguridad

  • Trata los skills de terceros como código no confiable. Léelos antes de habilitarlos.
  • Prefiere ejecuciones en sandbox para entradas no confiables y herramientas riesgosas. Consulta Sandboxing.
  • El descubrimiento de skills de workspace y extra-dir solo acepta raíces de skills y archivos SKILL.md cuyo realpath resuelto permanece dentro de la raíz configurada.
  • skills.entries.*.env y skills.entries.*.apiKey inyectan secretos en el proceso del host para ese turno del agente (no en el sandbox). Mantén los secretos fuera de prompts y logs.
  • Para un modelo de amenazas más amplio y checklists, consulta Seguridad.

Formato (AgentSkills + compatible con Pi)

SKILL.md debe incluir al menos:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

Notas:

  • Seguimos la especificación AgentSkills para diseño/intención.
  • El parser usado por el agente embebido admite solo claves de frontmatter de una sola línea.
  • metadata debe ser un objeto JSON de una sola línea.
  • Usa {baseDir} en las instrucciones para referenciar la ruta de la carpeta del skill.
  • Claves de frontmatter opcionales:

    • homepage — URL mostrada como “Website” en la UI de Skills de macOS (también admitida con metadata.openclaw.homepage).

    • user-invocable — true|false (por defecto: true). Cuando es true, el skill se expone como comando slash de usuario.

    • disable-model-invocation — true|false (por defecto: false). Cuando es true, el skill se excluye del prompt del modelo (sigue disponible por invocación de usuario).

    • command-dispatch — tool (opcional). Cuando se configura como tool, el comando slash omite el modelo y despacha directamente a una herramienta.

    • command-tool — nombre de la herramienta a invocar cuando command-dispatch: tool está configurado.

    • command-arg-mode — raw (por defecto). Para despacho a herramienta, reenvía la cadena de argumentos raw a la herramienta (sin parseo del core).

      La herramienta se invoca con los parámetros: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Filtrado (filtros en tiempo de carga)

OpenClaw filtra skills al cargar usando metadata (JSON de una sola línea):

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Campos bajo metadata.openclaw:

  • always: true — siempre incluir el skill (omite otros filtros).
  • emoji — emoji opcional usado por la UI de Skills de macOS.
  • homepage — URL opcional mostrada como “Website” en la UI de Skills de macOS.
  • os — lista opcional de plataformas (darwin, linux, win32). Si se configura, el skill solo es elegible en esos sistemas operativos.
  • requires.bins — lista; cada uno debe existir en PATH.
  • requires.anyBins — lista; al menos uno debe existir en PATH.
  • requires.env — lista; la variable de entorno debe existir o estar proporcionada en la configuración.
  • requires.config — lista de rutas de openclaw.json que deben ser truthy.
  • primaryEnv — nombre de variable de entorno asociada con skills.entries.<name>.apiKey.
  • install — array opcional de especificaciones de instalador usadas por la UI de Skills de macOS (brew/node/go/uv/download).

Nota sobre sandboxing:

  • requires.bins se verifica en el host al cargar el skill.
  • Si un agente está en sandbox, el binario también debe existir dentro del contenedor. Instálalo con agents.defaults.sandbox.docker.setupCommand (o una imagen personalizada). setupCommand se ejecuta una vez después de crear el contenedor. Las instalaciones de paquetes también requieren egreso de red, un sistema de archivos raíz con escritura y un usuario root en el sandbox. Ejemplo: el skill summarize (skills/summarize/SKILL.md) necesita el CLI summarize en el contenedor del sandbox para ejecutarse allí.

Ejemplo de instalador:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Notas:

  • Si hay múltiples instaladores listados, el gateway elige una única opción preferida (brew cuando está disponible, de lo contrario node).
  • Si todos los instaladores son download, OpenClaw lista cada entrada para que puedas ver los artefactos disponibles.
  • Las especificaciones de instalador pueden incluir os: ["darwin"|"linux"|"win32"] para filtrar opciones por plataforma.
  • Las instalaciones de Node respetan skills.install.nodeManager en openclaw.json (por defecto: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta las instalaciones de skills; el runtime del Gateway debe seguir siendo Node (Bun no recomendado para WhatsApp/Telegram).
  • Instalaciones de Go: si falta go y brew está disponible, el gateway instala Go mediante Homebrew primero y configura GOBIN al bin de Homebrew cuando es posible.
  • Instalaciones por descarga: url (obligatorio), archive (tar.gz | tar.bz2 | zip), extract (por defecto: auto cuando se detecta archivo), stripComponents, targetDir (por defecto: ~/.openclaw/tools/<skillKey>).

Si no hay metadata.openclaw presente, el skill siempre es elegible (a menos que esté desactivado en la configuración o bloqueado por skills.allowBundled para skills incluidos).

Sobreescrituras de configuración (~/.openclaw/openclaw.json)

Los skills incluidos/gestionados se pueden activar/desactivar y configurar con valores de env:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // o string en texto plano
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Nota: si el nombre del skill contiene guiones, pon la clave entre comillas (JSON5 permite claves entrecomilladas).

Las claves de configuración coinciden con el nombre del skill por defecto. Si un skill define metadata.openclaw.skillKey, usa esa clave en skills.entries.

Reglas:

  • enabled: false desactiva el skill aunque esté incluido/instalado.
  • env: se inyecta solo si la variable no está ya configurada en el proceso.
  • apiKey: conveniencia para skills que declaran metadata.openclaw.primaryEnv. Admite string en texto plano u objeto SecretRef ({ source, provider, id }).
  • config: bolsa opcional para campos personalizados por skill; las claves personalizadas deben ir aquí.
  • allowBundled: lista de permitidos opcional solo para skills incluidos. Si se configura, solo los skills incluidos en la lista son elegibles (los skills gestionados/de workspace no se ven afectados).

Inyección de entorno (por ejecución de agente)

Cuando se inicia una ejecución de agente, OpenClaw:

  1. Lee los metadatos del skill.
  2. Aplica cualquier skills.entries.<key>.env o skills.entries.<key>.apiKey a process.env.
  3. Construye el prompt del sistema con los skills elegibles.
  4. Restaura el entorno original después de que termina la ejecución.

Esto tiene alcance de ejecución del agente, no es un entorno de shell global.

Instantánea de sesión (rendimiento)

OpenClaw toma una instantánea de los skills elegibles cuando comienza una sesión y reutiliza esa lista para turnos subsiguientes en la misma sesión. Los cambios en skills o configuración surten efecto en la siguiente sesión nueva.

Los skills también pueden refrescarse a mitad de sesión cuando el watcher de skills está habilitado o cuando aparece un nuevo nodo remoto elegible (ver abajo). Piensa en esto como una recarga en caliente: la lista refrescada se aplica en el siguiente turno del agente.

Nodos remotos de macOS (gateway Linux)

Si el Gateway se ejecuta en Linux pero hay un nodo macOS conectado con system.run permitido (seguridad de aprobaciones de Exec no configurada como deny), OpenClaw puede tratar los skills solo para macOS como elegibles cuando los binarios requeridos están presentes en ese nodo. El agente debe ejecutar esos skills mediante la herramienta nodes (típicamente nodes.run).

Esto depende de que el nodo reporte su soporte de comandos y de una verificación de binarios mediante system.run. Si el nodo macOS se desconecta después, los skills permanecen visibles; las invocaciones pueden fallar hasta que el nodo se reconecte.

Watcher de skills (refresco automático)

Por defecto, OpenClaw observa las carpetas de skills y actualiza la instantánea de skills cuando los archivos SKILL.md cambian. Configúralo en skills.load:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Impacto en tokens (lista de skills)

Cuando hay skills elegibles, OpenClaw inyecta una lista XML compacta de skills disponibles en el prompt del sistema (mediante formatSkillsForPrompt en pi-coding-agent). El costo es determinista:

  • Overhead base (solo cuando hay 1+ skill): 195 caracteres.
  • Por skill: 97 caracteres + la longitud de los valores XML-escaped de <name>, <description> y <location>.

Fórmula (caracteres):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

Notas:

  • El escape XML expande & < > " ' en entidades (&amp;, &lt;, etc.), aumentando la longitud.
  • El conteo de tokens varía según el tokenizador del modelo. Una estimación aproximada al estilo OpenAI es ~4 caracteres/token, así que 97 caracteres ≈ 24 tokens por skill más la longitud real de tus campos.

Ciclo de vida de skills gestionados

OpenClaw incluye un conjunto base de skills como skills incluidos como parte de la instalación (paquete npm u OpenClaw.app). ~/.openclaw/skills existe para sobreescrituras locales (por ejemplo, fijar/parchear un skill sin cambiar la copia incluida). Los skills de workspace son propiedad del usuario y sobreescriben ambos en conflictos de nombre.

Referencia de configuración

Consulta Configuración de skills para el esquema completo de configuración.

¿Buscas más skills?

Navega en https://clawhub.com.

arrow_back
Anterior
Slash Commands
Siguiente
Skills Config
arrow_forward