Desarrollo de Agentes para Plugins de Claude Code

¿Qué hace Desarrollo de Agentes para Plugins de Claude Code?

Resumen

Los agentes son subprocesos autónomos que manejan tareas complejas de múltiples pasos de forma independiente. Comprender la estructura del agente, las condiciones de activación y el diseño de prompts del sistema permite crear potentes capacidades autónomas.

Conceptos clave:

• Los agentes son PARA trabajo autónomo, los comandos son PARA acciones iniciadas por el usuario
• Formato de archivo Markdown con frontmatter YAML
• Activación mediante el campo de descripción con ejemplos
• El prompt del sistema define el comportamiento del agente
• Personalización del modelo y color

Estructura del Archivo del Agente

Formato Completo

---
name: identificador-del-agente
description: Usa este agente cuando [condiciones de activación]. Ejemplos:

<example>
Context: [Descripción de la situación]
user: "[Solicitud del usuario]"
assistant: "[Cómo debe responder el asistente y usar este agente]"
<commentary>
[Por qué se debe activar este agente]
</commentary>
</example>

<example>
[Ejemplo adicional...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

Eres [descripción del rol del agente]...

**Tus Responsabilidades Principales:**
1. [Responsabilidad 1]
2. [Responsabilidad 2]

**Proceso de Análisis:**
[Flujo de trabajo paso a paso]

**Formato de Salida:**
[Qué devolver]

Campos del Frontmatter

name (obligatorio)

Identificador del agente utilizado para namespacing e invocación.

Formato: solo minúsculas, números y guiones Longitud: 3-50 caracteres Patrón: Debe comenzar y terminar con carácter alfanumérico

Buenos ejemplos:

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Malos ejemplos:

• helper (demasiado genérico)
• -agent- (comienza/termina con guión)
• my_agent (no se permiten guiones bajos)
• ag (demasiado corto, < 3 caracteres)

description (obligatorio)

Define cuándo Claude debe activar este agente. Este es el campo más crítico.

Debe incluir:

1. Condiciones de activación ("Usa este agente cuando...")
2. Múltiples bloques <example> que muestren el uso
3. Contexto, solicitud del usuario y respuesta del asistente en cada ejemplo
4. <commentary> explicando por qué se activa el agente

Formato:

Usa este agente cuando [condiciones]. Ejemplos:

<example>
Context: [Descripción del escenario]
user: "[Lo que dice el usuario]"
assistant: "[Cómo debe responder Claude]"
<commentary>
[Por qué este agente es apropiado]
</commentary>
</example>

[Más ejemplos...]

Mejores prácticas:

• Incluye 2-4 ejemplos concretos
• Muestra activación proactiva y reactiva
• Cubre diferentes redacciones de la misma intención
• Explica el razonamiento en el comentario
• Sé específico sobre cuándo NO usar el agente

model (obligatorio)

Qué modelo debe usar el agente.

Opciones:

• inherit - Usar el mismo modelo que el padre (recomendado)
• sonnet - Claude Sonnet (equilibrado)
• opus - Claude Opus (más capaz, caro)
• haiku - Claude Haiku (rápido, barato)

Recomendación: Usa inherit a menos que el agente necesite capacidades específicas del modelo.

color (obligatorio)

Identificador visual para el agente en la interfaz de usuario.

Opciones: blue, cyan, green, yellow, magenta, red

Directrices:

• Elige colores distintos para diferentes agentes en el mismo plugin
• Usa colores consistentes para tipos de agentes similares
• Azul/Cian: Análisis, revisión
• Verde: Tareas orientadas al éxito
• Amarillo: Precaución, validación
• Rojo: Crítico, seguridad
• Magenta: Creativo, generación

tools (opcional)

Restringe el agente a herramientas específicas.

Formato: Arreglo de nombres de herramientas

tools: ["Read", "Write", "Grep", "Bash"]

Valor predeterminado: Si se omite, el agente tiene acceso a todas las herramientas

Mejor práctica: Limita las herramientas al mínimo necesario (principio de mínimo privilegio)

Conjuntos de herramientas comunes:

• Análisis solo lectura: ["Read", "Grep", "Glob"]
• Generación de código: ["Read", "Write", "Grep"]
• Pruebas: ["Read", "Bash", "Grep"]
• Acceso completo: Omitir el campo o usar ["*"]

Diseño del Prompt del Sistema

El cuerpo del markdown se convierte en el prompt del sistema del agente. Escribe en segunda persona, dirigiéndote al agente directamente.

Estructura

Plantilla estándar:

Eres [rol] especializado en [dominio].

**Tus Responsabilidades Principales:**
1. [Responsabilidad principal]
2. [Responsabilidad secundaria]
3. [Responsabilidades adicionales...]

**Proceso de Análisis:**
1. [Paso uno]
2. [Paso dos]
3. [Paso tres]
[...]

**Estándares de Calidad:**
- [Estándar 1]
- [Estándar 2]

**Formato de Salida:**
Proporciona los resultados en este formato:
- [Qué incluir]
- [Cómo estructurar]

**Casos Especiales:**
Maneja estas situaciones:
- [Caso especial 1]: [Cómo manejarlo]
- [Caso especial 2]: [Cómo manejarlo]

Mejores Prácticas

✅ SÍ:

• Escribe en segunda persona ("Eres...", "Harás...")
• Sé específico sobre las responsabilidades
• Proporciona un proceso paso a paso
• Define el formato de salida
• Incluye estándares de calidad
• Aborda casos especiales
• Mantén menos de 10,000 caracteres

❌ NO:

• Escribas en primera persona ("Yo soy...", "Haré...")
• Seas vago o genérico
• Omitas pasos del proceso
• Dejes el formato de salida indefinido
• Omitas la guía de calidad
• Ignores los casos de error

Creación de Agentes

Método 1: Generación Asistida por IA

Usa este patrón de prompt (extraído de Claude Code):

Crea una configuración de agente basada en esta solicitud: "[TU DESCRIPCIÓN]"

Requisitos:
1. Extrae la intención central y las responsabilidades
2. Diseña un personaje experto para el dominio
3. Crea un prompt del sistema completo con:
   - Límites de comportamiento claros
   - Metodologías específicas
   - Manejo de casos especiales
   - Formato de salida
4. Crea un identificador (minúsculas, guiones, 3-50 caracteres)
5. Escribe una descripción con condiciones de activación
6. Incluye 2-3 bloques <example> que muestren cuándo usar

Devuelve JSON con:
{
  "identifier": "nombre-del-agente",
  "whenToUse": "Usa este agente cuando... Ejemplos: <example>...</example>",
  "systemPrompt": "Eres..."
}

Luego convierte al formato de archivo de agente con frontmatter.

Consulta examples/agent-creation-prompt.md para la plantilla completa.

Método 2: Creación Manual

1. Elige un identificador para el agente (3-50 caracteres, minúsculas, guiones)
2. Escribe la descripción con ejemplos
3. Selecciona el modelo (normalmente inherit)
4. Elige un color para la identificación visual
5. Define las herramientas (si se restringe el acceso)
6. Escribe el prompt del sistema con la estructura anterior
7. Guarda como agents/nombre-del-agente.md

Reglas de Validación

Validación del Identificador

✅ Válido: code-reviewer, test-gen, api-analyzer-v2
❌ Inválido: ag (demasiado corto), -start (comienza con guión), my_agent (guión bajo)

Reglas:

• 3-50 caracteres
• Solo minúsculas, números y guiones
• Debe comenzar y terminar con carácter alfanumérico
• Sin guiones bajos, espacios ni caracteres especiales

Validación de la Descripción

Longitud: 10-5,000 caracteres Debe incluir: Condiciones de activación y ejemplos Mejor: 200-1,000 caracteres con 2-4 ejemplos

Validación del Prompt del Sistema

Longitud: 20-10,000 caracteres Mejor: 500-3,000 caracteres Estructura: Responsabilidades claras, proceso, formato de salida

Organización de Agentes

Directorio de Agentes del Plugin

nombre-del-plugin/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

Todos los archivos .md en agents/ se descubren automáticamente.

Namespacing

Los agentes tienen namespacing automático:

• Plugin único: nombre-del-agente
• Con subdirectorios: plugin:subdirectorio:nombre-del-agente

Pruebas de Agentes

Probar Activación

Crea escenarios de prueba para verificar que el agente se activa correctamente:

1. Escribe el agente con ejemplos de activación específicos
2. Usa una redacción similar a los ejemplos en la prueba
3. Comprueba que Claude carga el agente
4. Verifica que el agente proporciona la funcionalidad esperada

Probar Prompt del Sistema

Asegúrate de que el prompt del sistema esté completo:

1. Dale al agente una tarea típica
2. Comprueba que sigue los pasos del proceso
3. Verifica que el formato de salida es correcto
4. Prueba los casos especiales mencionados en el prompt
5. Confirma que se cumplen los estándares de calidad

Referencia Rápida

Agente Mínimo

---
name: agente-simple
description: Usa este agente cuando... Ejemplos: <example>...</example>
model: inherit
color: blue
---

Eres un agente que [hace X].

Proceso:
1. [Paso 1]
2. [Paso 2]

Salida: [Qué proporcionar]

Resumen de Campos del Frontmatter

Campo	Obligatorio	Formato	Ejemplo
name	Sí	minúsculas-guiones	code-reviewer
description	Sí	Texto + ejemplos	Usa cuando... ...
model	Sí	inherit/sonnet/opus/haiku	inherit
color	Sí	Nombre del color	blue
tools	No	Arreglo de nombres de herramientas	["Read", "Grep"]

Mejores Prácticas

SÍ:

• ✅ Incluye 2-4 ejemplos concretos en la descripción
• ✅ Escribe condiciones de activación específicas
• ✅ Usa inherit para el modelo a menos que haya una necesidad específica
• ✅ Elige herramientas apropiadas (mínimo privilegio)
• ✅ Escribe prompts del sistema claros y estructurados
• ✅ Prueba la activación del agente a fondo

NO:

• ❌ Uses descripciones genéricas sin ejemplos
• ❌ Omitas las condiciones de activación
• ❌ Des a todos los agentes el mismo color
• ❌ Concedas acceso innecesario a herramientas
• ❌ Escribas prompts del sistema vagos
• ❌ Te saltes las pruebas

Recursos Adicionales

Archivos de Referencia

Para obtener una guía detallada, consulta:

• references/agent-creation-system-prompt.md - El prompt exacto de Claude Code
• references/system-prompt-design.md - Patrones completos de prompts del sistema
• references/triggering-examples.md - Formatos de ejemplo y mejores prácticas

Archivos de Ejemplo

Ejemplos funcionales en examples/:

• agent-creation-prompt.md - Plantilla de generación de agente asistida por IA
• complete-agent-examples.md - Ejemplos completos de agentes para diferentes casos de uso

Scripts de Utilidad

Herramientas de desarrollo en scripts/:

• validate-agent.sh - Validar la estructura del archivo del agente
• test-agent-trigger.sh - Probar si el agente se activa correctamente

Flujo de Trabajo de Implementación

Para crear un agente para un plugin:

1. Define el propósito del agente y las condiciones de activación
2. Elige el método de creación (asistido por IA o manual)
3. Crea el archivo agents/nombre-del-agente.md
4. Escribe el frontmatter con todos los campos obligatorios
5. Escribe el prompt del sistema siguiendo las mejores prácticas
6. Incluye 2-4 ejemplos de activación en la descripción
7. Valida con scripts/validate-agent.sh
8. Prueba la activación con escenarios reales
9. Documenta el agente en el README del plugin

Concéntrate en condiciones de activación claras y prompts del sistema completos para una operación autónoma.