docs: documentar sistema de skills

Documentar sistema de skills en .claude/:

CLAUDE.md:
- Agregar pkg/skills/, shell/skills/, tools/skilltools/ y skills/ a estructura
- skills/ como contenido declarativo (SKILL.md + recursos)

.claude/rules/create_skill.md:
- Guia completa para crear nuevas skills
- Template de SKILL.md con frontmatter
- Proceso paso a paso (categoria → estructura → SKILL.md → recursos → tests)
- Reglas criticas: skills != tools, < 500 lineas, idempotencia
- Ejemplos y anti-patrones

.claude/rules/index.md:
- Agregar regla "Crear skill" al indice
- Explicar cuando usar skills vs tools

La regla create_skill.md es la guia oficial para añadir skills.

.claude/CLAUDE.md

@@ -48,16 +48,20 @@ pkg/decision/          motor de reglas puro
 pkg/llm/               tipos LLM puros
 pkg/message/           parse/format mensajes
 pkg/personality/       tipos de personalidad
+pkg/skills/            tipos puros de skills + matching
 shell/llm/             clientes LLM (anthropic, openai)
 shell/matrix/          cliente Matrix (mautrix-go)
 shell/ssh/             ejecutor SSH
 shell/mcp/             cliente y servidor MCP (Model Context Protocol)
+shell/skills/          loader (filesystem) + executor (scripts)
 shell/effects/         Runner: []Action → side effects
 shell/bus/             comunicacion inter-agente
 agents/runtime.go      Agent{}: ensambla core + shell
 agents/<id>/           agent.go (reglas puras) + config.yaml + prompts/system.md
 tools/                 tool registry + tool implementations (subpackages)
 tools/mcptools/        bridge: convierte MCP tools → tools.Tool
+tools/skilltools/      tools para interactuar con skills (search, load, run)
+skills/                contenido declarativo: SKILL.md + recursos (scripts, references, templates)
 internal/config/       schema.go + loader.go
 security/              grupos de usuarios/agentes + politicas de permisos (YAMLs)
 cmd/launcher/          entrypoint principal (rulesRegistry)

.claude/rules/create_skill.md

@@ -0,0 +1,199 @@
+# 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

.claude/rules/index.md

@@ -9,6 +9,7 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co
 | **Crear agente** | [create_agent.md](create_agent.md) | Al crear un nuevo bot/agente Matrix completo |
 | **Crear herramienta** | [create_tool.md](create_tool.md) | Al añadir una nueva tool para LLM function calling |
 | **Crear comando** | [create_command.md](create_command.md) | Al añadir un comando directo (!xxx) a un agente |
+| **Crear skill** | [create_skill.md](create_skill.md) | Al crear una nueva skill (flujo multi-paso declarativo) |
 | **Crear issue** | [create_issue.md](create_issue.md) | Al crear un nuevo issue/feature request en `dev/issues/` |
 | **Arreglar issue** | [fix_issue.md](fix_issue.md) | Al implementar/arreglar un issue existente de `dev/issues/` |
 
@@ -17,6 +18,7 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co
 - **Crear agente**: cuando el usuario pida crear un nuevo bot, agente, o asistente. Incluye la estructura de archivos, reglas puras, config YAML, system prompt y registro en el launcher.
 - **Crear herramienta**: cuando el usuario pida añadir una nueva herramienta/tool al sistema. Incluye el patron Def (puro) + Exec (impuro), registro en runtime.go y habilitacion en config.
 - **Crear comando**: cuando el usuario pida añadir un comando directo (!xxx) a un agente. Los comandos se resuelven sin pasar por reglas ni LLM.
+- **Crear skill**: cuando el usuario pida añadir una skill (flujo multi-paso declarativo). Las skills combinan tools, logica condicional y conocimiento de dominio en un SKILL.md con recursos opcionales.
 - **Crear issue**: cuando el usuario pida crear un nuevo issue, feature request o task. Usa el template en `.claude/templates/issue.md`.
 - **Arreglar issue**: cuando el usuario pida implementar, arreglar o trabajar en un issue existente. Incluye crear rama (`/git-branch`), implementar las tareas con tests, cerrar el issue, e integrar a master (`/git-push`).