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.
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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
|
||||
@@ -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`).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user