La respuesta corta

Si creas habilidades reutilizables para agentes de IA — esos paquetes de instrucciones y recursos que enseñan a Claude, ChatGPT u otros asistentes tus flujos de trabajo — trátalas como un pequeño proyecto de software. Usa versionado semántico (un número de tres partes como 1.4.2, donde cada parte indica un tipo de cambio), escribe un changelog breve dentro de cada habilidad y migra con criterio cuando una plataforma cambie su formato. Así tu biblioteca personal sobrevive a cada actualización sin romperse en silencio.

Este artículo recorre cuándo subir versión, qué forma tiene un changelog útil para habilidades y cómo mantener tu biblioteca sana mientras Anthropic, OpenAI y otros evolucionan sus formatos.

Por qué las habilidades necesitan versionado

Las habilidades son carpetas con instrucciones y, opcionalmente, scripts y archivos de referencia. Al crear una, sueles incrustar convenciones que importan a tu trabajo: la estructura de una nota de release, el tono de un correo saliente, el orden de pasos de un checklist de despliegue, los campos exactos de un formulario de intake.

Esas convenciones cambian. Las refinas con el tiempo. Las plataformas también cambian: Anthropic sacó Agent Skills y la Skills API de beta en la API de Claude en agosto de 2026, el tipo de movimiento que puede afectar en silencio cómo se cargan las habilidades, qué campos aceptan y qué endpoints usan. Sin versionado, no puedes saber de un vistazo qué copia de una habilidad es la activa, cuál clonó un compañero el trimestre pasado o cuál se romperá con el release del mes que viene.

Un número de versión más un changelog corto convierten cada habilidad, de un archivo estático, en algo que puedes auditar, revertir y migrar.

Cuándo subir versión: patch, minor o major

El modelo mental más limpio para habilidades es el mismo que usa la mayoría de las librerías de software: versionado semántico.

  • Patch (1.0.1) — erratas, redacción más clara, un ejemplo que faltaba, un arreglo pequeño que no cambia qué hace la habilidad ni cómo está estructurada.
  • Minor (1.1.0) — añadiste una sección nueva, un ejemplo de código nuevo, un archivo de referencia nuevo, o documentaste una funcionalidad recién publicada del framework que la habilidad ahora cubre. Cualquier cosa que sume capacidad sin romper lo que ya funcionaba.
  • Major (2.0.0) — reescribiste el frontmatter (el bloque YAML al inicio de SKILL.md que le dice a la plataforma qué es la habilidad y cuándo cargarla), cambiaste nombres de campos obligatorios, eliminaste una sección de la que dependían otros flujos, renombraste conceptos clave, o moviste la habilidad de ubicación. Cualquier cosa que el consumidor tenga que editar para que siga funcionando.

Una regla práctica útil, basada en las políticas de versionado que han empezado a aparecer en torno a las habilidades de Claude: los cambios en el framework o plataforma que documentas van en el nombre y la description de la habilidad, no en un bump major. Las versiones mayores son para cambios en la habilidad misma, no en el mundo que describe.

Si estás a punto de reescribir la descripción del frontmatter, o de renombrar la habilidad para que coincida con una versión nueva del framework, suele ser señal de actualizar con cuidado como minor o, si el comportamiento anterior ya no se puede alcanzar, de planear un major.

Escribir un changelog que la gente realmente siga

Un buen changelog de habilidad es breve, con fecha y brutalmente concreto. Hay dos formatos que funcionan.

El primero es un archivo CHANGELOG.md dentro de la carpeta de la habilidad, en orden del más reciente al más antiguo. Cada entrada lleva la versión, una fecha y de tres a cinco puntos en lenguaje claro. Quien lee debería poder ojear las tres últimas entradas y saber si su flujo se ve afectado.

El segundo es una sección corta cerca del final del propio SKILL.md, bajo un encabezado como “Revision history”. Esto mantiene el changelog dentro del archivo que el asistente realmente lee, lo cual es conveniente para bibliotecas de una persona pero ruidoso cuando ya tienes varias habilidades.

Elijas el que elijas, mantén las entradas cortas y concretas:

## 1.2.0 — 2026-09-04
- Añadí la sección "rollback steps" al procedimiento de despliegue.
- Ejemplo nuevo para el entorno de staging.
- Aclaré cuándo saltarse el paso de cache-bust.

## 1.1.0 — 2026-07-22
- Documenté la nueva cabecera de auth v2 en la sección de llamadas a la API.
- Añadí una entrada de troubleshooting para el error "missing scope".

## 1.0.1 — 2026-06-30
- Corregí una errata en el checklist de release.
- Apreté la descripción del frontmatter para que la habilidad cargue de forma más fiable.

Tres detalles separan un changelog útil de uno ruidoso. Primero, incluye siempre la fecha: las habilidades evolucionan más rápido que la mayoría del código, y “recientemente” no se puede buscar. Segundo, describe el cambio en términos de quien lee, no en términos de qué editaste en el archivo. “Añadí pasos de rollback” gana a “expandí la sección 3”. Tercero, señala cualquier cosa que no sea retrocompatible (ver abajo) de manera imposible de pasar por alto.

Retrocompatibilidad: la pregunta que lo decide todo

La mayoría de las actualizaciones deberían ser retrocompatibles. La habilidad carga igual, acepta los mismos campos de frontmatter y produce los mismos resultados para los flujos que ya funcionaban. Solo estás añadiendo un ejemplo nuevo o corrigiendo una errata. Eso es patch o minor.

Una habilidad rompe retrocompatibilidad cuando quien lee tiene que editar algo de su lado para seguir usándola. Los casos clásicos:

  • Renombraste un campo obligatorio del frontmatter.
  • Eliminaste una sección a la que otra habilidad o flujo hacía referencia explícita.
  • Cambiaste el sentido de una instrucción existente de forma que cambia el resultado.
  • Reestructuraste la carpeta y los archivos a los que apuntaba la automatización de quien lee ya no existen.

En todos esos casos, el cambio es un bump de versión mayor, y la entrada del changelog debería decirlo a voces. Algo como:

## 2.0.0 — 2026-10-15 — BREAKING
- Renombré el campo de frontmatter `summary` a `description`. Los
  valores antiguos de `summary` se ignoran; actualiza tu SKILL.md.
- Moví los ejemplos fuera de `SKILL.md` a `references/examples.md`.
  Los flujos que leían ejemplos desde la raíz de la habilidad deben
  actualizarse.

Aquí es donde una nota de migración de una frase se gana su sitio. Dile a quien lee exactamente qué hacer, no solo qué cambió.

Cuándo actualizar una habilidad vs. crear una nueva

Esta es la pregunta que aparece el día que un release de plataforma cambia el formato.

Actualiza la habilidad existente cuando el cambio es local: un campo nuevo, un comportamiento más claro, un concepto renombrado. Tu entrada de changelog, tu bump de versión y quien lee pueden absorberlo en una sola pasada.

Crea una habilidad nueva cuando el cambio es estructural: un esquema de frontmatter distinto, una disposición de carpetas distinta, una forma distinta de declarar cuándo debe cargarse la habilidad. Intentar doblar la habilidad vieja a la nueva forma suele producir un archivo que funciona en una plataforma y falla en silencio en otra. Una habilidad aparte, con su propia versión empezando en 1.0.0, te permite mantener la antigua funcionando mientras migras usuarios a tu ritmo.

Una prueba útil: si tendrías que escribir un párrafo arriba del changelog explicando una migración de varios pasos, eso es una habilidad nueva, no una actualización.

Un plan práctico de migración para tu biblioteca personal

La mayoría de los fundadores acumulan habilidades en una sola carpeta y entran en pánico el día que Anthropic u OpenAI publican un cambio brusco. Una rutina pequeña mantiene ese pánico barato.

  1. Inventario. Una vez por trimestre, lista cada habilidad que tengas, qué hace en una frase y la última versión que tocó un cambio brusco. Una tabla en markdown plano sirve.
  2. Fija una línea base. Para cada habilidad, anota las versiones de plataforma y esquemas de frontmatter contra los que fue probada. Cuando una plataforma anuncia un cambio, sabes exactamente qué habilidades están en juego.
  3. Lee primero el changelog de la plataforma, luego el de tu habilidad. Cuando Anthropic sacó Agent Skills y la Skills API de beta, el cambio visible inmediato fue pequeño — dejó de ser obligatoria una cabecera beta — pero la migración del SDK (kit de desarrollo) que vino después cambió cómo se cargan las habilidades en algunos flujos. Leer ambas notas antes de tocar un archivo te ahorra parchear la capa equivocada.
  4. Migra en este orden. Primero el frontmatter y los campos obligatorios, porque eso rompe la carga por completo. Luego la estructura de carpetas, luego las referencias y scripts, luego las instrucciones en prosa. Corre la habilidad contra una tarea representativa después de cada capa.
  5. Mantén la versión vieja accesible. Hasta que hayas probado la nueva de extremo a extremo, no borres el archivo antiguo. Renómbralo a mi-habilidad.v1.md o muévelo a una carpeta archive/. Si la migración muestra una regresión real, puedes revertir en segundos.
  6. Sube la versión, escribe el changelog y luego publica. La disciplina de escribir la entrada del changelog antes de publicar te obliga a describir el cambio como lo vivirá quien lee, que suele ser además la descripción más útil.

Un ejemplo paso a paso

Imagina que tienes una habilidad llamada release-notes que convierte una lista de commits en una nota de release para clientes. Empezó en 1.0.0 y, en tres meses, le añadiste una sección de “known issues” (1.1.0), arreglaste un bug de formato de fecha (1.1.1) y aclaraste la descripción del frontmatter (1.1.2).

Luego, la plataforma que apuntas introduce un campo opcional nuevo en el frontmatter, audience, que quieres empezar a usar para marcar habilidades como internas o externas. Lo añades, lo documentas y publicas 1.2.0. Retrocompatible, sin migración.

Seis meses después, la plataforma renombra audience a visibility y lo vuelve obligatorio para habilidades que tocan contenido para clientes. Eso es un cambio brusco para cualquier automatización que en su lado asignaba audience de forma explícita. Publicas 2.0.0 con una entrada claramente etiquetada como BREAKING, una nota de migración (“busca y reemplaza audience: por visibility: en tus overrides”) y mantienes 1.2.0 en archive/ durante un ciclo de release.

Ese es todo el ciclo. La habilidad ahora tiene un historial en el que se puede confiar.

Preguntas frecuentes

¿Necesito versionar una habilidad que solo uso yo? Sí, pero puedes mantener la disciplina ligera. Una sola línea “Última actualización:” arriba del SKILL.md más una nota de una línea sobre qué cambió basta para mantener honesto a tu yo del futuro.

¿Dónde guardo el número de versión? Dentro de la carpeta de la habilidad, como un archivo VERSION con el número de tres partes, o como un campo version en el frontmatter si la plataforma lo soporta. La API de Claude Skills, por ejemplo, expone un campo latest_version por habilidad, lo que significa que los identificadores de versión forman parte de cómo se direccionan las habilidades allí.

¿Con qué frecuencia debería subir versión? Cada vez que el cambio encaje con una de las reglas. No hay valor en agrupar tres cambios no relacionados en un solo minor; tu yo del futuro no recordará qué cambio rompió qué flujo.

¿Y si una plataforma cambia el esquema de frontmatter de la noche a la mañana? Trátalo como un bump mayor para todas las habilidades afectadas. Sigue el plan de migración de arriba, mantén la versión vieja archivada y resiste la tentación de reescribir todas las habilidades de una sentada. Una migración por etapas es más rápida en la práctica que una migración de golpe.

¿Es versionado semántico overkill para instrucciones de prompt sueltas? Para prompts sueltos, sí. Para cualquier cosa que reutilizas entre proyectos, entre clientes o entre actualizaciones de plataforma, no. El coste de escribir 1.4.2 es trivial; el coste de no saber qué copia de una habilidad estás corriendo se acumula rápido.

Fuentes