I thought making my release notes skill reusable would mostly mean changing where it looked for information.
I’d built it for my team’s internal tool. It gathered code changes and project tickets, asked a couple of clarifying questions, and drafted release notes for our operations users.
To adapt it for another team, I expected to separate the workflow from the configuration: different repository, different project tickets, different Slack channel. I’d already followed that pattern with my weekly-update skill.
Then I got to the writing instructions.
The audience was hiding in the rules
Our operations users need to know what changed in their workflow. They understand journal entries and trade corrections. They shouldn’t need to interpret a database migration or a code-review summary to figure out whether something affects their work.
So I’d taught the skill to lead with the effect on the user. If a draft slipped into engineering language without explaining why it mattered, the instructions told it to stop and revise.
That worked for the audience I had in mind.
But a team publishing release notes for developers would need different instructions. Someone integrating with an API may need the technical detail I’d been telling the skill to translate or remove. A breaking change needs a clear explanation of what changed and what the developer must do.
My supposedly reusable workflow still assumed every reader was one of our operations users.
I’d made the sources configurable. I hadn’t done the same for the audience.
Small rules carried more context than I realized
Looking back through the skill, I could see other assumptions I’d built into it.
I capped follow-up questions at two because our previous release notes process had gone largely unused. It already felt like too much work. If the replacement required a long interview, we’d have another process people avoided.
I’d even added a rule about GIFs. Developer humor that feels natural in a code discussion can land strangely in a channel someone opens to learn what changed in their daily tools.
Those details made sense in our setting. They were also easy to mistake for universal rules once they were written into a skill.
Making the skill reusable meant reading those instructions again and asking which ones belonged to the workflow, which ones reflected our team’s habits, and which ones depended on who would read the result.
Ask who’s reading before choosing how to write
I added two fields to the setup: whether the release notes were for end users or developers, and a description of the specific audience.
The skill could then adjust its writing rules. The end-user version led with workflow impact. The developer version could lead with technical changes and include a breaking-changes section.
That split is a starting point. “End user” still covers plenty of people with different needs. The audience description gives the team room to explain what its readers already know and what they need from the notes.
Tone also remains uneven on a first run. When a channel has posting history, reading recent examples helps. Without it, the draft can be functional but flat. I still need to review whether it sounds right for the people receiving it.
I started this exercise expecting to move team-specific details into a configuration file. The harder work was noticing how much of my judgment about our readers was already embedded in the instructions.
The question I’d add to my next setup conversation is simple: what does this reader need to understand or do after reading the release notes? I want that answer before choosing the template.