VAADIN

Enseñándole a Claude Cómo Trabajamos: Skills para el Mantenimiento de Add‑ons

18 de noviembre de 2026 Paola De Bartolo 12 min
Una computadora retro con un cartucho conectado arriba, con íconos de git, pull request y checklist, rodeada de otros cartuchos

En mi post anterior planteé que, con la IA, crear un componente ya no es la parte difícil. Mantenerlo, sí. En Flowing Code mantenemos más de 30 add-ons, y la mayor parte de ese mantenimiento no es complejo, sino repetitivo: el mismo tipo de cambio, en muchos repositorios, siguiendo las mismas convenciones del equipo cada vez.

Claude puede ayudar mucho con ese tipo de trabajo, pero tiene que saber cómo trabaja el equipo, y explicárselo en cada conversación no es sostenible. Ahí es donde entran las skills de Claude Code.

Qué es una skill (y por qué no alcanza con un prompt)

Una skill es un conjunto de instrucciones empaquetadas que Claude Code carga cuando la tarea coincide con ella. En lugar de explicar nuestras convenciones en cada chat, las escribimos una vez, y Claude las aplica cada vez que va a hacer ese tipo de tarea.

La diferencia con un buen prompt es la durabilidad. Un prompt hay que pegarlo cada vez. Una skill queda en mi entorno, Claude la carga sola cuando aparece la tarea y puedo mejorarla cada vez que se equivoca.

Estas son tres de las skills que nos facilitan el mantenimiento de los add-ons: una para empezar un add-on nuevo, otra para nuestras convenciones del día a día y otra para una migración que toca muchos repositorios.

Empezar un add-on nuevo

Todo add-on nuevo arranca desde nuestro starter, y una de las primeras skills que pensé que podía ser útil para el equipo fue una para adaptarlo. Ya conté parte de esa historia en Crear un Add-on para Vaadin en Tiempo Récord con Claude AI, pero vale la pena volver a ella, porque es un ejemplo perfecto de trabajo repetitivo lleno de pequeñas trampas.

Adaptar el starter implica reemplazar los nombres del template en todos lados: el nombre visible, el artifact ID, el nombre del repositorio en el POM y en cada link y badge del README, las plantillas de issues, el año de inicio y las cabeceras de licencia. Nada de eso es difícil, pero los nombres no son todos iguales. El artifact ID termina en -addon, mientras que la URL del Vaadin Directory conserva el guion y termina en -add-on. Es el tipo de detalle que es fácil equivocar cuando lo haces a mano solo algunas veces al año.

La skill pide el nombre y la descripción, deriva todas las variantes, aplica los reemplazos y, al final, busca en todo el repositorio cualquier cosa que todavía parezca del template. Lo que no hace es igual de importante: renombrar los paquetes Java, escribir los ejemplos de uso e implementar el componente quedan en manos del desarrollador, y la skill los lista al final como trabajo pendiente.

Nuestras convenciones, por escrito: commits, PRs y revisiones

Nuestras convenciones cubren todo el camino desde el primer commit hasta un pull request mergeado, y son las mismas en todos nuestros repositorios de add-ons. Esa consistencia es la clave: cualquiera del equipo puede abrir cualquier repositorio y leer su historial, sus PRs y sus revisiones de la misma forma. Están escritas en documentos de workflow bastante extensos, pero un documento largo es fácil de olvidar justo cuando hace falta: no es algo que uno relea antes de cada commit.

Esta skill convierte esos documentos en reglas que Claude aplica cada vez, y es la que más uso, todos los días. Reúne nuestras convenciones de desarrollo en cuatro áreas.

Commits: Conventional Commits, a nuestra manera

Todos nuestros repositorios siguen nuestras guías de commits, una extensión de Conventional Commits. Cada mensaje de commit empieza con un tipo que indica qué clase de cambio es, como feat, fix, refactor, build, docs, test o chore, opcionalmente seguido de un scope, y después un resumen corto. Un mensaje como fix(demo): ... te dice de un vistazo qué cambió y dónde, antes de abrir un solo archivo.

Además del estándar, tenemos nuestras propias reglas:

  • El asunto va en imperativo, en minúscula, sin punto final, y todo el header tiene menos de 72 caracteres, incluidos el tipo y el scope.
  • Los breaking changes se marcan con ! después del tipo, para que sea imposible pasarlos por alto.
  • Los cambios de versión van en su propio commit build:, nunca mezclados con cambios de código.
  • El body es opcional. Lo agregamos solo cuando hace falta explicar el motivo de un cambio. Cuando un commit cierra un issue, lo indica un footer Close #n: ni Closes ni Fixes, Close.

Con más de 30 repositorios, estas pequeñas reglas son las que mantienen el historial legible. Cuando todos los commits tienen la misma forma, puedes recorrer el log de un add-on que no tocas hace meses y entender enseguida qué pasó.

Lo que salió mal la primera vez

La primera versión de esta skill agregaba un body a cada commit. Nuestras guías dicen que el body es opcional, pero mis instrucciones nunca decían cuándo no tenía que estar, así que Claude completaba el vacío con la práctica habitual y lo escribía siempre. Cuando escribí la regla de forma explícita, los commits empezaron a parecerse a los nuestros.

Esa fue la lección más útil de toda la experiencia: las partes de tus convenciones que se apartan de la práctica habitual son justamente las que tienes que escribir. Claude ya conoce las reglas generales. Lo que necesita de ti son las excepciones.

Pull requests

  • Todo PR empieza como borrador.
  • Su título es el asunto del commit principal, con el mismo formato de Conventional Commits.
  • La descripción es corta: un párrafo sobre qué y por qué, tal vez una breve lista de cambios, y Close #n. Nada de ensayos largos ni resúmenes autogenerados.

Revisiones: dos fases, dos formas de commitear

Las revisiones tienen dos fases, y la forma de commitear las correcciones cambia entre una y otra:

  1. Primero CodeRabbit, mientras el PR es un borrador. Como conté en nuestro post sobre CodeRabbit, hace la primera revisión. Las correcciones de esta fase se integran en el commit al que pertenecen, para que el historial quede limpio.
  2. Después, los compañeros, cuando el PR está listo para revisión. A partir de aquí el historial ya no se reescribe. Cada corrección es un commit WIP: nuevo, para que quien revisa vea exactamente qué cambió desde la última vez.
  3. Al mergear, se hace squash del PR, se descartan los commits WIP: y se conserva el mensaje del commit original tal cual estaba.

Y una regla que vale para todos: nadie resuelve sus propios hilos de revisión. Los resuelve quien revisa.

Siempre preguntar primero

Ninguna de estas reglas es complicada. Pero son suficientes, y con suficientes excepciones, como para que cumplirlas todas cada vez sea tedioso, y es fácil que se escape alguna.

Por eso la skill tiene una regla de oro por encima de todo: Claude nunca escribe en GitHub por su cuenta. Antes de cualquier commit, push, issue, PR o comentario, me muestra el mensaje, título o descripción exactos y espera mi OK. Ahora, cada vez que Claude va a hacer alguna de estas cosas en uno de nuestros repositorios, sigue las reglas de nuestro workflow, y yo mantengo el control de lo que realmente se publica.

Un warning chico, muchos repositorios

Vaadin 25.2 introdujo un warning de deprecación para los add-ons que incluyen archivos de frontend en META-INF/resources/frontend/. No era urgente: es solo un warning, y hoy no se rompe nada. Pero la comunidad ya lo estaba reportando, tanto en add-ons de Component Factory como en los nuestros, así que valía la pena resolverlo. La solución suena trivial: mover los archivos. Pero hay una trampa. Los archivos que se cargan con @JsModule o @CssImport van a un lugar y conservan sus rutas. Los que se cargan en tiempo de ejecución con @StyleSheet, @JavaScript o una URL van a otro lugar, y sus URLs cambian. Un movimiento descuidado compila bien y se rompe en ejecución.

La primera vez lo hice a mano, en el Enhanced Grid de Vaadin Component Factory. Una vez que entendí la regla, no quería volver a descubrirla en cada repositorio, así que empaqueté esa migración como una skill, usando ese PR como referencia: decide adónde va cada archivo según cómo se usa, hace el movimiento y después verifica que el jar generado y la demo arranquen sin el warning.

Desde entonces, migró otros add-ons de Component Factory, como Splide y Date Range Picker. Después les llegó el turno a nuestros propios add-ons.

Eso trajo una lección nueva. La regla para mover los archivos es la misma, pero nuestros add-ons están armados de otra forma que los de Component Factory. Nuestras demos corren sobre Jetty, que sirve archivos estáticos desde la misma carpeta que la migración vacía. Lo descubrí con ShareEasy, el primero de nuestros add-ons que migré: los archivos estaban en el lugar correcto y el build funcionaba, pero la demo no arrancaba. Git no guarda carpetas vacías, y Jetty seguía buscando esa. Además, muchos de nuestros add-ons soportan varias versiones de Vaadin a la vez, de la 14 a la 25, así que una migración puede necesitar validarse en cada una de ellas, no solo en la última. La primera skill no sabía nada de esto, así que creé una segunda, adaptada a nuestros repositorios.

Su primera versión era exhaustiva, quizás demasiado: validaba cada add-on en cada versión de Vaadin soportada, y estaba tardando muchísimo. Por eso la ajusté para que valide según el riesgo. Así lo dice la skill, un poco abreviado (en inglés, tal como está escrito):

**Light tier**: every change is a 100% rename of a bundle source
(`@JsModule` / `@CssImport`, annotations unchanged). The code does not
change and `META-INF/frontend/` is supported since Vaadin 14, so
multi-version runs add nothing. Run the static checks and one run on the
latest 25.x.

**Full tier**: any of: a runtime resource moved (`@StyleSheet`,
`@JavaScript("context://…")`, images, fonts: the URL changes and a mistake
only shows as a missing style, never a build error), a Java or annotation
edit, a deletion, or anything else outside the simple case. Run every
supported version and the browser check.

When unsure, use the full tier.

Fíjate que la skill no dice solo qué correr, sino por qué. Eso es lo que le permite a Claude decidir bien en los casos que la regla no enumera, y lo que me permite revisar su decisión antes de que ejecute algo.

Con esa versión, el resto de la migración llevó dos días: más de 20 de nuestros add-ons salieron de la ubicación deprecada, y la skill no necesitó más correcciones en el camino. Antes de cerrar la tarea, también le pedí a Claude que revisara todos nuestros repositorios activos contra la lista original. Encontró seis add-ons más que la lista no tenía, todos con archivos de demo todavía en la carpeta vieja, y verifiqué cada uno antes de migrarlo. Un buen recordatorio de que el mantenimiento rara vez termina cuando el checklist dice que terminó.

Una skill no solo guarda qué hacer. También guarda supuestos sobre dónde lo haces y cuánto control merece cada caso. Cuando esos supuestos resultan equivocados, se corrige la skill.

No todo necesita una skill

Igual, no todo trabajo repetitivo merece una skill. Hace poco, javadoc.io dejó de funcionar en nuestros builds, y el POM de cada add-on tuvo que apuntar sus links de Javadoc a nuestro propio servidor. Eso significó cerca de 40 repositorios, incluidas sus ramas de mantenimiento. Lo hicimos con un único prompt, muy simple:

Inspect all the add-ons (see our list of repositories). In pom, use flowingcode docs instead of javadoc.io (see AddonStarter24 template)

El starter ya tenía la configuración correcta, así que alcanzó con señalárselo a Claude como referencia.

Escribir una skill para eso no habría hecho ninguna diferencia. A primera vista se parece mucho a la migración de frontend: un cambio, aplicado una vez en cada repositorio. La diferencia está en cuánto te pide cada repositorio. El cambio de Javadoc era la misma edición en todos lados, y el starter mostraba exactamente cómo tenía que quedar. La migración de frontend requería decisiones en cada repositorio: qué archivos son del bundle y cuáles son recursos de ejecución, si la demo sigue arrancando, cuánta validación merece el cambio. Aprender esas reglas llevó algunos repositorios, y una skill es donde quedan aprendidas. Cada ajuste que le hice mejoró todos los repositorios que vinieron después.

También cambia quién puede hacer el trabajo. Hice la migración yo, pero con las reglas por escrito, cualquier compañero podría haber tomado la mitad de la lista y obtenido exactamente el mismo resultado. Un prompt también se puede compartir, pero cada persona tiene que pegarlo, y cada copia evoluciona por su lado. Una skill se usa sola cada vez que aparece la tarea, y si está compartida con el equipo, cada mejora les llega a todos los que la usan.

Entonces, la pregunta no es solo cada cuánto vuelve una tarea, sino cuánto criterio necesita cada vez y cuántas personas tienen que aplicar ese criterio de la misma forma. Para un cambio simple y mecánico, alcanza con un prompt claro.

Dónde siguen estando las personas

Las skills automatizan la parte mecánica, no el criterio. En todas ellas:

  • Nada llega a GitHub sin aprobación. Claude me muestra primero cada commit, push, issue y PR.
  • Las skills se mantienen acotadas. Cada una hace bien un tipo de tarea, en lugar de intentar “mantener el add-on”.
  • Las decisiones siguen siendo nuestras. Si un cambio es breaking, si un add-on necesita una nueva versión mayor, cómo responderle a un usuario en un issue: eso lo decide el equipo.

Lecciones aprendidas

Si estás pensando en escribir skills para tu equipo, esto es lo que te diría:

  1. Empieza por lo que más repites, no por lo que parece más impresionante.
  2. Igual, no toda tarea repetitiva necesita una skill. Depende de la tarea. Si cada repetición necesita criterio, o si otras personas van a tener que hacerla de la misma forma, escribe una skill. Si es el mismo cambio simple en todos lados, alcanza con un prompt claro.
  3. Escribe las excepciones, no las reglas generales. Claude conoce la práctica habitual; lo que necesita son las diferencias de tu equipo.
  4. Revisa el resultado con atención las primeras veces. Así es como encuentras los huecos en tus instrucciones.
  5. Corrige la skill, no la conversación. Cuando Claude se equivoca, corregirlo en el chat lo resuelve una vez. Corregir la skill lo resuelve para siempre.

Conclusión

Las skills transformaron nuestras convenciones, de documentos que había que recordar, en reglas que se aplican de forma consistente. Eso no reemplaza al equipo. Lo libera para dedicar tiempo a lo que realmente necesita una persona: decisiones de diseño, revisiones y ayudar a quienes usan nuestros add-ons.

Y sí, este mismo post se convirtió al formato que espera nuestro sitio con otra skill. Hay costumbres difíciles de dejar.

Gracias por leernos ¡and let’s keep the code flowing!

Paola De Bartolo
Paola De Bartolo

Ingeniera en Sistemas. Java Developer. Entusiasta de Vaadin desde el momento en que escuché "puedes implementar todo el UI con Java". Parte del #FlowingCodeTeam desde 2017.

¡Sumate a la conversación!