Evolucionar una Habilidad Existente

Mejora, extiende o crea una variante avanzada de una habilidad que fue creada originalmente con

create-skill

Cuándo Usar

• Los pasos del procedimiento de una habilidad están desactualizados o incompletos tras cambios en las herramientas
• Los comentarios de usuarios revelan errores faltantes, pasos poco claros o validación débil
• Una habilidad necesita crecer de básica a intermedia (o de intermedia a avanzada)
• Se necesita una variante avanzada junto a la original (p.ej.,

  create-r-package

  y

  create-r-package-advanced

  )
• Se añadieron o eliminaron habilidades relacionadas y las referencias cruzadas están obsoletas

Entradas

• Requerido: Ruta al SKILL.md existente que se va a evolucionar
• Requerido: Disparador de evolución (comentario, cambio de herramienta, actualización de complejidad, nuevas habilidades relacionadas, errores descubiertos)
• Opcional: Nivel de complejidad objetivo si cambia (basic, intermediate, advanced)
• Opcional: Si crear una variante avanzada en lugar de refinar en el lugar (por defecto: refinar en el lugar)

Procedimiento

Paso 1: Evaluar la Habilidad Actual

Leer el SKILL.md existente y evaluar cada sección frente a la lista de verificación de calidad:

description

tags

version

# Leer la habilidad
cat skills/<skill-name>/SKILL.md

# Verificar que el frontmatter se analiza
head -20 skills/<skill-name>/SKILL.md

# Verificar que las habilidades relacionadas aún existen
grep -oP '`[\w-]+`' skills/<skill-name>/SKILL.md | sort -u

Esperado: Una lista de brechas específicas, debilidades u oportunidades de mejora.

En caso de fallo: Si el SKILL.md no existe o no tiene frontmatter, esta habilidad no aplica — usar

create-skill

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.

Esperado: Una lista concreta de cambios (p.ej., "Añadir On failure al Paso 4", "Añadir nuevo Paso 6 para caso extremo X", "Actualizar Related Skills para incluir

new-skill

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:

<skill>-advanced

Refinamiento: Elegir al mejorar la calidad, corregir brechas o añadir contenido nuevo modesto. La habilidad mantiene su identidad.

Variante: Elegir cuando la versión evolucionada duplicaría la longitud, cambiaría el público objetivo o requeriría entradas sustancialmente diferentes. 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 de Contenido

Para Refinamientos

Editar el SKILL.md existente directamente:

# Abrir para edición
# Añadir/revisar pasos del procedimiento
# Fortalecer pares Expected/On failure
# Añadir tablas o ejemplos
# Actualizar los disparadores de When to Use
# Revisar Inputs si el alcance cambió

Seguir estas reglas de edición:

• Preservar todas las secciones existentes — añadir contenido, no eliminar secciones
• Mantener la numeración de pasos secuencial tras las inserciones
• Cada paso nuevo o modificado debe tener tanto Expected como On failure
• Los nuevos errores van al final de la sección Common Pitfalls
• Las nuevas habilidades relacionadas van al final de la sección Related Skills

Para Variantes

# Crear el directorio de variante
mkdir -p skills/<skill-name>-advanced/

# Copiar el original como punto de partida
cp skills/<skill-name>/SKILL.md skills/<skill-name>-advanced/SKILL.md

# Editar la variante:
# - Cambiar `name` a `<skill-name>-advanced`
# - Actualizar `description` para reflejar el alcance avanzado
# - Aumentar `complexity` (p.ej., intermediate → advanced)
# - Restablecer `version` a "1.0"
# - Añadir/expandir pasos del procedimiento para el caso de uso avanzado
# - Referenciar el original en Related Skills como requisito previo

Esperado: El SKILL.md (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 la habilidad evolucionada y actualizarlas para reflejar el nuevo estado de la fuente:

# Comprobar las traducciones existentes
ls i18n/*/skills/<skill-name>/SKILL.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/*/skills/<skill-name>/SKILL.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(<skill-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

Paso 5: Actualizar la Versión y los Metadatos

Incrementar el campo

version

También actualizar:

• complexity

  si el alcance se expandió (p.ej., basic → intermediate)

• tags

  si el área de cobertura cambió

• description

  si el alcance de la habilidad es materialmente diferente

Esperado: El

version

"1.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

No se necesitan cambios en el registro (la ruta no cambia). Actualizar las referencias cruzadas solo si las Habilidades Relacionadas cambiaron en otras habilidades:

# Comprobar si alguna habilidad referencia la habilidad evolucionada
grep -r "<skill-name>" skills/*/SKILL.md

Para Variantes

Añadir la nueva habilidad a

skills/_registry.yml

- id: <skill-name>-advanced
  path: <skill-name>-advanced/SKILL.md
  complexity: advanced
  language: multi
  description: One-line description of the advanced variant

Luego:

1. Incrementar

   total_skills

   al inicio del registro
2. Añadir referencia cruzada de Related Skills en la habilidad original apuntando a la variante
3. Añadir referencia cruzada de Related Skills en la variante apuntando al original
4. Crear symlinks para el descubrimiento de comandos slash:

# A nivel de proyecto
ln -s ../../skills/<skill-name>-advanced .claude/skills/<skill-name>-advanced

# Global
ln -s /mnt/d/dev/p/agent-almanac/skills/<skill-name>-advanced ~/.claude/skills/<skill-name>-advanced

Esperado: El

total_skills

find skills -name SKILL.md | wc -l

En caso de fallo: Si el recuento del registro es incorrecto, ejecutar

find skills -name SKILL.md | wc -l

readlink -f

Paso 7: Validar la Habilidad Evolucionada

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

• SKILL.md existe en la ruta esperada
• El frontmatter YAML se analiza sin errores

• version

  fue incrementada (refinamiento) o establecida en "1.0" (variante)
• Todas las secciones presentes: When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills
• Cada paso del procedimiento tiene bloques Expected y On failure
• Las Habilidades Relacionadas hacen referencia a nombres de habilidades válidos y existentes
• La entrada del registro existe con la ruta correcta (solo variantes)
• El recuento

  total_skills

  coincide con el recuento real de habilidades en disco
• Los symlinks se resuelven correctamente (solo variantes)

• git diff

  no muestra eliminaciones accidentales del contenido original

# Verificar frontmatter
head -20 skills/<skill-name>/SKILL.md

# Contar habilidades en disco vs registro
find skills -name SKILL.md | wc -l
grep total_skills skills/_registry.yml

# Comprobar symlinks (para variantes)
ls -la .claude/skills/<skill-name>-advanced
readlink -f .claude/skills/<skill-name>-advanced/SKILL.md

# Revisar todos los cambios
git diff

Esperado: Todos los elementos de la lista de verificación pasan. La habilidad evolucionada está lista para confirmar.

En caso de fallo: Abordar cada elemento fallido individualmente. El problema más común tras la evolución es un recuento

total_skills

Validación

• SKILL.md existe y tiene frontmatter YAML válido
• El campo

  version

  refleja los cambios realizados
• Todos los pasos del procedimiento tienen bloques Expected y On failure
• Las referencias de Related Skills son válidas (sin referencias cruzadas rotas)
• El

  total_skills

  del registro coincide con el recuento real en disco
• Para variantes: nueva entrada en

  _registry.yml

  con la ruta correcta
• Para variantes: symlinks creados en

  .claude/skills/

  y

  ~/.claude/skills/

• 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

  en el frontmatter antes de confirmar.
• Eliminación accidental de contenido: Al reestructurar pasos, es fácil perder un bloque On failure o una fila de tabla. Siempre revisar

  git diff

  antes de confirmar.
• Referencias cruzadas obsoletas: Al crear una variante, tanto el original como la variante necesitan referenciarse mutuamente. Las referencias unidireccionales dejan el grafo incompleto.
• Desviación del recuento del registro: Tras crear una variante, el recuento

  total_skills

  debe incrementarse. Olvidarlo causa fallos de validación en otras habilidades que comprueban el registro.
• Aumento de alcance durante el refinamiento: Un refinamiento que duplica la longitud de la habilidad debería ser probablemente una variante en su lugar. Si añades más de 3 nuevos pasos del procedimiento, reconsiderar la decisión de alcance del Paso 3.
• Evitar

  git mv

  en rutas montadas en NTFS (WSL): En rutas

  /mnt/

  ,

  git mv

  para directorios puede crear permisos rotos (

  d?????????

  ). Usar

  mkdir -p

  + copiar archivos +

  git rm

  la ruta antigua en su lugar. Ver la sección de solución de problemas de la guía del entorno.

Habilidades Relacionadas

• create-skill

  — base para la creación de nuevas habilidades; evolve-skill asume que esto se siguió originalmente

• commit-changes

  — confirmar la habilidad evolucionada con un mensaje descriptivo

• configure-git-repository

  — cambios de habilidades bajo control de versiones

• security-audit-codebase

  — revisar habilidades evolucionadas para detectar secretos incluidos accidentalmente