Writing Release Notes
Businesswriting-release-notesWriting Release Notes is an Agent Skill for business published in the actualbudget/actual repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use whenever adding, writing, drafting, or fixing a release note in the Actual Budget repo. This is the changelog entry that ships with a code change, living as a Markdown file in `upcoming-release-notes/`. Trigger for asks like "add a release note", "write the changelog entry", "add the release note for this PR/change", "create the upcoming release note", or any time finishing a user-facing change in this repo where a release note is the natural next step. These notes are published for humans to read, so they must be short, plain-language, and free of technical detail. Writing them like a commit message or with implementation jargon produces entries that get flagged and rewritten in review.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/actualbudget/actual/blob/HEAD/.claude/skills/writing-release-notes/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-release-notes, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Writing Release Notes for actualbudget/actual
Release notes are the user-facing changelog. Each code change adds one Markdown file to upcoming-release-notes/, and these get collected into the published changelog at the next release. The authoritative source is the Writing Good Release Notes section of packages/docs/docs/contributing/index.md. Read it if anything below is unclear.
The file
Create upcoming-release-notes/<slug>.md, where <slug> is a short, descriptive kebab-case slug naming the change (e.g. add-payee-autocomplete.md, fix-mobile-category-delete.md). Do not use a PR number, since the PR link is resolved automatically at release time. (Numeric filenames like 1234.md still work, but a slug is preferred.)
---
category: Features
authors: [YourGitHubUsername]
---
Add payee autocomplete to the transaction entry form
category: exactly one ofFeatures(new feature),Enhancements(improvement to an existing feature),Bugfix(bug fix), orMaintenance(internal change with no user-visible effect).authors: array of the GitHub username(s) who did the work.
Writing the entry
The body is the changelog line. It is read by everyday users, not developers.
- One sentence. Short and clear. No paragraphs, no bullet lists, no long prose.
- Plain language, no technical detail. Describe what changed for the user, not how it was built. Avoid file names, function names, internal component names, and implementation jargon. (Exception:
Maintenanceentries may be technical, since they are for internal changes.) - Phrase it as a command. Start with a present-tense verb: "Add …", "Fix …", "Show …", not "Added …" or "Adds …".
- Generally match the PR title, but reword it if that reads more clearly to a user.
Good: Fix incorrect balance when reconciling an account with future transactions
Too technical: Fix off-by-one in reconcileTransactions() when txn.date > today