---
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
```