Evolve Agent

Evolucionar un Agente Existente

Mejora, extiende o crea una variante avanzada de un agente que fue creado originalmente con create-agent. Este procedimiento cubre el lado de mantenimiento del ciclo de vida del agente: evaluar brechas frente a las mejores prácticas, aplicar mejoras específicas a la definición de la persona, actualizar versiones y mantener sincronizados el registro y las referencias cruzadas.

Cuándo Usar

• La lista de habilidades de un agente está desactualizada tras añadir nuevas habilidades a la biblioteca
• Los comentarios de usuarios revelan capacidades faltantes, propósito poco claro o ejemplos débiles
• Los requisitos de herramientas han cambiado (nuevo servidor MCP, herramienta eliminada, reducción de privilegios necesaria)
• El alcance de un agente necesita ajuste — se superpone con otro agente o es demasiado amplio
• Se necesita una variante avanzada junto a la original (p.ej., r-developer y r-developer-advanced)
• Se añadieron agentes o equipos relacionados y las referencias cruzadas en Ver También están obsoletas

Entradas

• Requerido: Ruta al archivo de agente existente que se va a evolucionar (p.ej., agents/r-developer.md)
• Requerido: Disparador de evolución (comentario, nuevas habilidades, cambio de herramienta, solapamiento de alcance, integración en equipo, limitaciones descubiertas)
• Opcional: Magnitud objetivo del incremento de versión (parche, menor, mayor)
• Opcional: Si crear una variante avanzada en lugar de refinar en el lugar (por defecto: refinar en el lugar)

Procedimiento

Paso 1: Evaluar el Agente Actual

Leer el archivo de agente existente y evaluar cada sección frente a la lista de verificación de calidad de guides/agent-best-practices.md:

# Read the agent file
cat agents/<agent-name>.md

# Check frontmatter parses
head -20 agents/<agent-name>.md

# Verify skills in frontmatter exist in registry
grep "skills:" -A 20 agents/<agent-name>.md

# Check if agent is referenced by any team
grep -r "<agent-name>" teams/*.md

Esperado: Una lista de brechas específicas, debilidades u oportunidades de mejora organizadas por sección.

En caso de fallo: Si el archivo del agente no existe o no tiene frontmatter, esta habilidad no aplica — usar create-agent en su lugar para crearlo desde cero.

Paso 2: Reunir los Requisitos de Evolución

Identificar y categorizar qué desencadenó la evolución:

Documentar los cambios específicos necesarios antes de editar. Listar cada cambio con su sección objetivo:

- Frontmatter: añadir `new-skill-id` a la lista de habilidades
- Capabilities: añadir capacidad "API Security Analysis"
- Available Skills: añadir `new-skill-id` con descripción
- Limitations: eliminar limitación desactualizada sobre habilidad faltante
- See Also: añadir enlace al nuevo equipo que incluye este agente

Esperado: Una lista concreta de cambios, cada uno mapeado a una sección específica del archivo del agente.

En caso de fallo: Si los cambios no están claros, consultar al usuario para aclaración antes de proceder. Los objetivos de evolución vagos producen mejoras vagas.

Paso 3: Elegir el Alcance de la Evolución

Usar esta matriz de decisión para determinar si refinar en el lugar o crear una variante:

Refinamiento: Elegir al actualizar habilidades, corregir documentación, afinar alcance o ajustar herramientas. El agente mantiene su identidad.

Variante: Elegir cuando la versión evolucionada serviría a una audiencia sustancialmente diferente, requeriría un modelo diferente o añadiría capacidades que harían al original demasiado amplio. El original permanece como está para casos de uso más simples.

Esperado: Una decisión clara — refinamiento o variante — con justificación.

En caso de fallo: Si no estás seguro, por defecto optar por refinamiento. Siempre puedes extraer una variante más tarde; es más difícil fusionarla de vuelta.

Paso 4: Aplicar los Cambios al Archivo del Agente

Para Refinamientos

Editar el archivo de agente existente directamente:

• Frontmatter: Actualizar skills, tools, tags, model, priority, mcp_servers según sea necesario
• Purpose/Capabilities: Revisar para reflejar nuevo alcance o funcionalidad añadida
• Available Skills: Añadir nuevas habilidades con descripciones, eliminar las obsoletas
• Usage Scenarios: Añadir o revisar escenarios para demostrar nuevas capacidades
• Limitations: Eliminar restricciones que ya no aplican, añadir nuevas honestas
• See Also: Actualizar referencias cruzadas para reflejar el panorama actual de agente/equipo/guía

Seguir estas reglas de edición:

• Preservar todas las secciones existentes — añadir contenido, no eliminar secciones
• Mantener la sección Available Skills sincronizada con la lista skills del frontmatter
• No añadir habilidades por defecto (meditate, heal) al frontmatter a menos que sean fundamentales para la metodología del agente
• Verificar que cada ID de habilidad existe: grep "id: skill-name" skills/_registry.yml

Para Variantes

# Copy the original as a starting point
cp agents/<agent-name>.md agents/<agent-name>-advanced.md

# Edit the variant:
# - Change `name` to `<agent-name>-advanced`
# - Update `description` to reflect the advanced scope
# - Raise `model` if needed (e.g., sonnet → opus)
# - Reset `version` to "1.0.0"
# - Expand skills, capabilities, and examples for the advanced use case
# - Reference the original in See Also as a simpler alternative

Esperado: El archivo del agente (refinado o nueva variante) pasa la lista de verificación de evaluación del Paso 1.

En caso de fallo: Si una edición rompe la estructura del documento, usar git diff para revisar los cambios y revertir ediciones parciales con git checkout -- <file>.

Paso 4.5: Sincronizar Variantes Traducidas

Obligatorio cuando existen traducciones. Este paso se aplica tanto a autores humanos como a agentes de IA que siguen este procedimiento. No omitir — los valores obsoletos de source_commit hacen que npm run validate:translations informe advertencias falsas de obsolescencia en todas las localizaciones.

Comprobar si existen traducciones para el agente evolucionado y actualizarlas para reflejar el nuevo estado de la fuente:

# Check for existing translations
ls i18n/*/agents/<agent-name>.md 2>/dev/null

Si existen traducciones

1. Obtener el hash del commit de la fuente actual:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. Actualizar source_commit en el frontmatter de cada archivo traducido:

for locale_file in i18n/*/agents/<agent-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. Marcar archivos para re-traducción incluyendo las localizaciones afectadas en el mensaje de commit:

evolve-agent(<agent-name>): <descripción de los cambios>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <lista de secciones que cambiaron>

4. Regenerar los archivos de estado de traducción:

npm run translation:status

Si no existen traducciones

No se requiere ninguna acción. Continuar al Paso 5.

Para Variantes

Aplazar la traducción de nuevas variantes hasta que la variante se estabilice (1-2 versiones). Traducir una variante v1.0 que puede cambiar sustancialmente para v1.2 desperdicia esfuerzo. Añadir traducciones después de que la variante haya sido refinada al menos una vez.

Esperado: Todos los archivos traducidos tienen source_commit actualizado al commit actual. El mensaje de commit indica qué localizaciones necesitan re-traducción y qué secciones cambiaron. npm run translation:status sale con 0.

En caso de fallo: Si sed no coincide con el campo del frontmatter, el archivo traducido puede tener un formato no estándar. Abrirlo manualmente y verificar que tiene source_commit en su frontmatter YAML. Si el campo falta, el archivo no se generó correctamente — regenerar con npm run translate:scaffold -- agents.

Paso 5: Actualizar la Versión y los Metadatos

Incrementar el campo version en el frontmatter siguiendo el versionado semántico:

También actualizar:

• Fecha updated a la fecha actual
• tags si la cobertura de dominio del agente cambió
• description si el propósito es materialmente diferente
• priority si la importancia del agente relativa a otros cambió

Esperado: version y updated del frontmatter reflejan la magnitud y fecha de los cambios. Las nuevas variantes comienzan en "1.0.0".

En caso de fallo: Si olvidas incrementar la versión, la próxima evolución no tendrá forma de distinguir el estado actual del anterior. Siempre incrementar antes de confirmar.

Paso 6: Actualizar el Registro y las Referencias Cruzadas

Para Refinamientos

Actualizar la entrada existente en agents/_registry.yml para que coincida con el frontmatter revisado:

# Find the agent's registry entry
grep -A 10 "id: <agent-name>" agents/_registry.yml

Actualizar los campos description, tags, tools y skills para que coincidan con el archivo del agente. No se necesita cambio de recuento.

Actualizar las referencias cruzadas en otros archivos si las capacidades o nombre del agente cambiaron:

# Check if any team references this agent
grep -r "<agent-name>" teams/*.md

# Check if any guide references this agent
grep -r "<agent-name>" guides/*.md

Para Variantes

Añadir el nuevo agente a agents/_registry.yml en posición alfabética:

  - id: <agent-name>-advanced
    path: agents/<agent-name>-advanced.md
    description: One-line description of the advanced variant
    tags: [domain, specialty, advanced]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two

Luego:

1. Incrementar total_agents al inicio del registro
2. Añadir referencia cruzada Ver También en el agente original apuntando a la variante
3. Añadir referencia cruzada Ver También en la variante apuntando al original
4. El symlink .claude/agents/ a agents/ significa que la variante es automáticamente descubrible

Esperado: La entrada del registro coincide con el frontmatter del archivo del agente. Para variantes, total_agents es igual al número real de entradas de agentes.

En caso de fallo: Contar entradas con grep -c "^ - id:" agents/_registry.yml y verificar que coincide con total_agents.

Paso 7: Validar el Agente Evolucionado

Ejecutar la lista de verificación de validación completa:

• El archivo del agente existe en la ruta esperada
• El frontmatter YAML se analiza sin errores
• version fue incrementada (refinamiento) o establecida en "1.0.0" (variante)
• La fecha updated refleja hoy
• Todas las secciones requeridas presentes: Purpose, Capabilities, Available Skills, Usage Scenarios, Examples, Limitations, See Also
• Las habilidades en el frontmatter coinciden con la sección Available Skills
• Todos los IDs de habilidades existen en skills/_registry.yml
• Las habilidades por defecto (meditate, heal) no están listadas a menos que sean fundamentales para la metodología
• La lista de herramientas sigue el principio de mínimo privilegio
• La entrada del registro existe y coincide con el frontmatter
• Para variantes: el recuento total_agents coincide con el recuento real en disco
• Las referencias cruzadas son bidireccionales (original ↔ variante)
• git diff no muestra eliminaciones accidentales del contenido original

# Verify frontmatter
head -20 agents/<agent-name>.md

# Check skills exist
for skill in skill-a skill-b; do
  grep "id: $skill" skills/_registry.yml
done

# Count agents on disk vs registry
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml

# Review all changes
git diff

Esperado: Todos los elementos de la lista de verificación pasan. El agente evolucionado está listo para confirmar.

En caso de fallo: Abordar cada elemento fallido individualmente. Los problemas más comunes tras la evolución son IDs de habilidades obsoletos en la sección Available Skills y una fecha updated olvidada.

Validación

• El archivo del agente existe y tiene frontmatter YAML válido
• El campo version refleja los cambios realizados
• La fecha updated es actual
• Todas las secciones presentes e internamente consistentes
• El array skills del frontmatter coincide con la sección Available Skills
• Todos los IDs de habilidades existen en skills/_registry.yml
• Las habilidades por defecto no están listadas innecesariamente
• La entrada del registro coincide con el archivo del agente
• Para variantes: nueva entrada en agents/_registry.yml con la ruta correcta
• Para variantes: recuento total_agents actualizado
• Las referencias cruzadas son válidas (sin enlaces rotos en Ver También)
• git diff confirma que no se eliminó contenido accidentalmente

Errores Comunes

• Olvidar incrementar la versión: Sin incrementos de versión, no hay forma de rastrear qué cambió o cuándo. Siempre actualizar version y updated en el frontmatter antes de confirmar.
• Desviación de la lista de habilidades: El array skills del frontmatter y la sección ## Available Skills deben mantenerse sincronizados. Actualizar uno sin el otro crea confusión tanto para humanos como para las herramientas.
• Listar habilidades por defecto innecesariamente: Añadir meditate o heal al frontmatter cuando ya se heredan del registro. Solo listarlas si son fundamentales para la metodología del agente (p.ej., mystic, alchemist).
• Sobreprovisión de herramientas durante la evolución: Añadir Bash o WebFetch durante una evolución "por si acaso". Cada adición de herramienta debe justificarse por una nueva capacidad específica.
• Ver También obsoleto tras la creación de variante: Al crear una variante, tanto el original como la variante necesitan referenciarse mutuamente. Las referencias unidireccionales dejan el grafo incompleto.
• Entrada del registro no actualizada: Tras cambiar las habilidades, herramientas o descripción de un agente, la entrada en agents/_registry.yml debe actualizarse para que coincida. Las entradas de registro obsoletas causan fallos de descubrimiento y de herramientas.

Habilidades Relacionadas

• create-agent — base para la creación de nuevos agentes; evolve-agent asume que esto se siguió originalmente
• evolve-skill — el procedimiento paralelo para evolucionar archivos SKILL.md
• commit-changes — confirmar el agente evolucionado con un mensaje descriptivo