Desarrollo Básico de Skills: Sintaxis y Estructura

Esta lección aborda la sintaxis y estructura fundamentales para desarrollar Skills en OpenClaw. Aprenderá a construir un Skill funcional, entendiendo los componentes clave y cómo interactúan para su correcta ejecución. El enfoque es práctico, preparando para la creación de automatizaciones robustas.

Anatomía de un Skill: Archivo SKILL.md

Un Skill en OpenClaw se define principalmente en un archivo SKILL.md. Este archivo utiliza una variante de Markdown enriquecida con bloques de código y directivas específicas para la orquestación de tareas. La estructura es declarativa, lo que facilita la lectura y el mantenimiento. El motor de OpenClaw interpreta este archivo para determinar las acciones a ejecutar, los parámetros requeridos y las respuestas esperadas.

El archivo SKILL.md no es solo documentación; es el código ejecutable del Skill. Su formato permite integrar lógica de negocio, llamadas a herramientas externas y la definición de la interfaz de usuario o de API. La claridad en su escritura impacta directamente en la capacidad de depuración y escalabilidad del Skill.

Componentes Estructurales Básicos

Todo Skill.md debe incluir secciones bien definidas para su correcta operación. Estos son los bloques mínimos que un desarrollador debe considerar:

• Metadatos (Front Matter): Bloque YAML al inicio del archivo que define propiedades como el nombre del Skill, descripción, versión, autor y los parámetros de entrada esperados. Es crucial para el descubrimiento y la invocación del Skill.
• Descripción del Skill: Texto en Markdown que explica el propósito del Skill, sus capacidades y cómo usarlo. Es la interfaz humana del Skill.
• Definición de Herramientas: Bloques de código que declaran las herramientas externas (scripts, APIs, comandos CLI) que el Skill puede invocar. Se especifica el tipo de herramienta, su nombre y, opcionalmente, su configuración.
• Lógica de Ejecución: La secuencia de pasos que el Skill seguirá. Puede incluir condicionales, bucles y llamadas a las herramientas definidas. Aquí es donde reside la inteligencia del Skill.
• Respuestas y Salidas: Cómo el Skill comunica sus resultados al usuario o al sistema que lo invocó. Puede ser texto, JSON, o referencias a archivos generados.

Sintaxis de Metadatos y Parámetros

Los metadatos se definen usando un bloque YAML delimitado por --- al inicio del archivo. Aquí se especifican los parámetros de entrada que el Skill espera recibir. Cada parámetro debe tener un nombre, un tipo de dato y, opcionalmente, una descripción y un valor por defecto.

---
name: "ConsultarEstadoServicio"
description: "Consulta el estado actual de un servicio específico en la infraestructura."
version: "1.0.0"
author: "EquipoINT"
parameters:
  - name: "nombre_servicio"
    type: "string"
    description: "Nombre del servicio a consultar (e.g., 'Firewall_DMZ', 'VPN_Sucursal')."
    required: true
  - name: "formato_salida"
    type: "enum"
    description: "Formato deseado para la salida (texto o JSON)."
    enum: ["texto", "json"]
    default: "texto"
---

# Consulta de Estado de Servicio

Este Skill permite obtener el estado operativo de un servicio dado. Utiliza herramientas internas para verificar la disponibilidad y el rendimiento.

En este ejemplo, nombre_servicio es un parámetro obligatorio de tipo cadena, mientras que formato_salida es opcional, con valores predefinidos y un valor por defecto. La correcta definición de estos parámetros es fundamental para la validación de entrada y la experiencia del usuario al invocar el Skill.

Definición de Herramientas y Lógica de Ejecución

Las herramientas se declaran en bloques de código específicos. Por ejemplo, para ejecutar un script de Python o un comando de shell, se utiliza la directiva tool.

```tool
name: "obtener_estado_script"
type: "python_script"
path: "./scripts/get_service_status.py"
```

```tool
name: "ejecutar_comando_cli"
type: "shell_command"
command: "ssh user@host 'systemctl status {{params.nombre_servicio}}'"
```

La lógica de ejecución se construye secuencialmente, invocando estas herramientas y procesando sus salidas. Se pueden usar variables para pasar datos entre pasos y condicionales para controlar el flujo.

## Lógica de Ejecución

1.  **Validar servicio:**
    Si `params.nombre_servicio` está vacío:
        Retornar "Error: El nombre del servicio no puede estar vacío."

2.  **Consultar estado:**
    Ejecutar `obtener_estado_script` con `service_name=params.nombre_servicio`.
    Guardar resultado en `estado_raw`.

3.  **Formatear salida:**
    Si `params.formato_salida` es "json":
        Convertir `estado_raw` a JSON y retornar.
    Sino:
        Retornar `estado_raw` como texto.

Aplicación Práctica: Tu Primer Skill Funcional

Para el lunes, crea un archivo mi_primer_skill.md con la siguiente estructura. Este Skill debe aceptar un parámetro nombre_usuario y usar una herramienta ficticia para "saludar" al usuario. No es necesario que la herramienta exista; solo la declaración y la invocación.

1. Define los metadatos: name, description, version, author.
2. Declara un parámetro nombre_usuario de tipo string y marcado como required: true.
3. Crea una sección de descripción que explique el propósito del Skill.
4. Define una herramienta de tipo shell_command llamada saludar_usuario. Su command debe ser echo 'Hola, {{params.nombre_usuario}} desde OpenClaw.'.
5. En la lógica de ejecución, invoca la herramienta saludar_usuario y retorna su salida. Incluye una validación simple: si nombre_usuario está vacío, retorna un mensaje de error.

Este ejercicio te familiarizará con la creación de un Skill completo, desde los metadatos hasta la lógica de ejecución y la respuesta. Guarda el archivo en un directorio local y prepárate para la siguiente lección, donde exploraremos cómo ejecutarlo y gestionar sus permisos.