Habilidades

Las skills son instrucciones reutilizables y definiciones opcionales de herramientas que ZeroClaw puede cargar en una sesión de agente. Úsalas para flujos de trabajo repetibles, como listas de verificación para revisión de código, runbooks de despliegue, guías de soporte o wrappers de herramientas específicos de un dominio.

Las habilidades residen en una de tres ubicaciones:

• Habilidades del espacio de trabajo por agente en <install>/agents/<alias>/workspace/skills/<name>/.
• Paquetes de habilidades compartidos en <install>/shared/skills/<bundle>/<name>/. Los agentes los cargan cuando su configuración incluye el paquete en agents.<alias>.skill_bundles.
• El directorio global de habilidades está en <install>/data/skills/<name>/. La CLI puede instalarlas allí como alternativa, pero los agentes no cargan las habilidades globales automáticamente.

Usa paquetes para las habilidades que un agente debe cargar durante la ejecución. Un paquete se configura bajo [skill_bundles.<alias>]; cuando se omite su directory, ZeroClaw lo resuelve a <install>/shared/skills/<alias>/.

<install>/shared/skills/<bundle>/<name>/

Para skills locales escritas manualmente, usa SKILL.md o SKILL.toml. Usa SKILL.md para instrucciones junto con metadatos simples. Usa SKILL.toml cuando la skill necesite prompts estructurados o definiciones de herramientas. ZeroClaw también admite manifest.toml para paquetes de skills al estilo de registro, pero SKILL.md y SKILL.toml son los formatos de creación local recomendados.

Para distribuir un conjunto de skills como un paquete firmado, versionado e instalable, consulta Skill bundles. Ten en cuenta que estos utilizan el sistema de plugins, que los binarios de versiones precompiladas no incluyen; en un binario estándar, los bundles compartidos de esta página son el mecanismo compatible.

Crear una skill de Markdown

Crea un bundle, luego genera un skill de solo instrucciones en él:

zeroclaw skills bundle add ops
zeroclaw skills add release-check \
  --bundle ops \
  --description "Check release readiness before tagging" \
  --edit

El comando skills add escribe SKILL.md en el directorio del paquete resuelto y lo abre en tu editor. Reemplaza las instrucciones generadas con el flujo de trabajo que quieres que siga el agente:

# Release check

Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

El nombre del directorio se convierte en el nombre de la skill. ZeroClaw usa el primer párrafo que no sea un encabezado como descripción cuando no hay una descripción en el frontmatter.

SKILL.md también admite frontmatter simple para metadatos:

---
name: release-check
description: Check release readiness before tagging
version: 0.1.0
author: zeroclaw_user
tags: [release, docs]
---

# Release check

Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

Los campos de frontmatter admitidos son name, description, author, version, tags, always y slash_options.

Establecer always: true mantiene las instrucciones completas de una skill insertadas en el prompt del sistema incluso cuando el agente se ejecuta en modo compacto de prompts de skills (en el que las demás skills se resumen y sus instrucciones se cargan a petición mediante read_skill). Su valor predeterminado es false. Resérvalo para skills relacionadas con políticas o críticas para la seguridad que deban estar siempre visibles para el modelo, no para skills de flujos de trabajo rutinarios como la comprobación de la versión mencionada arriba:

---
name: security-policy
description: Non-negotiable safety rules the agent must follow every turn.
version: 0.1.0
author: zeroclaw_user
tags: [policy]
always: true
---

# Security policy

Never exfiltrate secrets, never disable audit logging, and always ask for approval before touching production credentials.

Crear una skill de TOML

Una habilidad también puede ser un manifiesto TOML estructurado (SKILL.toml). La tabla [skill] requiere name y description; version tiene el valor predeterminado 0.1.0 cuando se omite; author, tags, prompts y always son opcionales (always tiene el valor predeterminado false; consulta lo anterior). Las entradas de herramientas pueden usar kind = "shell", kind = "http" o kind = "script". Mantén las descripciones de las herramientas acotadas y concretas para que el modelo sepa cuándo usarlas.

Las herramientas de la habilidad HTTP solo usan URL http y https. Los argumentos se codifican porcentualmente antes de insertarse, las redirecciones y los proxies del entorno están deshabilitados, y el destino resuelto debe cumplir la política de salida de red pública de ZeroClaw. Los destinos privados o de metadatos se rechazan, y los cuerpos de respuesta de más de un megabyte se truncan antes de que puedan ampliar la memoria en tiempo de ejecución.

Opciones de comandos slash y localizaciones

Una habilidad etiquetada como slash se muestra como un comando slash en un canal de chat (p. ej., Discord /search). Puede declarar [[skill.slash_options]] tipadas; una habilidad que no declare ninguna recurre a una única entrada de texto libre obligatoria. Tanto la descripción del comando como la descripción de cada opción aceptan un mapa opcional description_localizations indexado por código de idioma. Los códigos de idioma desconocidos o no admitidos se omiten con una advertencia en lugar de hacer que falle el registro, de modo que un error tipográfico nunca bloquee el registro del comando.

[skill]
name = "search"
description = "Buscar en la web"
tags = ["slash"]
# Descripciones localizadas del comando, indexadas por código de locale.
description_localizations = { fr = "Rechercher sur le web", ja = "ウェブを検索" }

[[skill.slash_options]]
name = "query"
description = "La consulta de búsqueda"
type = "string"
required = true
# Descripciones localizadas de la opción, con el mismo formato.
description_localizations = { fr = "La requête de recherche" }

Gestionar habilidades instaladas

Enumera el inventario completo:

zeroclaw skills list

Enumera exactamente lo que carga un agente en tiempo de ejecución:

zeroclaw skills list --agent default

Enumera un bundle directamente:

zeroclaw skills list --bundle ops

Audita una skill instalada o un directorio de skill local:

zeroclaw skills audit release-check
zeroclaw skills audit ./release-check

Instala una habilidad desde un directorio local, una URL de Git o un nombre del registro:

zeroclaw skills install ./release-check --bundle ops
zeroclaw skills install https://example.com/zeroclaw-release-check.git --bundle ops
zeroclaw skills install release-check --agent default

Instala una skill por su nombre desde un repositorio de catálogo Git (un repositorio cuyas skills se encuentran en skills/<name>/):

zeroclaw skills install https://github.com/vercel-labs/skills --skill find-skills

La precedencia del destino de instalación es:

1. Explícito --bundle <alias>.
2. El único paquete asignado del agente de destino. --agent <alias> elige el agente de destino; cuando se omite, ZeroClaw usa el agente de ejecución activo.
3. El directorio global bajo <install>/data/skills/.

Si el agente de destino tiene varios bundles, pasa --bundle para que el destino no sea ambiguo. Si ZeroClaw recurre al directorio global, la habilidad se instala y se lista, pero ningún agente la carga automáticamente. Adjúntala a un bundle para que esté disponible en tiempo de ejecución.

Eliminar una skill instalada:

zeroclaw skills remove release-check --bundle ops
zeroclaw skills remove release-check --agent default

Al eliminar de un bundle, se archiva el directorio de la skill para que pueda recuperarse. Al eliminar del directorio global, se borra la copia global después de que pasen las comprobaciones existentes de contención de rutas.

Ejecuta la validación de TEST.sh para una skill, u omite el nombre para probar todas las skills instaladas:

zeroclaw skills test release-check
zeroclaw skills test --verbose

zeroclaw skills test ejecuta el archivo TEST.sh de la skill cuando existe. Inspecciona TEST.sh antes de ejecutar pruebas de un origen de skill en el que aún no confías.

Si zeroclaw skills list muestra una habilidad, pero el agente no la usa, revisa la vista en tiempo de ejecución:

zeroclaw skills list --agent default

Cuando la habilidad aparezca solo en el grupo global, instálala en un bundle y asegúrate de que el agente enumere ese bundle en agents.<alias>.skill_bundles.

Para un ejemplo práctico que convierte una herramienta integrada en un flujo de trabajo de operador reutilizable, consulta using relationship memory from skills.

Sugerencias de funcionalidades activadas por prompts

ZeroClaw puede sugerir opcionalmente una capacidad de skill instalable cuando un prompt enviado nombra claramente algo que existe en los metadatos de registro en caché pero que no está instalado. La ruta del lado del servidor se ejecuta después del envío y antes del turno normal del LLM. Solo devuelve una sugerencia; no instala el skill, no lo habilita, no escribe en memoria ni trata el cuerpo del skill como instrucciones globales.

Habilítalo mediante la configuración skills (gateway, zerocode o zeroclaw config set). El comparador de sugerencias utiliza los nombres de las skills instaladas y los metadatos del registro en caché, como nombres, alias y frontmatter. Evita intencionadamente hacer coincidencias con los cuerpos de skills no aprobadas. El descubrimiento a nivel de plugin/paquete sigue siendo un trabajo pendiente hasta que esté disponible la interfaz de búsqueda/instalación del registro de plugins. Las sugerencias exactas en tiempo de composición, mientras el usuario aún está escribiendo, requieren compatibilidad con ACP, gateway o la interfaz de usuario del cliente, y quedan fuera de esta ruta exclusiva del servidor.

Seguridad de scripts

ZeroClaw audita las skills antes de cargarlas o instalarlas. Los archivos similares a scripts como .sh, .bash, .ps1 y los archivos con shebangs de shell se bloquean de forma predeterminada.

Si usa intencionalmente skills que contienen scripts, habilite skills.allow_scripts. Mantenga esto deshabilitado a menos que confíe en la fuente del skill y haya revisado lo que hacen los scripts.

Para conocer los patrones de ejecución específicos de Python, la política del intérprete y las ventajas e inconvenientes entre la ejecución nativa y Docker, consulta Running Python skills.

Cargando habilidades de la comunidad

La carga de open-skills de la comunidad es opcional y se activa mediante la configuración skills. Cuando está habilitada, ZeroClaw carga las skills desde el open_skills_dir configurado, o desde $HOME/open-skills cuando no se ha establecido ningún directorio. Si ese directorio no existe, ZeroClaw puede clonar el repositorio de open-skills de la comunidad; si existe y es un checkout de git, ZeroClaw puede descargar actualizaciones. Habilite esto solo para fuentes de la comunidad en las que confíe, o apunte open_skills_dir a una copia local revisada.

Configuración avanzada

El modo predeterminado de inyección de prompts es full, que incluye las instrucciones completas de las habilidades en el prompt del sistema. Establece prompt_injection_mode = "compact" globalmente o en un perfil de ejecución para mantener los metadatos habituales de las habilidades en el contexto y cargar las instrucciones según sea necesario mediante read_skill. Las habilidades marcadas con always: true conservan sus instrucciones completas en el modo compacto. El modo compacto reduce el tamaño del prompt; no es un límite de aislamiento para fuentes de habilidades no confiables.

Creación autónoma de habilidades

Después de una tarea multietapa exitosa (al menos dos llamadas a herramientas), ZeroClaw puede persistir la ejecución como una habilidad reutilizable. Esto está desactivado de forma predeterminada y requiere activación explícita:

[skills.skill_creation]
enabled = true              # off by default
max_skills = 500            # LRU cap: oldest auto-generated skill is evicted past this
similarity_threshold = 0.85 # embedding-dedup cutoff; near-duplicate tasks are skipped

De forma predeterminada, cada skill creada es un SKILL.toml determinista generado directamente a partir de la traza de llamadas a herramientas; no interviene ninguna llamada al modelo.

Reflection (SKILL.md síntesis)

Con la reflexión habilitada, ZeroClaw en su lugar pide al proveedor de modelo configurado del agente que sintetice un SKILL.md canónico a partir de un fragmento acotado de la ejecución (la tarea, el rastro de llamadas a herramientas y la respuesta final). Cada entrada se trunca de forma independiente a un presupuesto de caracteres configurado, de modo que una ejecución grande nunca pueda producir una solicitud de reflexión no acotada:

[skills.skill_creation]
enabled = true
reflection_enabled = true   # opt-in; requires enabled = true
max_task_chars = 1000           # task description budget
max_tool_trace_chars = 4000     # tool-call trace budget
max_final_answer_chars = 2000   # final assistant answer budget

Si la llamada de reflexión falla (error del proveedor, salida malformada o un cuerpo vacío), ZeroClaw recurre a la ruta determinista de SKILL.toml, de modo que habilitar la reflexión nunca deja una habilidad sin crear. Las habilidades reflejadas se marcan con el autor zeroclaw-auto y participan en la misma deduplicación y expulsión LRU que las habilidades de SKILL.toml.

Debido a que reflection reenvía el contenido del turno al proveedor del modelo, la tarea, el registro de llamadas a herramientas y la respuesta final se analizan para detectar valores con forma de credencial (claves de API, tokens, credenciales de AWS, claves privadas PEM, JWT, URL de conexión a bases de datos y secretos de alta entropía) y se redactan antes de que se componga y envíe el prompt, utilizando la misma protección de contenido saliente que ZeroClaw aplica a las respuestas del canal. La redacción se ejecuta en el proceso antes de la solicitud, de modo que un secreto que aparezca en un argumento de herramienta o en la respuesta final se sustituye por un marcador [REDACTED_…] en lugar de llegar al proveedor.

Reflexión vs. mejora de habilidades. La reflexión ([skills.skill_creation] reflection_enabled) crea una nueva habilidad a partir de una traza de ejecución completada. El fork de revisión en segundo plano de [skills.skill_improvement] es una función separada que aplica parches a habilidades existentes después de que se usan. Se pueden habilitar de forma independiente.

Ver también

• Resumen de herramientas
• [Usando la memoria de relaciones de skills]
• Descripción general de seguridad
• Recibos de herramientas