manuelmauro/arkouda

Usar Skilo

Skilo es una herramienta CLI para desarrollar Habilidades de Agente.

Instalación

curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh

Inicio Rápido

skilo new my-skill        # Crear desde plantilla
skilo add owner/repo      # Instalar desde git
skilo lint .              # Validar contra la especificación
skilo fmt .               # Formatear archivos SKILL.md

Ejecuta skilo -h para ver todos los comandos y opciones.

SIEMPRE Validar Habilidades

Ejecuta skilo lint y skilo fmt antes de confirmar cualquier cambio en una habilidad. Estos comandos aplican la Especificación de Habilidades de Agente y detectan problemas comunes.

# Validar y formatear en un solo comando
skilo check .

# Modo estricto para CI (las advertencias se convierten en errores)
skilo check --strict .

Estructura de la Habilidad

my-skill/
├── SKILL.md        # Obligatorio: manifiesto con frontmatter YAML
├── scripts/        # Opcional: código ejecutable
├── references/     # Opcional: documentación adicional (cargada bajo demanda)
└── assets/         # Opcional: recursos estáticos

Requisitos del Frontmatter

Campos Obligatorios

name (1-64 caracteres)

• Solo minúsculas alfanuméricas y guiones (a-z, 0-9, -)
• NO debe comenzar/terminar con - ni contener --
• Debe coincidir con el nombre del directorio padre

description (1-1024 caracteres)

• Describe QUÉ hace la habilidad Y CUÁNDO usarla
• Incluye palabras clave que ayuden a los agentes a emparejar solicitudes de usuario

Campos Opcionales

• license - Manténlo breve, referencia el archivo LICENSE para detalles
• compatibility (máx. 500 caracteres) - Requisitos de entorno (ej. Requiere git, docker)
• metadata - Pares clave-valor para propiedades personalizadas
• allowed-tools - Lista de herramientas preaprobadas separadas por espacios (experimental)

Buenas Prácticas

Escribir Descripciones Efectivas

La descripción es cómo los agentes deciden cuándo activar tu habilidad. Sé específico.

# Buena: específica, rica en palabras clave
description: Extrae texto y tablas de archivos PDF, rellena formularios PDF y fusiona múltiples PDFs. Úsalo al trabajar con documentos PDF o cuando el usuario mencione PDFs, formularios o extracción de documentos.

# Mala: vaga, sin señales de activación
description: Ayuda con PDFs.

Mantener el Contenido del Cuerpo Conciso

Todo el cuerpo del SKILL.md se carga cuando la habilidad se activa. Mantenlo por debajo de 500 líneas.

• Incluye instrucciones paso a paso
• Añade ejemplos de entradas y salidas
• Cubre casos límite comunes
• Mueve material detallado a references/

Usar Divulgación Progresiva

Estructura las habilidades para minimizar el uso de contexto:

1. Metadatos (~100 tokens) - name + description cargados al inicio para todas las habilidades
2. Instrucciones (<5000 tokens) - Cuerpo completo cargado cuando la habilidad se activa
3. Recursos (bajo demanda) - scripts/, references/, assets/ cargados solo cuando se necesitan

Escribir Scripts Autónomos

Los scripts en scripts/ deben:

• Ser autónomos o documentar claramente las dependencias
• Incluir mensajes de error útiles
• Manejar casos límite de forma elegante

Organizar Referencias Efectivamente

Los archivos en references/ se cargan bajo demanda:

• Mantén los archivos enfocados (un archivo = un concepto)
• Usa rutas relativas desde la raíz de la habilidad
• Evita cadenas de referencias profundamente anidadas

Reglas de Lint

Skilo aplica estas reglas (configurables en .skilorc.toml):

Código	Regla	Por Defecto
E001	name_format	habilitado
E002	name_length	64 caracteres
E003	name_directory	habilitado
E004	description_required	habilitado
E005	description_length	1024 caracteres
E006	compatibility_length	500 caracteres
E009	references_exist	habilitado
W001	body_length	500 líneas
W002	script_executable	habilitado
W003	script_shebang	habilitado

Integración con CI

- name: Validar habilidades
  run: |
    curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh
    skilo check --strict skills/