Release Note Skill

By the Syncfusion DevTutorials team · Last updated October 22, 2026

Choose a good first task, answer the five design questions, and build release-note-helper: grouping rules, fixed headings, style guide, check script, an AI-drafted version you review, and a with and without test.

Build Your First Real Skill

A release note skill turns a list of commits into clear notes for users. In this lesson, you will build one from start to finish. You will plan it, write it, review it and test it.

Every sprint ends the same way.

Someone reads a long list of commits.

Then they turn lines like "fix(api): timeout on large CSV exports" into words a customer understands.

This job is:

• Boring: it takes about half an hour.
• Repeated: it happens every sprint.
• Messy: every person does it a little differently.

That makes it a great first skill.

Simple lesson: a task you repeat, the same way, is a good skill.

A Real-World Example

Mei's team wrote release notes by hand.

One week, the notes said "We removed the old v1 login" in the middle of a long paragraph.

Customers missed it, and two of their apps broke.

A skill puts every change in a fixed place. Big changes can no longer hide.

Click the button and open the Library tab.

• SKILL.md: the steps the agent follows.
• references/style-guide.md: the wording rules.
• scripts/check_notes.py: a small script that checks the result.

Simple lesson: you will build each of these files in this lesson.

What You Will Learn

In this lesson, you will learn:

1. How to choose a good task for a skill.
2. How to answer the five design questions.
3. How to write grouping rules that never guess.
4. How to fix the shape of the output.
5. How to draft a skill with AI, then review it.
6. How to test the skill with and without it.

Choose the Right Task

Not every task should be a skill.

A good first skill passes four tests:

• Often: you ask for it at least once a week or once a sprint.
• Same steps: you could write the steps as a numbered list.
• Easy to check: you can tell quickly if the result is right.
• Low risk: a mistake is easy to spot and fix.

Example:

• Release notes: every sprint, same steps, easy to check, read before publishing. Good skill.
• Commit messages: many times a week, same steps, tiny risk. Good skill.
• Fixing the production database: rare, different every time, high risk. Not a skill.

Simple lesson: start with a small, safe task you repeat often.

Plan the Skill

The Five Design Questions

Before you write the file, answer five questions.

Each answer becomes one part of SKILL.md.

Important: if you cannot answer a question, the task is not ready to be a skill yet.

Watch the five answers turn into one file:

Each answer filled one part. At the end, the checker found no problems.

The Description

The description says three things:

• What the skill does.
• When to use it.
• When not to use it.

Turns a list of commits or merged pull requests into grouped, user-facing
release notes. Use when someone asks for release notes, a changelog or a
"what's new" summary for a version. Do not use for commit messages or code review.

It uses the words people really type: "release notes", "changelog" and "what's new".

Click the button and open the Activate tab.

• Score bar: release-note-helper passes the line, so it fires.
• Other skills: they stay closed.

Simple lesson: use the words your team really types in the description.

Write the Workflow

Grouping Rules

The main job is to put each change in exactly one group.

The five groups are:

• Features: new things users can do.
• Fixes: bugs that were fixed.
• Breaking changes: changes that may break users' apps.
• Internal changes: work users never see.
• Unknowns: lines that are not clear.

The rules run in a fixed order.

Breaking changes are checked first.

This is because feat!: remove legacy v1 login endpoint is a feature and a breaking change. If Features came first, it would hide there.

Watch the rules run on real commits:

Every commit landed in one group. "update stuff" went to Unknowns, not to a guess.

In SKILL.md, the rules become numbered steps:

## Workflow
1. Read every change line.
2. Put each change into exactly one group: Features, Fixes, Breaking changes,
   Internal changes or Unknowns.
3. A "!" after the type, or the words "remove" or "breaking", means Breaking changes.
4. chore, ci, build, test and docs changes go to Internal changes.
5. If you can't tell what a change does, put it in Unknowns. Never guess.
6. Rewrite each line for users: plain words, present tense, no commit prefixes.
7. Follow references/style-guide.md for wording.

Simple lesson: check the most important group first, and give unclear lines a safe place.

Wording Rules

Commits are written for developers.

Release notes are written for users.

Step 7 points to a small style guide:

# Release note style guide
- Start each line with a past-tense verb: Added, Fixed, Removed, Improved.
- Name the feature the user sees, not the file or function.
- Keep each line under 15 words.
- Breaking changes must say what users need to do.

The rules live in references/, not in SKILL.md.

This is because only the rewrite step needs them. The agent opens the file at that step.

Simple lesson: keep detailed rules in a reference file, and name it in one step.

Fix the Shape of the Output

Five Fixed Headings

## Output format
Use these headings in this order. Write "None" under an empty group.
- ## Features
- ## Fixes
- ## Breaking changes
- ## Internal changes
- ## Unknowns

Fixed headings help in three ways:

• Readers know where to look.
• Breaking changes always have their own place.
• A script can check the headings every time.

Important: use the exact same words every time. "Bug fixes" one week and "Fixes" the next will fail the check.

Example and Do Not Use

A short example shows the agent what one good line looks like:

## Examples
Input: `feat: add dark mode toggle`
Output line under Features: `- Added a dark mode toggle in Settings.`

## Do not use
- Writing a single commit message (use commit-writer).
- Reviewing code changes (use pr-review).

The "Do not use" list names the nearby skills. This stops the wrong skill from firing.

Final Checks

## Final checks
- Every input line appears exactly once.
- All five headings are present, in order.
- Run scripts/check_notes.py (Python) or scripts/check_notes.js (Node) if the notes will be published.

The first check catches lost or repeated changes.

The script checks the headings.

Click the button and read the script.

• REQUIRED: the five headings, in order.
• Result: it prints OK, or FAIL with what is missing.

Simple lesson: fixed headings let a script check every reply.

Draft It with AI

You do not have to type the skill from scratch.

You can ask an AI to draft it.

Give the AI your five answers. Then ask it to write a SKILL.md.

Many tools have a helper for this:

• Syncfusion Code Studio: type /create-skill in chat, or use + New Skill from /skills.
• OpenAI Codex: a built-in skill-creator skill.
• Claude Code: ask the agent to create a skill.

Important: an AI draft is a fast start. It is not a finished skill.

The AI does not know your team's rules. You must review every line.

Watch a real review:

The checker found missing sections. Your review found the bigger problems.

When you review a draft, ask:

• Where would the agent have to guess?
• Is the most important group checked first?
• Is the output shape fixed?
• Is there a final check?

Simple lesson: let AI draft the skill, then review and test it yourself.

Run and Compare

Now test the skill on real commits.

Click the button and press Compare in the Run tab.

• Without the skill: a friendly paragraph. The v1 login removal is hidden. "Exports are faster" is a guess.
• With the skill: five headings. The breaking change has its own place and an action. "update stuff" is in Unknowns.

Simple lesson: always compare with and without the skill, so you can see it helps.

Install It and Check It

Your skill only helps when your tool can find it.

Use the steps from Skill Installation:

1. Put the folder in your project skills folder. For example: .claude/skills/release-note-helper/SKILL.md.
2. Check that the folder name matches name: in the front matter.
3. Start a new session, so the tool reads the folder again.
4. List the skills. Look for release-note-helper.
5. Call it by name with a few commits.
6. Then ask in plain words: "Write release notes for v3.1 from these commits."

If step 5 works but step 6 does not, fix the description. If step 4 fails, fix the folder.

Simple lesson: a skill is not done until you install it and see it fire.

TL;DR

1. Good first skill = a task you repeat often, with the same steps, easy to check and low risk.

2. Five design questions = when, what to read, which steps, what result, how to check.

   • Each answer becomes one part of SKILL.md.

3. Grouping rules = put each change in exactly one group.

   • Check Breaking changes first.
   • Put unclear lines in Unknowns. Never guess.
4. Fixed headings = the same five headings, in the same order, every time.
5. Style guide = wording rules in references/, opened at one step.
6. Check script = a small script that tests the headings.
7. AI draft = a fast start. Review and test it before you use it.
8. Compare = run the request with and without the skill.

Common Mistakes

Check Your Understanding

Exercises

These exercises use the real release-note-helper skill.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• Pick a first skill that is frequent, repeated, easy to check and low risk.
• Answer the five design questions before you write the file.
• Check the most important group first, and never guess.
• Use fixed headings, so a script can check every reply.
• Keep wording rules in references/ and checks in scripts/.
• Let AI draft the skill, but review and test it yourself.
• Compare replies with and without the skill.

Next: Workflow Instructions. You will learn to write steps the agent follows the same way every time.