Evolucionar un Agente Existente

Mejora, extiende o crea una variante avanzada de un agente que fue creado originalmente con

create-agent

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

name

description

tools

model

version

author

tags

version

priority

skills

# Leer el archivo del agente
cat agents/<agent-name>.md

# Verificar que el frontmatter se analiza
head -20 agents/<agent-name>.md

# Verificar las habilidades en el frontmatter existen en el registro
grep "skills:" -A 20 agents/<agent-name>.md

# Comprobar si algún equipo referencia este agente
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

Paso 2: Reunir los Requisitos de Evolución

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

analyze-api-security

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:

<agent>-advanced

<agent>-<specialty>

.md

agents/

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

# Copiar el original como punto de partida
cp agents/<agent-name>.md agents/<agent-name>-advanced.md

# Editar la variante:
# - Cambiar `name` a `<agent-name>-advanced`
# - Actualizar `description` para reflejar el alcance avanzado
# - Aumentar `model` si es necesario (p.ej., sonnet → opus)
# - Restablecer `version` a "1.0.0"
# - Expandir habilidades, capacidades y ejemplos para el caso de uso avanzado
# - Referenciar el original en Ver También como alternativa más simple

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

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:

# Comprobar las traducciones existentes
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

npm run translation:status

En caso de fallo: Si

sed

source_commit

npm run translate:scaffold -- agents

Paso 5: Actualizar la Versión y los Metadatos

Incrementar el campo

version

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

updated

"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

# Encontrar la entrada del registro del agente
grep -A 10 "id: <agent-name>" agents/_registry.yml

Actualizar los campos

description

tags

tools

skills

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

# Comprobar si algún equipo referencia este agente
grep -r "<agent-name>" teams/*.md

# Comprobar si alguna guía referencia este agente
grep -r "<agent-name>" guides/*.md

Para Variantes

Añadir el nuevo agente a

agents/_registry.yml

  - 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

En caso de fallo: Contar entradas con

grep -c "^  - id:" agents/_registry.yml

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

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

# Comprobar que las habilidades existen
for skill in skill-a skill-b; do
  grep "id: $skill" skills/_registry.yml
done

# Contar agentes en disco vs registro
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml

# Revisar todos los cambios
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

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