​

Skills (OpenClaw)

​

Ubicaciones y precedencia

1. Carpetas de Skills adicionales: configuradas con skills.load.extraDirs
2. Skills incluidas: incluidas con la instalación (paquete npm o OpenClaw.app)
3. Skills gestionadas/locales: ~/.openclaw/skills
4. Skills personales del agente: ~/.agents/skills
5. Skills del agente del proyecto: <workspace>/.agents/skills
6. Skills del workspace: <workspace>/skills

​

Skills por agente frente a Skills compartidas

• Las Skills por agente viven en <workspace>/skills solo para ese agente.
• Las Skills del agente del proyecto viven en <workspace>/.agents/skills y se aplican a ese workspace antes de la carpeta normal skills/ del workspace.
• 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 de la misma máquina.
• También se pueden añadir carpetas compartidas mediante skills.load.extraDirs (precedencia más baja) si quieres un paquete común de Skills usado por varios agentes.

​

Allowlists de Skills por agente

• La ubicación/precedencia decide qué copia gana cuando una Skill con el mismo nombre existe en varios sitios.
• Las allowlists del agente deciden qué Skills visibles puede usar realmente un agente.

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // hereda github, weather
      { id: "docs", skills: ["docs-search"] }, // reemplaza los valores predeterminados
      { id: "locked-down", skills: [] }, // sin Skills
    ],
  },
}

• Omite agents.defaults.skills para permitir Skills sin restricciones de forma predeterminada.
• Omite agents.list[].skills para heredar agents.defaults.skills.
• Establece agents.list[].skills: [] para no tener Skills.
• Una lista no vacía en agents.list[].skills es el conjunto final para ese agente; no se combina con los valores predeterminados.

​

Plugins + Skills

​

ClawHub (instalación + sincronización)

• Instalar una Skill en tu workspace:
  • openclaw skills install <skill-slug>
• Actualizar todas las Skills instaladas:
  • openclaw skills update --all
• Sincronizar (examinar + publicar actualizaciones):
  • clawhub sync --all

​

Notas de seguridad

• Trata las Skills de terceros como código no confiable. Léelas antes de habilitarlas.
• Prefiere ejecuciones con sandbox para entradas no confiables y herramientas de riesgo. Consulta Sandboxing.
• El descubrimiento de Skills en el workspace y en directorios extra 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 Gateway (skills.install, incorporación y la UI de ajustes de Skills) ejecutan el escáner integrado de código peligroso antes de ejecutar los metadatos del instalador. Los hallazgos critical bloquean de forma predeterminada a menos que quien llama establezca explícitamente la sobrescritura de código peligroso; los hallazgos sospechosos siguen mostrando solo advertencias.
• openclaw skills install <slug> es diferente: descarga una carpeta de Skill de ClawHub en el workspace y no usa la ruta de metadatos del instalador anterior.
• 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 un modelo de amenazas y listas de comprobación más amplios, consulta Security.

​

Formato (compatible con AgentSkills + Pi)

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

• Seguimos la especificación de AgentSkills para diseño/intención.
• El parser usado por el agente integrado solo admite 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 referirte a la ruta de la carpeta de la Skill.
• Claves opcionales de frontmatter:
  • homepage — URL mostrada como “Website” en la UI de Skills de macOS (también admitida mediante metadata.openclaw.homepage).
  • user-invocable — true|false (predeterminado: true). Cuando es true, la Skill se expone como un slash command de usuario.
  • disable-model-invocation — true|false (predeterminado: false). Cuando es true, la Skill se excluye del prompt del modelo (sigue disponible mediante invocación del usuario).
  • command-dispatch — tool (opcional). Cuando se establece en tool, el slash command omite el modelo y se envía directamente a una herramienta.
  • command-tool — nombre de la herramienta que se invocará cuando command-dispatch: tool esté establecido.
  • command-arg-mode — raw (predeterminado). Para el envío a herramientas, reenvía la cadena de argumentos sin procesar a la herramienta (sin análisis del núcleo). La herramienta se invoca con los parámetros: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

​

Restricción (filtros en el momento de carga)

---
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",
      },
  }
---

• always: true — incluir siempre la Skill (omite las demás restricciones).
• 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 establece, la Skill solo es apta en esos SO.
• requires.bins — lista; cada elemento debe existir en PATH.
• requires.anyBins — lista; al menos uno debe existir en 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 verdaderas.
• primaryEnv — nombre de la variable de entorno asociada a skills.entries.<name>.apiKey.
• install — array opcional de especificaciones de instalación usadas por la UI de Skills de macOS (brew/node/go/uv/download).

• requires.bins se comprueba en el host en el momento de carga de la Skill.
• Si un agente está en 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 después de crear el contenedor. Las instalaciones de paquetes también requieren salida de red, un sistema de archivos raíz escribible y un usuario root en el sandbox. Ejemplo: la Skill summarize (skills/summarize/SKILL.md) necesita la CLI summarize en el contenedor del sandbox para ejecutarse allí.

---
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)",
            },
          ],
      },
  }
---

• Si se enumeran varios instaladores, el gateway elige una única opción preferida (brew cuando está disponible; de lo contrario, node).
• Si todos los instaladores son download, OpenClaw enumera 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 con Node respetan skills.install.nodeManager en openclaw.json (predeterminado: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta a las instalaciones de Skills; el runtime del Gateway debe seguir siendo Node (Bun no se recomienda para WhatsApp/Telegram).
• La selección de instaladores respaldada por Gateway se basa en preferencias, no solo en node: cuando las especificaciones de instalación mezclan tipos, OpenClaw prefiere Homebrew cuando skills.install.preferBrew está habilitado y brew existe; después uv, luego el administrador de node configurado y, después, otros respaldos como go o download.
• Si todas las especificaciones de instalación son download, OpenClaw muestra todas las opciones de descarga en lugar de contraerlas en un único instalador preferido.
• Instalaciones con Go: si falta go y brew está disponible, el gateway instala primero Go mediante Homebrew y establece GOBIN en el bin de Homebrew cuando es posible.
• Instalaciones con descarga: url (obligatorio), archive (tar.gz | tar.bz2 | zip), extract (predeterminado: automático cuando se detecta un archivo), stripComponents, targetDir (predeterminado: ~/.openclaw/tools/<skillKey>).

​

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

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

• enabled: false deshabilita la Skill aunque esté incluida/instalada.
• env: se inyecta solo si la variable todavía no está establecida en el proceso.
• apiKey: comodidad 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 claves personalizadas deben vivir aquí.
• allowBundled: allowlist opcional solo para Skills incluidas. Si se establece, solo las Skills incluidas de la lista son aptas (las Skills gestionadas/del workspace no se ven afectadas).

​

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

1. Lee los metadatos de la Skill.
2. Aplica cualquier skills.entries.<key>.env o skills.entries.<key>.apiKey a process.env.
3. Construye el prompt del sistema con las Skills aptas.
4. Restaura el entorno original cuando termina la ejecución.

​

Instantánea de sesión (rendimiento)

​

Nodos remotos de macOS (Gateway en Linux)

​

Watcher de Skills (actualización automática)

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

​

Impacto en tokens (lista de Skills)

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

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

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

​

Ciclo de vida de las Skills gestionadas

​

Referencia de configuración

​

¿Buscas más Skills?

​

Relacionado

• Creating Skills — crear Skills personalizadas
• Skills Config — referencia de configuración de Skills
• Slash Commands — todos los slash commands disponibles
• Plugins — descripción general del sistema de plugins