agents_and_robots/.claude/rules/create_skill.md

Regla: Crear nueva skill

Guia para crear una nueva skill en skills/.

Prerequisitos

• Entender la diferencia entre tools (funciones atomicas) y skills (flujos multi-paso)
• Las skills son contenido declarativo (markdown + recursos), no codigo Go
• Una skill combina tools existentes, logica condicional y conocimiento de dominio

Proceso

1. Determinar categoria

Elegir la categoria adecuada:

• devops/ — operaciones y deploy
• analysis/ — analisis de datos/logs
• communication/ — comunicacion y notificaciones
• coding/ — desarrollo y code review
• system/ — administracion del sistema

Si ninguna aplica, crear nueva categoria.

2. Crear estructura de directorios

mkdir -p skills/<categoria>/<skill-name>/{scripts,references,templates,assets}

Solo crear las subcarpetas que vayas a usar.

3. Escribir SKILL.md

Template:

---
name: skill-name
description: >
  Descripcion clara de que hace la skill y cuando debe activarse.
  Esta descripcion es el mecanismo principal de triggering.
  Idealmente < 100 palabras.
---

# <Nombre Descriptivo>

Breve introduccion de la skill (1-2 parrafos).

## Casos de uso

- Caso 1
- Caso 2
- Caso 3

## Proceso de ejecucion

### 1. Paso inicial

Descripcion del paso, que tools usar, ejemplos de codigo.

```bash
# ejemplo de comando
ssh_command host="prod-01" command="systemctl status myapp"

2. Paso siguiente

Continuar con los pasos...

Parametros requeridos

Lista de parametros que el usuario debe proporcionar:

• param1: descripcion
• param2: descripcion

Parametros opcionales:

• opt1: descripcion (default: valor)

Ejemplo de uso

Usuario: "Haz X"

Agente:

1. skill_search("X")
2. skill_load("")
3. Ejecutar pasos...
4. Reportar resultado

Seguridad

Consideraciones de seguridad especificas para esta skill.

### 4. Anadir recursos (opcional)

#### Scripts (`scripts/`)

Scripts ejecutables que la skill puede invocar:

```bash
#!/bin/bash
# scripts/deploy.sh
# Descripcion del script

set -euo pipefail

# Validar argumentos
if [ $# -lt 1 ]; then
  echo "Usage: $0 <service-name>"
  exit 1
fi

# Implementacion...

Importante:

• Usar shebang correcto (#!/bin/bash, #!/usr/bin/env python3, etc.)
• Validar argumentos
• Usar set -euo pipefail en bash
• Exit codes claros (0 = exito, != 0 = error)

Referencias (references/)

Documentacion extensa que el agente puede consultar bajo demanda:

# API Reference

Documentacion detallada...

Si > 300 lineas, agregar TOC al inicio.

Templates (templates/)

Plantillas que la skill usa como base:

# template-report.md
# Report: {{title}}

Generated: {{timestamp}}

## Summary
{{summary}}

...

5. Probar la skill

1. Habilitar skills en el config de un agente de prueba:

skills:
  enabled: true
  path: "skills/"
  categories: ["<categoria>"]

tools:
  skills:
    allowed_interpreters: ["bash", "sh"]

2. Reiniciar el agente
3. Probar buscando la skill: skill_search("<query>")
4. Cargar la skill: skill_load("<skill-name>")
5. Ejecutar el flujo completo siguiendo las instrucciones

6. Documentar

Actualizar skills/README.md si:

• Creas una nueva categoria
• La skill introduce un patron nuevo
• Hay consideraciones de seguridad especiales

Reglas criticas

• Skills != Tools: Las skills usan tools, no son tools
• SKILL.md < 500 lineas: Si es mas largo, dividir en multiple skills o mover contenido a references/
• Description precisa: La description en el frontmatter es critica para el matching
• Idempotencia: Las skills deben ser seguras de ejecutar multiples veces si es posible
• Error handling: Las instrucciones deben incluir que hacer en caso de error
• Rollback: Si la skill hace cambios destructivos, incluir instrucciones de rollback

Ejemplos de skills validas

Ver las skills existentes en skills/:

• skills/devops/deploy-service/ — deploy completo con rollback
• skills/analysis/log-analyzer/ — analisis de logs con metricas
• skills/system/health-check/ — verificacion de salud multi-servicio
• skills/communication/daily-report/ — generacion de reportes

Anti-patrones

• Skill que solo ejecuta un comando SSH → usar tool ssh_command directamente
• Skill con logica de negocio compleja → crear tool Go con tests
• Skill que repite instrucciones del system prompt → innecesario
• Scripts que requieren interaccion humana → las skills son automaticas