Agentes Personalizados

Aprende a crear agentes personalizados especializados en tareas específicas de tu dominio.

Requisito: Debes entender la arquitectura de agentes antes de crear los tuyos.

¿Qué es un Agente Personalizado?

Un agente personalizado es una IA especializada con:

• Rol específico - Función bien definida
• Prompt personalizado - Comportamiento adaptado
• Tools especializadas - Herramientas específicas
• Skills integradas - Conocimiento de dominio

🎯 Rol Definido

El agente tiene un propósito claro y delimitado.

📝 Prompt Personalizado

Comportamiento y estilo adaptado a la tarea.

🔧 Tools Especializadas

Herramientas específicas para su función.

📚 Skills Integradas

Conocimiento de dominio incorporado.

Estructura de un Agente

.claude/agents/
└── my-custom-agent/
    ├── config.json           # Configuración del agente
    ├── prompt.md             # System prompt
    ├── tools/                # Herramientas disponibles
    │   ├── tool1.js
    │   └── tool2.py
    └── skills/               # Skills que puede usar
        └── skill-list.txt

Archivo config.json

El archivo de configuración define el comportamiento del agente:

{
  "name": "my-custom-agent",
  "displayName": "My Custom Agent",
  "description": "Descripción de qué hace este agente",
  "version": "1.0.0",
  "role": "Descripción del rol del agente",
  "capabilities": [
    "capability1",
    "capability2",
    "capability3"
  ],
  "tools": [
    "tool1",
    "tool2"
  ],
  "skills": [
    "skill1",
    "skill2"
  ],
  "settings": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "temperature": 0.1,
    "maxTokens": 200000,
    "contextLimit": 100000
  },
  "triggers": [
    "pattern1",
    "pattern2"
  ]
}

Campos de config.json

Campo	Tipo	Descripción
name	string	ID único del agente (kebab-case)
displayName	string	Nombre para mostrar
description	string	Descripción breve
version	string	Versión del agente
role	string	Rol principal del agente
capabilities	array[]	Capacidades del agente
tools	array[]	Tools que puede usar
skills	array[]	Skills que puede usar
settings	object	Configuración del modelo
triggers	array[]	Patrones que activan el agente

Archivo prompt.md

El system prompt define el comportamiento del agente:

# My Custom Agent

Eres un agente especializado en [dominio].

## Tu Rol

[Descripción detallada del rol]

## Tus Capacidades

- [Capacidad 1]
- [Capacidad 2]
- [Capacidad 3]

## Principios

1. **Principio 1** - Descripción
2. **Principio 2** - Descripción
3. **Principio 3** - Descripción

## Workflow

1. [Paso 1]
2. [Paso 2]
3. [Paso 3]

## Output Esperado

[Descripción del formato de output]

## Limitaciones

- [Limitación 1]
- [Limitación 2]

## Examples

### Example 1: [Título]

**Input:**

[Input de ejemplo]

**Output:**

[Output de ejemplo]

Crear un Agente: Paso a Paso

Paso 1: Definir el Propósito

Ejemplo: Database Architect

Propósito: Diseñar schemas de bases de datos optimizados

Rol:

• Diseñar schemas normalizados
• Optimizar queries lentas
• Planear estrategias de índices
• Crear migraciones seguras

Capacidades:

• Schema design
• Query optimization
• Index strategy
• Migration planning

Skills:

• databases
• postgresql-expert
• sql-optimizer

Ejemplo: UI/UX Reviewer

Propósito: Revisar interfaces desde perspectiva UX

Rol:

• Evaluar usabilidad
• Identificar problemas de accesibilidad
• Sugerir mejoras de UX
• Verificar consistencia visual

Capacidades:

• Usability testing
• Accessibility audit
• UX recommendations
• Visual consistency check

Skills:

• ui-ux-pro-max
• web-design-guidelines
• accessibility

Paso 2: Crear Estructura

# Crear directorio del agente
mkdir -p .claude/agents/my-agent/{tools,skills}

# Crear archivos de configuración
touch .claude/agents/my-agent/config.json
touch .claude/agents/my-agent/prompt.md

Paso 3: Escribir config.json

{
  "name": "database-architect",
  "displayName": "Database Architect",
  "description": "Experto en diseño de schemas y optimización de bases de datos",
  "version": "1.0.0",
  "role": "Diseña schemas de bases de datos optimizados y seguros",
  "capabilities": [
    "schema-design",
    "query-optimization",
    "index-strategy",
    "migration-planning"
  ],
  "tools": [
    "sql-executor",
    "schema-validator",
    "query-analyzer"
  ],
  "skills": [
    "databases",
    "postgresql-expert",
    "sql-optimizer"
  ],
  "settings": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "temperature": 0.1,
    "maxTokens": 200000,
    "contextLimit": 100000
  },
  "triggers": [
    "database",
    "schema",
    "query optimization",
    "sql",
    "postgresql",
    "mysql"
  ]
}

Paso 4: Escribir prompt.md

# Database Architect Agent

Eres un experto en bases de datos con 15 años de experiencia en diseño y optimización de schemas.

## Tu Rol

Diseñas bases de datos optimizadas, seguras y escalables. Tu enfoque prioritario es:

1. **Normalización** - 3NF por defecto, denormalizar solo con razón justificada
2. **Performance** - Índices solo cuando benefician queries reales
3. **Migraciones** - Siempre backwards compatible
4. **Seguridad** - Nunca exponer datos sensibles

## Tus Capacidades

- **Schema Design** - Diseñar ERDs normalizados
- **Query Optimization** - Analizar y mejorar queries lentas
- **Index Strategy** - Planear índices efectivos
- **Migration Planning** - Crear migraciones seguras

## Principios

### 1. Normalización con Propósito

```sql
-- ✅ BIEN - 3NF con foreign keys
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  total DECIMAL(10,2),
  created_at TIMESTAMP DEFAULT NOW()
);

-- ❌ MAL - Datos duplicados
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  user_name VARCHAR(100), -- Duplicado de users table
  user_email VARCHAR(100), -- Duplicado de users table
  total DECIMAL(10,2)
);

2. Índices Estratégicos

-- ✅ BIEN - Índice en columnas frecuentemente consultadas
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_created_at ON orders(created_at);

-- ❌ MAL - Índice en columna de baja cardinalidad
CREATE INDEX idx_orders_status ON orders(status); -- Solo 3 valores

3. Migraciones Seguras

-- ✅ BIEN - Backwards compatible
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT true;

-- ❌ MAL - Breaking change
ALTER TABLE users ALTER COLUMN email SET NOT NULL; -- Falla si hay NULLs existentes

Workflow

1. Analizar Requisitos - Entender el dominio y casos de uso
2. Diseñar Schema - Crear ERD normalizado
3. Optimizar Queries - Identificar queries críticas
4. Planear Índices - Agregar índices estratégicos
5. Crear Migraciones - Escribir SQL backwards compatible
6. Documentar Decisiones - Explicar trade-offs

Output Esperado

Tus respuestas deben incluir:

1. ERD Diagram - Representación visual del schema
2. SQL Schema - CREATE TABLE statements completos
3. Índices - CREATE INDEX statements con justificación
4. Migraciones - ALTER statements backwards compatible
5. Documentación - Explicación de decisiones técnicas

Limitaciones

• No sugerir particionamiento sin analizar volumen de datos
• No recomendar NoSQL sin justificación clara
• No usar triggers (lógica en aplicación)
• No usar stored procedures (lógica en aplicación)

Examples

Example 1: E-commerce Schema

Input:

Necesito una base de datos para un e-commerce con usuarios, productos, y órdenes.

Output:

-- Users table
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Products table
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  price DECIMAL(10,2) NOT NULL,
  stock INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Orders table
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  total DECIMAL(10,2) NOT NULL,
  status VARCHAR(50) DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT NOW()
);

-- Order items (junction table)
CREATE TABLE order_items (
  id SERIAL PRIMARY KEY,
  order_id INTEGER REFERENCES orders(id),
  product_id INTEGER REFERENCES products(id),
  quantity INTEGER NOT NULL,
  price DECIMAL(10,2) NOT NULL
);

-- Índices
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_order_items_order_id ON order_items(order_id);
CREATE INDEX idx_order_items_product_id ON order_items(product_id);

Documentación:

• Schema normalizado a 3NF
• Junction table para relationship many-to-many
• Índices en foreign keys para performance
• Precios en order_items para historial

### Example 2: Query Optimization

**Input:**

Esta query es lenta: SELECT * FROM orders o JOIN users u ON o.user_id = u.id WHERE o.created_at > ‘2024-01-01’

**Output:**
```sql
-- Query optimizada:
SELECT o.id, o.total, o.status, u.email
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.created_at > '2024-01-01';

-- Índice recomendado:
CREATE INDEX idx_orders_created_at ON orders(created_at);

-- Explicación:
1. Eliminar SELECT * - Solo seleccionar columnas necesarias
2. Agregar índice en created_at - Filtra por fecha
3. Índice ya existe en user_id (FK) - JOIN optimizado

### Paso 5: Crear Tools (Opcional)

Las tools extienden las capacidades del agente:

**`tools/sql-executor.js`**
```javascript
#!/usr/bin/env node

/**
 * SQL Executor Tool
 * Ejecuta queries SQL y retorna resultados
 */

const { Pool } = require('pg');

async function executeSQL(query, connectionString) {
  const pool = new Pool({ connectionString });

  try {
    const result = await pool.query(query);
    return {
      success: true,
      rows: result.rows,
      rowCount: result.rowCount
    };
  } catch (error) {
    return {
      success: false,
      error: error.message
    };
  } finally {
    await pool.end();
  }
}

// CLI interface
if (require.main === module) {
  const query = process.argv[2];
  const connString = process.env.DATABASE_URL;

  if (!query) {
    console.error('Usage: node sql-executor.js "<query>"');
    process.exit(1);
  }

  executeSQL(query, connString)
    .then(result => console.log(JSON.stringify(result, null, 2)))
    .catch(err => {
      console.error('Error:', err);
      process.exit(1);
    });
}

module.exports = { executeSQL };

Paso 6: Definir Skills

skills/skill-list.txt

databases
postgresql-expert
sql-optimizer
schema-validator

Paso 7: Probar el Agente

# Verificar que el agente está disponible
claude ask "¿Qué agentes están disponibles?"

# Usar el agente
claude cook "Diseñar schema para e-commerce usando database-architect"

Ejemplos de Agentes Personalizados

1. API Documentation Agent

{
  "name": "api-documenter",
  "displayName": "API Documentation Agent",
  "description": "Genera y mantiene documentación de APIs",
  "role": "Crear documentación clara y precisa de endpoints REST",
  "capabilities": [
    "endpoint-documentation",
    "schema-generation",
    "example-creation",
    "openapi-spec"
  ],
  "skills": [
    "openapi-generator",
    "api-docs-formatter"
  ]
}

2. Security Auditor Agent

{
  "name": "security-auditor",
  "displayName": "Security Auditor Agent",
  "description": "Revisa código en busca de vulnerabilidades",
  "role": "Identificar y recomendar fixes para vulnerabilidades de seguridad",
  "capabilities": [
    "vulnerability-scan",
    "dependency-check",
    "code-review-security",
    "owasp-top-10"
  ],
  "skills": [
    "security-scanner",
    "owasp-checker",
    "dependency-auditor"
  ]
}

3. Performance Optimizer Agent

{
  "name": "performance-optimizer",
  "displayName": "Performance Optimizer Agent",
  "description": "Optimiza código para mejorar rendimiento",
  "role": "Analizar y mejorar performance de aplicaciones",
  "capabilities": [
    "code-profiling",
    "bottleneck-identification",
    "optimization-recommendations",
    "benchmarking"
  ],
  "skills": [
    "profiler",
    "performance-analyzer",
    "benchmark-tool"
  ]
}

Best Practices

1. Rol Claro y Delimitado

// ✅ BIEN - Rol específico
{
  "role": "Diseñar schemas de bases de datos PostgreSQL"
}

// ❌ MAL - Rol muy general
{
  "role": "Ayudar con bases de datos"
}

2. Capacidades Medibles

// ✅ BIEN - Capacidades específicas
{
  "capabilities": [
    "design-postgresql-schema",
    "optimize-slow-queries",
    "create-safe-migrations"
  ]
}

// ❌ MAL - Capacidades vagas
{
  "capabilities": [
    "database-stuff",
    "help-with-queries",
    "make-things-faster"
  ]
}

3. Prompts con Examples

## Examples

### Example 1: User Authentication Schema

**Input:**

Schema para autenticación de usuarios

**Output:**
```sql
CREATE TABLE users (...);
-- Con justificación de cada decisión

### 4. Documentar Decisiones

El agente debe explicar por qué toma ciertas decisiones:

```markdown
## Por qué este enfoque

1. **Índice en user_id**: Esta columna se usa en JOINs frecuentes
2. **VARCHAR(255)**: Longitud suficiente para emails RFC-compliant
3. **DEFAULT NOW()**: Automatiza timestamp de creación

5. Manejo de Errores

## Cuando No Puedo Ayudar

Si requieres información que no tengo:
- Te preguntaré específicamente qué necesito
- No inventaré datos o asunciones
- Sugeriré cómo obtener la información

Debugging de Agentes

El agente no responde correctamente

# Verificar config.json
cat .claude/agents/my-agent/config.json | jq .

# Verificar prompt.md
head -n 50 .claude/agents/my-agent/prompt.md

# Probar manualmente
claude ask "Test prompt usando my-agent"

Output no cumple expectativas

1. Revisar prompt.md - ¿Las instrucciones son claras?
2. Agregar examples - ¿Los examples cubren el caso?
3. Ajustar temperature - ¿Demasiado aleatorio?
4. Verificar contextLimit - ¿Contexto suficiente?

El agente se activa incorrectamente

// Ajustar triggers en config.json
{
  "triggers": [
    "exact phrase to match",
    "another specific pattern"
  ]
}

Compartir tu Agente

Opción 1: Repositorio Interno

# Agregar a git
git add .claude/agents/my-agent/
git commit -m "Add my-agent"

# Documentar en README.md
echo "## my-agent" >> .claude/README.md
echo "Descripción del agente" >> .claude/README.md

Opción 2: Publicar como Paquete

# Crear repo
gh repo create my-claudekit-agent --public

# Documentar instalación
cat > README.md << EOF
# My ClaudeKit Agent

## Installation

\`\`\`bash
mkdir -p .claude/agents/my-agent
cp -r * .claude/agents/my-agent/
\`\`\`

## Usage

\`\`\`bash
claude cook "Task using my-agent"
\`\`\`
EOF

Siguiente: Workflows Complejos

Aprende patrones avanzados de orquestación y ejecución paralela.

---

¿Preguntas? Usa claude ask "tu pregunta sobre agentes" en cualquier momento.