Configura tus habilidades en OpenClaw: Guía de directorios

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

Ubicaciones y precedencia

OpenClaw carga skills de estas fuentes:

1. Extra skill folders: configuradas con skills.load.extraDirs
2. Bundled skills: incluidas con la instalación (paquete npm o OpenClaw.app)
3. Managed/local skills: ~/.openclaw/skills
4. Personal agent skills: ~/.agents/skills
5. Project agent skills: <workspace>/.agents/skills
6. Workspace skills: <workspace>/skills

Si hay un conflicto de nombres, la precedencia es:

<workspace>/skills (máxima) → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled skills → skills.load.extraDirs (mínima)

Skills por agente vs skills compartidas

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

• Las skills por agente viven en <workspace>/skills solo para ese agente.
• Las skills de proyecto del agente viven en <workspace>/.agents/skills y se aplican a ese workspace antes que la carpeta normal skills/.
• Las skills personales del agente viven en ~/.agents/skills y se aplican en todos los workspaces de esa máquina.
• Las skills compartidas viven en ~/.openclaw/skills (gestionadas/locales) y son visibles para todos los agentes en la misma máquina.
• También puedes añadir carpetas compartidas mediante skills.load.extraDirs (precedencia mínima) si quieres un pack de skills común usado por varios agentes.

Si el mismo nombre de skill existe en más de un lugar, se aplica la precedencia habitual: gana el workspace, luego las skills de proyecto, luego las personales, luego las gestionadas/locales, luego las bundled y finalmente las carpetas extra.

Plugins + skills

Los plugins pueden incluir sus propias skills listando directorios skills en openclaw.plugin.json (rutas relativas a la raíz del plugin). Las skills del plugin se cargan cuando el plugin está habilitado. Actualmente, esos directorios se fusionan en la misma ruta de baja precedencia que skills.load.extraDirs, por lo que una skill con el mismo nombre que sea bundled, gestionada, de agente o de workspace la sobrescribirá. Puedes filtrarlas mediante metadata.openclaw.requires.config en la entrada de configuración del plugin. Consulta [Plugins](/tools/

Notas de seguridad

• Trata las skills de terceros como código no confiable. Léelas antes de activarlas.
• Prefiere ejecuciones en sandbox para inputs no confiables y herramientas de riesgo. Consulta Sandboxing.
• El descubrimiento de skills en el workspace y en extra-dir solo acepta raíces de skills y archivos SKILL.md cuyo realpath resuelto permanezca dentro de la raíz configurada.
• Las instalaciones de dependencias de skills respaldadas por el Gateway (skills.install, onboarding y la interfaz de configuración de Skills) ejecutan el escáner de código peligroso integrado antes de ejecutar los metadatos del instalador. Los hallazgos marcados como critical bloquean la acción por defecto, a menos que el usuario establezca explícitamente el override de peligro; los hallazgos sospechosos solo muestran una advertencia.
• openclaw skills install <slug> funciona de forma distinta: descarga una carpeta de skill de ClawHub en el workspace y no utiliza la ruta de metadatos del instalador mencionada arriba.
• skills.entries.*.env y skills.entries.*.apiKey inyectan secretos en el proceso host para ese turno del agente (no en el sandbox). Mantén los secretos fuera de los prompts y los logs.
• Para conocer un modelo de amenazas más amplio y ver las listas de verificación, consulta Security.

Formato (AgentSkills + compatible con Pi)

SKILL.md debe incluir al menos:

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

Notas:

• Seguimos la especificación de AgentSkills para el diseño y la intención.
• El parser que utiliza el agente embebido solo admite keys de frontmatter en una sola línea.
• metadata debe ser un objeto JSON de una sola línea.
• Usa {baseDir} en las instrucciones para hacer referencia a la ruta de la carpeta de la skill.
• Keys opcionales de frontmatter:

  • homepage: URL que aparece como “Website” en la interfaz de Skills para macOS (también compatible mediante metadata.openclaw.homepage).

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

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

  • command-dispatch: tool (opcional). Cuando se establece en tool, el comando slash omite el modelo y se envía directamente a una herramienta.

  • command-tool: nombre de la herramienta a invocar cuando se configura command-dispatch: tool.

  • command-arg-mode: raw (por defecto). Para el envío a herramientas, reenvía la cadena de argumentos sin procesar a la herramienta (sin parsing del core).

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

Gating (filtros en tiempo de carga)

OpenClaw filtra las skills al momento de la carga usando metadata (JSON de una sola línea):

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Campos bajo metadata.openclaw:

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

Nota sobre el sandboxing:

• requires.bins se verifica en el host al cargar la skill.
• Si un agente está en un sandbox, el binario también debe existir dentro del contenedor. Instálalo mediante agents.defaults.sandbox.docker.setupCommand (o una imagen personalizada). setupCommand se ejecuta una vez tras crear el contenedor. Las instalaciones de paquetes también requieren salida de red, un sistema de archivos raíz con permisos de escritura y un usuario root en el sandbox. Ejemplo: la 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 se listan varios instaladores, el Gateway elige una única opción preferida (brew cuando esté disponible, de lo contrario node).
• Si todos los instaladores son de tipo download, OpenClaw lista cada entrada para que puedas ver los artefactos disponibles.
• Las especificaciones del 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 a las instalaciones de skills; el runtime del Gateway debe seguir siendo Node (no se recomienda Bun para WhatsApp/Telegram).
• Instalaciones de Go: si falta go y brew está disponible, el Gateway instala Go mediante Homebrew primero y configura GOBIN en el bin de Homebrew cuando es posible.
• Instalaciones de descarga (Download): url (requerido), archive (tar.gz | tar.bz2 | zip), extract (por defecto: auto cuando se detecta un archivo), stripComponents, targetDir (por defecto: ~/.openclaw/tools/<skillKey>).

Si no hay metadata.openclaw, la skill siempre es elegible (a menos que se desactive en la configuración o sea bloqueada por skills.allowBundled para skills integradas).

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

Las skills integradas o gestionadas se pueden activar o desactivar, y se les pueden asignar valores de entorno:

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        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 de la skill contiene guiones, escribe la key entre comillas (JSON5 permite keys con comillas).

Si quieres generación o edición de imágenes estándar dentro de OpenClaw, usa la herramienta core image_generate con agents.defaults.imageGenerationModel en lugar de una skill integrada. Los ejemplos de skills aquí son para flujos de trabajo personalizados o de terceros.

Para el análisis nativo de imágenes, usa la herramienta image con agents.defaults.imageModel. Para la generación o edición nativa de imágenes, usa image_generate con agents.defaults.imageGenerationModel. Si eliges openai/*, google/*, fal/* u otro proveedor específico de modelos de imagen, añade también la autenticación o API key de ese proveedor.

Las keys de configuración coinciden con el nombre de la skill por defecto. Si una skill define metadata.openclaw.skillKey, usa esa key bajo skills.entries.

Reglas:

• enabled: false desactiva la skill aunque esté integrada o instalada.
• env: se inyecta solo si la variable no está ya configurada en el proceso.
• apiKey: utilidad para skills que declaran metadata.openclaw.primaryEnv. Admite una cadena de texto plano o un objeto SecretRef ({ source, provider, id }).
• config: contenedor opcional para campos personalizados por skill; las keys personalizadas deben ir aquí.
• allowBundled: lista de permitidos opcional solo para skills integradas (bundled). Si se configura, solo las skills integradas en la lista serán elegibles (las skills gestionadas o del workspace no se ven afectadas).

AI Setup Assistant

Inyección de entorno (por ejecución del agent)

Cuando comienza la ejecución de un agent, OpenClaw:

1. Lee la metadata de las skills.
2. Aplica cualquier skills.entries.<key>.env o skills.entries.<key>.apiKey a process.env.
3. Construye el system prompt con las skills aptas.
4. Restaura el entorno original una vez que termina la ejecución.

Esto está limitado a la ejecución del agent, no se trata de un entorno de shell global.

Snapshot de sesión (rendimiento)

OpenClaw toma un snapshot de las skills aptas cuando comienza una sesión y reutiliza esa lista para los turnos siguientes dentro de la misma sesión. Si haces cambios en las skills o en la configuración, estos se aplicarán en la siguiente sesión nueva.

Las skills también pueden actualizarse a mitad de una sesión si tienes activado el skills watcher o si aparece un nuevo nodo remoto apto (mira más abajo). Considéralo como un hot reload: la lista actualizada se utiliza en el siguiente turno del agent.

Nodos macOS remotos (Linux Gateway)

Si el Gateway está funcionando en Linux pero tienes un macOS node conectado con system.run permitido (la seguridad de Exec approvals no está configurada como deny), OpenClaw puede tratar las skills exclusivas de macOS como disponibles si los binaries requeridos están presentes en ese node. El agent debe ejecutar esas skills usando la herramienta exec con host=node.

Esto se basa en que el node reporte su soporte de comandos y en un bin probe mediante system.run. Si el macOS node se desconecta más tarde, las skills seguirán apareciendo; las llamadas podrían fallar hasta que el node se reconecte.

Observador de skills (auto-refresh)

Por defecto, OpenClaw monitorea las carpetas de skills y actualiza el snapshot de las skills cuando los archivos SKILL.md cambian. Puedes configurar esto en skills.load:

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

Impacto de los tokens (lista de skills)

Cuando las skills son elegibles, OpenClaw inyecta una lista XML compacta de las skills disponibles en el system prompt (a través de formatSkillsForPrompt en pi-coding-agent). El costo es determinista:

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

Fórmula (caracteres):

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

Notas:

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

Ciclo de vida de las skills gestionadas

OpenClaw incluye un conjunto base de skills como bundled skills como parte de la instalación (paquete npm o OpenClaw.app). El directorio ~/.openclaw/skills existe para overrides locales (por ejemplo, para fijar o parchear una skill sin cambiar la copia empaquetada). Las skills del workspace son propiedad del usuario y tienen prioridad sobre ambas en caso de conflictos de nombres.

Referencia de configuración

Consulta Skills config para ver el esquema de configuración completo. Te recomiendo revisar esta documentación si necesitas ajustar los parámetros técnicos de tu entorno.

¿Buscas más skills?

Explora https://clawhub.com.

Relacionado

• Creating Skills — construcción de skills personalizadas
• Skills Config — referencia de configuración de skills
• Slash Commands — todos los comandos de barra disponibles
• Plugins — descripción general del sistema de plugins