chore: improve release skill

Author: AaronCQL

.claude/skills/release/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: release
-description: Draft a new release by updating CHANGELOG.md and bumping the version in package.json
+description: Draft a new release by bumping the version and updating the changelog. Use when changes are committed and ready to ship.
 disable-model-invocation: true
+allowed-tools: Bash(git *), Bash(jq *), Read, Edit, Write, AskUserQuestion
 ---
 
 # Release
@@ -17,14 +18,13 @@ Draft a new release by updating CHANGELOG.md and bumping the version in package.
 
 ### 1. Pre-flight checks
 
-Run these checks before proceeding:
-
 - **Branch check:** Verify the current branch is `main`. If not, stop and tell the user.
 - **Clean work tree:** Run `git status` to check for uncommitted changes. If the work tree is dirty, ask the user to confirm they want to ignore the changes before continuing.
+- **Pull latest:** Run `git pull` to ensure the local branch is up to date with the remote.
 
 ### 2. Determine the current and next version
 
-- Read the current version from `package.json`.
+- Read the current version from `package.json` using `jq -r .version package.json`.
 - List all git tags matching `v*` sorted by version descending. The latest tag is the current release.
 - Gather all commits from the latest tag to HEAD using `git log <latest-tag>..HEAD`. Use the full log (not `--oneline`) so commit bodies are available for writing better descriptions.
 - If there are no new commits since the last tag, stop and tell the user there is nothing to release.
@@ -36,24 +36,25 @@ This project is pre-v1. Apply these rules based on the actual nature of the chan
 - **Minor bump** (0.x.0): if any commit introduces new functionality or contains `BREAKING CHANGE`
 - **Patch bump** (0.x.y): for everything else (bug fixes, docs, CI, refactors, etc.)
 
-Parse the current version from package.json, apply the bump, and determine the new version string.
-
 ### 4. Update CHANGELOG.md
 
-If CHANGELOG.md does not exist, create it. If it does, read it first, then prepend the new release section.
+Read CHANGELOG.md first, then prepend the new release section. If it does not exist, create it.
 
 The format for each release section:
 
 ```markdown
 ## vX.Y.Z
 
 ### Features
+
 - description (commit-hash)
 
 ### Bug Fixes
+
 - description (commit-hash)
 
 ### Improvements
+
 - description (commit-hash)
 ```
 
@@ -63,7 +64,7 @@ Group commits into these categories. Use the conventional commit prefix as a sta
 - Bug Fixes — actual bug fixes
 - Improvements — everything else (docs, CI, refactors, chores, etc.)
 
-Omit any category section that has no entries. Exclude version bump commits (e.g. `chore: bump version to vX.Y.Z`). Use the short commit hash (7 chars) in parentheses. Strip the conventional commit prefix from the description — just use the human-readable part. Rephrase descriptions where necessary to be more understandable, capitalised, and properly formatted (e.g. use backticks for command names, file names, and config values).
+Omit any category section that has no entries. Exclude version bump and release commits (e.g. `chore: bump version to vX.Y.Z`, `chore: release vX.Y.Z`). Use the short commit hash (7 chars) in parentheses. Strip the conventional commit prefix from the description — just use the human-readable part. Rephrase descriptions where necessary to be more understandable, capitalised, and properly formatted (e.g. use backticks for command names, file names, and config values).
 
 The file should have a top-level `# Changelog` heading, followed by release sections in reverse chronological order (newest first).
 
@@ -75,5 +76,5 @@ Update the `"version"` field in package.json to the new version string (without
 
 - Stage CHANGELOG.md and package.json with `git add`.
 - Show the user the staged diff with `git diff --cached`.
-- Tell the user the version bump (e.g. `0.2.2 → 0.3.0`) and ask for confirmation before committing.
+- Use the `AskUserQuestion` tool to confirm the release, showing the version bump (e.g. `0.2.2 → 0.3.0`).
 - Once confirmed, commit with message `chore: release vX.Y.Z` and push to `main`.