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

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

Solo crear las subcarpetas que vayas a usar.

### 3. Escribir SKILL.md

Template:

```markdown
---
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("<skill-name>")
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:

```markdown
# API Reference

Documentacion detallada...

Si > 300 lineas, agregar TOC al inicio.
```

#### Templates (`templates/`)

Plantillas que la skill usa como base:

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

Generated: {{timestamp}}

## Summary
{{summary}}

...
```

### 5. Probar la skill

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

```yaml
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