VAADIN

Teaching Claude How We Work: Skills for Add‑on Maintenance

November 18, 2026 Paola De Bartolo 12 min
A retro computer with a cartridge plugged in on top, showing git, pull request and checklist icons, surrounded by other cartridges

In my previous post I argued that, with AI, creating a component is no longer the hard part. Maintaining it is. At Flowing Code we maintain more than 30 add-ons, and most of that maintenance is not complex, just repetitive: the same kind of change, in many repositories, following the same team conventions every single time.

Claude can help a lot with that kind of work, but it needs to know how the team works, and explaining it again in every conversation doesn’t scale. That is where Claude Code skills come in.

What a skill is (and why not just a prompt)

A skill is a packaged set of instructions that Claude Code loads when the task at hand matches it. Instead of explaining our conventions in every chat, we write them down once, and Claude applies them whenever it is about to do that kind of task.

The difference with a good prompt is durability. A prompt has to be pasted again every time. A skill stays in my setup, Claude loads it on its own when the task comes up, and I can improve it every time it gets something wrong.

Here are three of the skills that make our add-on maintenance easier: one to start a new add-on, one for our day-to-day conventions, and one for a migration that touches many repositories.

Starting a new add-on

Every new add-on starts from our starter template, and one of the first skills I thought the team would benefit from was one to adapt it. I already told part of that story in Building a Vaadin Add-on in Record Time with Claude AI, but it is worth coming back to, because it is a perfect example of repetitive work full of small traps.

Adapting the starter means replacing the template’s placeholder names everywhere: the display name, the artifact ID, the repository name in the POM and in every link and badge of the README, the issue templates, the inception year and the license headers. None of it is difficult, but the names are not all the same. The artifact ID ends in -addon, while the Vaadin Directory URL keeps the dash and ends in -add-on. The kind of detail that is easy to get wrong when you only do it by hand a few times a year.

The skill asks for the name and description, derives every variant from them, applies the replacements and, at the end, searches the whole repository for anything that still looks like the template. What it doesn’t do is just as important: renaming the Java packages, writing the usage examples and implementing the component stay with the developer, and the skill lists them at the end as pending work.

Our conventions, written down: commits, PRs and reviews

Our conventions cover the whole path from the first commit to a merged pull request, and they are the same in every one of our add-on repositories. That consistency is the point: anyone on the team can open any repository and read its history, its PRs and its reviews the same way. They are written down in detailed workflow documents, but a long document is easy to forget right when you need it: it is not something you reread before every commit.

This skill turns those documents into rules Claude applies every time, and it is the one I use the most, every single day. It holds our development conventions in four areas.

Commits: Conventional Commits, our way

All our repositories follow our commit guidelines, an extension of Conventional Commits. Every commit message starts with a type that says what kind of change it is, such as feat, fix, refactor, build, docs, test or chore, optionally followed by a scope, and then a short summary. A message like fix(demo): ... tells you at a glance what changed and where, before you open a single file.

On top of the standard, we have our own rules:

  • The subject is imperative, lowercase, with no trailing period, and the whole header stays under 72 characters, including type and scope.
  • Breaking changes are marked with ! after the type, so they are impossible to miss.
  • Version bumps go in their own build: commit, never mixed with code changes.
  • The body is optional. We add it only when the motivation for a change needs explaining. When a commit closes an issue, a Close #n footer says so: not Closes, not Fixes, Close.

With more than 30 repositories, these small rules are what keep the history readable. When every commit follows the same shape, you can scan the log of an add-on you haven’t touched in months and immediately understand what happened.

What went wrong the first time

The first version of this skill added a body to every commit. Our guidelines say the body is optional, but my instructions never said when it should not be there, so Claude filled the gap with common practice and wrote one every time. Once I spelled the rule out, the commits started looking like ours.

That was the most useful lesson of the whole experience: the parts of your conventions that differ from common practice are exactly the ones you have to spell out. Claude already knows the general rules. What it needs from you is the exceptions.

Pull requests

  • Every PR starts as a draft.
  • Its title is the main commit subject, in the same Conventional Commits format.
  • The description is short: a paragraph about what and why, maybe a brief list of changes, and Close #n. No long essays, no auto-generated summaries.

Reviews: two phases, two ways of committing

Reviews happen in two phases, and the way fixes are committed changes between them:

  1. CodeRabbit first, while the PR is a draft. As I explained in our post about CodeRabbit, it does the first review. Fixes in this phase are folded into the commit they belong to, so the history stays clean.
  2. Teammates next, once the PR is ready for review. From this point the history is not rewritten anymore. Each fix is a new WIP: commit, so reviewers can see exactly what changed since their last look.
  3. On merge, the PR is squashed, dropping the WIP: commits and keeping the original commit message exactly as it was.

And one rule that applies to everyone: nobody resolves their own review threads. The reviewer does.

Always ask first

None of these rules is complicated. But there are enough of them, with enough exceptions, that getting all of them right every time is tedious, and it is easy to miss one.

So the skill has one golden rule above everything else: Claude never writes to GitHub on its own. Before any commit, push, issue, PR or comment, it shows me the exact message, title or description and waits for my OK. Now, whenever Claude is about to do any of these things in one of our repositories, it follows our workflow rules, and I stay in control of what actually gets published.

A small warning, many repositories

Vaadin 25.2 introduced a deprecation warning for add-ons that ship frontend sources under META-INF/resources/frontend/. It wasn’t urgent: it is only a warning, and nothing breaks today. But the community was already reporting it, both on Component Factory add-ons and on ours, so it was worth fixing. The fix sounds trivial: move the files. But there is a trap. Files loaded through @JsModule or @CssImport go to one place and keep their paths. Files loaded at runtime through @StyleSheet, @JavaScript or a URL go to another place, and their URLs change. A careless move compiles fine and breaks at runtime.

The first time, I did it by hand, on the Vaadin Component Factory Enhanced Grid. Once I understood the rule, I didn’t want to rediscover it on every repository, so I packaged that migration as a skill, using that PR as its reference: it decides where each file goes based on how it is used, makes the move, and then checks that the packaged jar and the demo start with no warning.

Since then, it has migrated other Component Factory add-ons, such as Splide and Date Range Picker. Then it was our own add-ons’ turn.

That turned out to be a new lesson. The rule for moving the files is the same, but our add-ons are built differently from the Component Factory ones. Our demos run on Jetty, which serves static files from the same folder the migration empties. I found that out with ShareEasy, the first of our add-ons I migrated: the files were in the right place and the build was fine, but the demo wouldn’t start. Git doesn’t keep empty folders, and Jetty was still looking for that one. And many of our add-ons support several Vaadin versions at once, from 14 to 25, so a migration may need to be validated on each of them, not only on the latest one. The first skill knew nothing about any of that, so I created a second one, tailored to our repositories.

Its first version was thorough, maybe too thorough: it validated every add-on on every supported Vaadin version, and it was taking far too long. So I adjusted it to validate by risk. This is how the skill puts it, slightly abridged:

**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.

Notice that the skill doesn’t just say what to run, it says why. That is what lets Claude decide well in the cases the rule doesn’t list, and what lets me review its decision before it runs anything.

With that version in place, the rest of the migration took two days: more than 20 of our add-ons moved out of the deprecated location, and the skill didn’t need any more corrections along the way. Before closing the task, I also asked Claude to check all our active repositories against the original list. It found six more add-ons that the list had missed, all of them with demo files still in the old folder, and I verified each one before migrating it. A good reminder that maintenance work is rarely done when the checklist says it is.

A skill doesn’t only capture what to do. It also captures assumptions about where you do it, and how much checking each case deserves. When those assumptions turn out wrong, you fix the skill.

Not everything needs a skill

Not all repetitive work deserves a skill, though. Recently, javadoc.io stopped working in our builds, and every add-on’s POM had to point its Javadoc links to our own server instead. That meant close to 40 repositories, including their maintenance branches. We did it with a single, very simple prompt:

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

The starter template already had the right configuration, so it was enough to point Claude at it as the reference.

Writing a skill for that would not have made any difference. At first sight, it looks a lot like the frontend migration: one change, applied once to every repository. The difference is how much each repository asks of you. The Javadoc change was the same edit everywhere, and the template showed exactly what it had to look like. The frontend migration needed decisions in every repository: which files are bundle sources and which are runtime resources, whether the demo still starts, how much validation the change deserves. Those rules took a few repositories to learn, and a skill is where they stay learned. Every adjustment I made to it improved every repository that came after.

It also changes who can do the work. I ran the migration myself, but with the rules written down, any of my teammates could have taken half the list and gotten exactly the same result. You can share a prompt too, but each person has to paste it, and every copy evolves on its own. A skill is picked up whenever the task comes up, and if it is shared with the team, every improvement reaches everyone who uses it.

So the question is not only how often a task comes back, but how much judgment it needs each time, and how many people need to apply that judgment the same way. For a simple, mechanical change, a clear prompt is enough.

Where humans stay in the loop

Skills automate the mechanical part, not the judgment. In all of them:

  • Nothing reaches GitHub without approval. Every commit, push, issue and PR is shown to me first.
  • The skills stay narrow. Each one does one kind of task well, instead of trying to “maintain the add-on”.
  • Decisions remain ours. Whether a change is a breaking one, whether an add-on needs a new major version, how to answer a user in an issue: those are still the team’s call.

Lessons learned

If you are thinking about writing skills for your own team, this is what I would tell you:

  1. Start with what you repeat the most, not with what seems most impressive.
  2. Not every repetitive task needs a skill, though. It depends on the task. If each repetition needs judgment, or other people will need to do it the same way, write a skill. If it is the same simple change everywhere, a clear prompt will do.
  3. Write the exceptions, not the general rules. Claude knows common practice; your team’s differences are what it needs.
  4. Review the output closely the first few times. That is how you find the gaps in your instructions.
  5. Fix the skill, not the conversation. When Claude gets something wrong, correcting it in the chat solves it once. Correcting the skill solves it for good.

Conclusion

Skills turned our conventions from documents we had to remember into rules that are applied consistently. That doesn’t replace the team. It frees the team to spend time on what actually needs a human: design decisions, reviews and helping the people who use our add-ons.

And yes, this post itself was turned into the format our website expects with another skill. Some habits are hard to break.

Thanks for reading, and let’s keep the code flowing!

Paola De Bartolo
Paola De Bartolo

Systems Engineer. Java Developer. Vaadin enthusiast since the moment I heard "you can implement all UI with Java". Proud member of the #FlowingCodeTeam since 2017.

Join the conversation!