From 439d42f082ba256fd052faa522edb41e7f330172 Mon Sep 17 00:00:00 2001
From: Egutierrez <egutierrez@dead.dd>
Date: Tue, 24 Mar 2026 22:59:34 +0100
Subject: [PATCH] feat: crear skill create-agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Skill para generar nuevos agentes especializados siguiendo la estructura oficial.

Características:
- Validación de nombre y convenciones
- Configuración guiada (model, tools, MCP servers)
- Soporte para repositorios locales en ~/.local_agentes/
- Generación de SKILL.md con frontmatter YAML + documentación
- Templates para MCP servers (gitea, sqlite, filesystem)
- Integración automática con git-push

Estructura generada:
- .claude/agents/nombre/SKILL.md
- ~/.local_agentes/nombre/ (opcional)
- README.md en carpeta local

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/skills/create-agent/SKILL.md | 439 +++++++++++++++++++++++++++
 1 file changed, 439 insertions(+)
 create mode 100644 .claude/skills/create-agent/SKILL.md

diff --git a/.claude/skills/create-agent/SKILL.md b/.claude/skills/create-agent/SKILL.md
new file mode 100644
index 0000000..87f62e0
--- /dev/null
+++ b/.claude/skills/create-agent/SKILL.md
@@ -0,0 +1,439 @@
+---
+name: create-agent
+description: Crea un nuevo agente especializado en .claude/agents/ con su SKILL.md y estructura completa
+argument-hint: [nombre]
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# create-agent
+
+Crea un nuevo agente especializado en `.claude/agents/` con archivo `SKILL.md` obligatorio siguiendo la estructura oficial de Claude Code.
+
+## Sintaxis
+
+```bash
+/create-agent [nombre]
+/create-agent api-client
+/create-agent cloud-deploy
+```
+
+## Precondiciones
+
+- [ ] Carpeta `.claude/agents/` existe
+- [ ] No existe agente con el mismo nombre
+- [ ] Nombre cumple convenciones (minúsculas, guiones)
+
+## Flujo
+
+### 1. Validar nombre
+
+- Solo minúsculas, números y guiones
+- No nombres reservados (help, clear, exit)
+- Máximo 64 caracteres
+
+```bash
+ls -d .claude/agents/*/ 2>/dev/null | xargs -n1 basename | grep -E "^${nombre}$"
+```
+
+Si existe, STOP.
+
+### 2. Solicitar inputs usando AskUserQuestion
+
+Usar `AskUserQuestion` para obtener:
+
+#### Input 1: Información básica
+- **nombre**: minúsculas y guiones (ej: `api-client`)
+- **descripcion**: qué hace el agente y cuándo invocarlo (1-2 frases claras)
+
+#### Input 2: Configuración técnica
+- **model**: Modelo Claude a usar
+  - `sonnet` (default): Balance costo/capacidad
+  - `opus`: Tareas complejas que requieren máximo razonamiento
+  - `haiku`: Tareas simples y rápidas
+
+- **tools**: Herramientas necesarias (separadas por coma)
+  - Default: `Read, Write, Bash, Glob, Grep, Edit`
+  - Opcionales: `WebFetch, WebSearch, NotebookEdit`
+
+#### Input 3: Configuración de proyecto
+- **gestiona_repo**: ¿Gestiona un repositorio local?
+  - `si`: Crear carpeta en `~/.local_agentes/`
+  - `no`: Solo definición de agente
+
+- **usa_mcp**: ¿Usa MCP servers? (gitea, sqlite, etc)
+  - `si`: Solicitar configuración de MCP
+  - `no`: Omitir mcpServers
+
+#### Input 4: MCP Servers (si usa_mcp = si)
+Preguntar qué MCP servers necesita:
+- `gitea`: Gestión de repositorios Gitea
+- `sqlite`: Bases de datos SQLite
+- `filesystem`: Sistema de archivos
+- `otro`: Configuración personalizada
+
+#### Input 5: Documentación
+- **rol**: Rol del agente (ej: "Eres un experto en...")
+- **capacidades**: Lista de capacidades principales
+- **flujo_trabajo**: Descripción del flujo de trabajo típico
+- **ejemplos_uso**: Ejemplos de cuándo invocar al agente
+
+### 3. Crear carpeta del agente
+
+```bash
+mkdir -p .claude/agents/${nombre}
+```
+
+### 4. Crear carpeta local (si gestiona_repo = si)
+
+```bash
+mkdir -p ~/.local_agentes/${nombre}
+```
+
+### 5. Generar frontmatter YAML
+
+Estructura base:
+```yaml
+---
+name: ${nombre}
+description: ${descripcion}
+model: ${model}
+tools: ${tools}
+mcpServers:  # Solo si usa_mcp = si
+  - ${mcp_config}
+---
+```
+
+### 6. Generar SKILL.md completo
+
+Template oficial de agente:
+
+```markdown
+---
+name: ${nombre}
+description: ${descripcion}
+model: ${model}
+tools: ${tools}
+${mcp_servers_section}
+---
+
+# Agente ${nombre}
+
+${rol}
+
+## Tu entorno
+
+${descripcion_entorno}
+
+## Capacidades principales
+
+${capacidades}
+
+## Flujo de trabajo
+
+${flujo_trabajo}
+
+## Templates disponibles
+
+${templates_codigo}
+
+## Integración con otros agentes
+
+${integracion}
+
+## Ejemplos de uso
+
+${ejemplos_uso}
+
+## Comandos útiles
+
+${comandos}
+
+## Notas y convenciones
+
+${notas}
+```
+
+### 7. Templates de MCP Servers
+
+#### Gitea MCP
+```yaml
+mcpServers:
+  - gitea:
+      type: stdio
+      command: gitea-mcp
+      args:
+        - -t
+        - stdio
+        - --host
+        - "${GITEA_URL}"
+        - --token
+        - "${GITEA_TOKEN}"
+```
+
+#### SQLite MCP
+```yaml
+mcpServers:
+  - sqlite:
+      type: stdio
+      command: sqlite-mcp
+      args:
+        - --db
+        - "${DB_PATH}"
+```
+
+#### Filesystem MCP
+```yaml
+mcpServers:
+  - filesystem:
+      type: stdio
+      command: mcp-server-filesystem
+      args:
+        - --allowed-directories
+        - "${ALLOWED_DIR}"
+```
+
+### 8. Mostrar y confirmar
+
+```
+Agente creado: ${nombre}
+Ubicación: .claude/agents/${nombre}/SKILL.md
+${carpeta_local ? "Carpeta local: ~/.local_agentes/" + nombre : ""}
+
+Configuración:
+- Model: ${model}
+- Tools: ${tools}
+- MCP: ${usa_mcp ? "Sí" : "No"}
+- Repositorio local: ${gestiona_repo ? "Sí" : "No"}
+
+¿Te parece bien?
+- Si correcto: commit e integrar automáticamente
+- Si ajustes: edita manualmente antes de integrar
+```
+
+### 9. Crear README.md en carpeta local (si gestiona_repo = si)
+
+```bash
+cat > ~/.local_agentes/${nombre}/README.md <<EOF
+# ${nombre}
+
+${descripcion}
+
+## Estructura del proyecto
+
+\`\`\`
+~/.local_agentes/${nombre}/
+├── README.md
+├── CLAUDE.md           # Instrucciones para Claude
+└── ...                 # Archivos del proyecto
+\`\`\`
+
+## Sincronización con Gitea
+
+\`\`\`bash
+cd ~/.local_agentes/${nombre}
+git remote add origin \${GITEA_URL}/\${user}/${nombre}.git
+git push -u origin main
+\`\`\`
+
+## Uso
+
+Invocar con:
+\`\`\`
+Hablar con el agente ${nombre} para [tarea]
+\`\`\`
+EOF
+```
+
+### 10. Ejecutar /git-push
+
+Si confirma, crear rama `quick/create-agent-${nombre}` e integrar.
+
+### 11. Verificar disponibilidad
+
+```
+Agente "${nombre}" creado e integrado
+
+El agente está disponible en:
+  .claude/agents/${nombre}/SKILL.md
+
+${gestiona_repo ? "Carpeta de trabajo:\n  ~/.local_agentes/" + nombre : ""}
+
+Para usar, solicita al usuario:
+  "Trabajar con el agente ${nombre} para [tarea]"
+
+Configuración:
+- Model: ${model}
+- Tools: ${tools}
+- MCP Servers: ${usa_mcp ? "Sí" : "No"}
+```
+
+## Campos del frontmatter de agentes
+
+| Campo | Descripción | Requerido |
+|-------|-------------|-----------|
+| name | Nombre del agente | Sí |
+| description | Qué hace y cuándo invocarlo | Sí |
+| model | Model Claude (sonnet, opus, haiku) | Sí |
+| tools | Herramientas disponibles | Sí |
+| mcpServers | Servidores MCP (opcional) | No |
+
+## Estructura de documentación de agentes
+
+Seguir este orden en el contenido Markdown:
+
+1. **Título y rol**: Descripción del rol del agente
+2. **Tu entorno**: Dónde trabaja, qué repositorios gestiona
+3. **Capacidades principales**: Lista de lo que puede hacer
+4. **Flujo de trabajo**: Cómo abordar tareas típicas
+5. **Templates disponibles**: Código de ejemplo
+6. **Integración con otros agentes**: Cómo colabora con otros
+7. **Ejemplos de uso**: Cuándo invocar al agente
+8. **Comandos útiles**: Comandos CLI relevantes
+9. **Notas y convenciones**: Reglas y mejores prácticas
+
+## Convenciones
+
+- Nombres descriptivos con guiones (ej: `api-client`, `cloud-deploy`)
+- Descripciones claras para invocación automática por Claude
+- Un agente por dominio/especialización
+- Documentación completa con ejemplos prácticos
+- Templates de código cuando sea aplicable
+
+## Diferencia entre Agentes y Skills
+
+| Característica | Agente | Skill |
+|----------------|--------|-------|
+| Ubicación | `.claude/agents/` | `.claude/skills/` |
+| Propósito | Experto especializado | Automatización/herramienta |
+| Invocación | Claude decide cuándo | Usuario con `/nombre` |
+| Contenido | Conocimiento de dominio | Flujo de trabajo |
+| Ejemplo | `backend-lib`, `docker` | `git-push`, `create-issue` |
+
+## Ejemplos de agentes
+
+### Agente simple (sin repo ni MCP)
+```yaml
+---
+name: code-review
+description: Agente para revisar código y sugerir mejoras
+model: sonnet
+tools: Read, Grep, Glob
+---
+
+# Agente Code Review
+
+Eres un experto en revisión de código...
+```
+
+### Agente complejo (con repo y MCP)
+```yaml
+---
+name: api-client
+description: Agente para generar clientes API desde especificaciones OpenAPI
+model: sonnet
+tools: Read, Write, Bash, Glob, Grep, Edit
+mcpServers:
+  - gitea:
+      type: stdio
+      command: gitea-mcp
+      args:
+        - -t
+        - stdio
+        - --host
+        - "${GITEA_URL}"
+        - --token
+        - "${GITEA_TOKEN}"
+---
+
+# Agente API Client
+
+Eres un experto en generación de clientes API...
+
+## Tu entorno
+
+- **Repositorio**: `Bl4cksmith/api-clients` (Gitea)
+- **Carpeta local**: `~/.local_agentes/api-client`
+- **Stack**: TypeScript, Go, Python
+
+...
+```
+
+## Reglas
+
+- Validar nombre antes de crear
+- SKILL.md es obligatorio
+- Confirmación antes de integrar
+- Crear carpeta local solo si gestiona_repo = si
+- MCP servers solo si usa_mcp = si
+- Documentación completa y con ejemplos
+
+## Integración con otros agentes
+
+### Con gitea
+```bash
+# Crear repositorio para el agente (si gestiona_repo = si)
+cd ~/.local_agentes/${nombre}
+git init
+git add .
+git commit -m "Initial commit"
+# Usar agente gitea para crear repo y push
+```
+
+### Con backend-lib / frontend-lib
+```markdown
+# En SKILL.md del nuevo agente, documentar integración:
+
+## Integración con otros agentes
+
+### Con backend-lib (DevFactory)
+- Usar DevFactory para estructuras funcionales Go
+- Integrar via go.work
+
+### Con frontend-lib
+- Usar Frontend_Library para componentes React
+- Integrar via pnpm link
+```
+
+## Variables dinámicas
+
+| Variable | Descripción |
+|----------|-------------|
+| ${nombre} | Nombre del agente |
+| ${descripcion} | Descripción del agente |
+| ${model} | Model Claude |
+| ${tools} | Herramientas disponibles |
+| ${CLAUDE_SKILL_DIR} | Ruta del skill |
+
+## Flujo completo de ejemplo
+
+```bash
+# Usuario invoca
+/create-agent api-client
+
+# Skill valida nombre
+✓ Nombre válido
+
+# Skill pregunta configuración con AskUserQuestion
+? Descripción: Agente para generar clientes API desde OpenAPI
+? Model: sonnet
+? Tools: Read, Write, Bash, Glob, Grep, Edit
+? ¿Gestiona repositorio?: Sí
+? ¿Usa MCP?: Sí
+? MCP servers: gitea
+
+# Skill crea estructura
+✓ Carpeta creada: .claude/agents/api-client/
+✓ Carpeta local creada: ~/.local_agentes/api-client/
+✓ SKILL.md generado
+✓ README.md generado
+
+# Skill confirma
+Agente "api-client" creado
+
+# Skill integra con git
+✓ Rama: quick/create-agent-api-client
+✓ Commit: "feat: crear agente api-client"
+✓ Push exitoso
+```