# Sistema de Skills

Sistema de skills reutilizables para agentes Matrix. Las skills son paquetes de instrucciones, scripts y recursos que amplian las capacidades de un agente mas alla de las tools de function calling.

## Diferencia entre Tools y Skills

- **Tools** (`tools/`) — funciones atomicas que el LLM invoca via function calling (ssh_command, http_get, clock, etc.)
- **Skills** (`skills/`) — flujos completos de trabajo multi-paso que combinan tools, logica condicional y conocimiento de dominio

Ejemplo:
- Tool: `ssh_command` — ejecuta un comando SSH
- Skill: `deploy-service` — usa ssh_command, http_get y logica para hacer un deploy completo

## Estructura de una skill

```
skills/<categoria>/<skill-name>/
├── SKILL.md              ← obligatorio (frontmatter YAML + instrucciones markdown)
├── LICENSE.txt            ← opcional
├── scripts/              ← opcional, codigo ejecutable (bash, python, etc.)
├── references/           ← opcional, docs de referencia
├── templates/            ← opcional, plantillas/assets
└── assets/               ← opcional, fuentes, iconos, etc.
```

### SKILL.md — formato

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

# Instrucciones

Cuerpo markdown con las instrucciones completas.
Idealmente < 500 lineas.
```

## Carga progresiva (3 niveles)

El sistema carga skills de forma progresiva para optimizar el uso del contexto del LLM:

1. **Metadata** (name + description) — siempre en contexto (~100 palabras). El agente la lee para decidir si activar la skill.
2. **Cuerpo del SKILL.md** — se carga cuando la skill se activa. Instrucciones principales.
3. **Recursos bundled** (scripts/, references/, etc.) — se cargan bajo demanda. El SKILL.md indica cuando leer cada archivo.

## Carpetas opcionales

| Carpeta | Proposito |
|---------|-----------|
| `scripts/` | Codigo ejecutable que el agente corre (bash, python). Puede ejecutarlos sin cargarlos en contexto. |
| `references/` | Documentacion extensa, leida solo cuando es relevante. Si > 300 lineas, agregar TOC al inicio. |
| `templates/` | Plantillas que la skill usa como base para generar outputs. |
| `assets/` | Archivos estaticos (fuentes, iconos, imagenes). |

## Categorias de skills

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

## Uso desde agentes

Los agentes pueden interactuar con skills via function calling:

1. **`skill_search`** — busca skills relevantes por query
2. **`skill_load`** — carga instrucciones completas de una skill
3. **`skill_read_resource`** — lee un recurso especifico (script, reference, template)
4. **`skill_run_script`** — ejecuta un script de la skill con argumentos

## Configuracion

Las skills se configuran por agente en el YAML de configuracion:

```yaml
skills:
  enabled: true
  path: "skills/"
  categories: ["devops", "system"]  # filtro opcional
```

## Seguridad

- Los scripts de skills tienen las mismas restricciones que ssh_command
- Allowlist de interpreters permitidos (bash, python3, sh)
- Timeout obligatorio en ejecucion
- Sin acceso directo a secretos

## Crear nuevas skills

Ver `.claude/rules/create_skill.md` para la guia completa de creacion de skills.