From 4a23468c14df02ec9872fc46dd350d62e93bfabc Mon Sep 17 00:00:00 2001 From: Enmanuel Date: Sun, 8 Mar 2026 22:13:50 +0000 Subject: [PATCH] docs: documentar sistema de skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 4 + .claude/rules/create_skill.md | 199 ++++++++++++++++++++++++++++++++++ .claude/rules/index.md | 2 + 3 files changed, 205 insertions(+) create mode 100644 .claude/rules/create_skill.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 2d4266c..d1efc58 100644 --- a/.claude/CLAUDE.md +++ b/.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// 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) diff --git a/.claude/rules/create_skill.md b/.claude/rules/create_skill.md new file mode 100644 index 0000000..c0d02db --- /dev/null +++ b/.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///{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. +--- + +# + +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 " + 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: [""] + +tools: + skills: + allowed_interpreters: ["bash", "sh"] +``` + +2. Reiniciar el agente +3. Probar buscando la skill: `skill_search("")` +4. Cargar la skill: `skill_load("")` +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 diff --git a/.claude/rules/index.md b/.claude/rules/index.md index 3fdfc41..5ccb58f 100644 --- a/.claude/rules/index.md +++ b/.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`).