11---
22name : github-release
33description : >
4- Guides IA through releasing a new version of a GitHub library end-to-end.
4+ Guides IA through releasing a new version of a GitHub library end-to-end.
55 Handles SemVer versioning and Keep a Changelog formatting automatically.
66compatibility : " requires: gh CLI and git"
77---
@@ -10,9 +10,9 @@ compatibility: "requires: gh CLI and git"
1010
1111This skill automates the full release workflow for a single-package GitHub repository,
1212from analysis through changelog authoring and PR creation. It relies exclusively on
13- ` gh ` (GitHub CLI) and ` git ` — no other tools needed.
13+ ` gh ` (GitHub CLI) and ` git ` no other tools needed.
1414
15- Steps 1– 4 are ** read-only reconnaissance** — nothing is written to the repo until
15+ Steps 1 - 4 are ** read-only reconnaissance** nothing is written to the repo until
1616Step 5, once the version number is confirmed.
1717
1818## When to Use This Skill
@@ -26,7 +26,7 @@ ship a new version" or "time to release".
2626
2727## Prerequisites
2828
29- Examples below include both Bash and PowerShell variants; Windows users should prefer
29+ Examples below include both Bash and PowerShell variants; Windows users should prefer
3030the PowerShell blocks.
3131
3232Before starting, verify the environment:
@@ -42,7 +42,7 @@ If any check fails, stop and tell the user what to fix before continuing.
4242Then ask the user one question:
4343
4444> * "Which directory contains your library's public-facing source code?
45- > (e.g. ` src/ ` , ` lib/ ` , ` pkg/ ` — used to focus the diff on what consumers
45+ > (e.g. ` src/ ` , ` lib/ ` , ` pkg/ ` - used to focus the diff on what consumers
4646> actually see. Press Enter to scan the whole repo.)"*
4747
4848Store the answer as ` PUBLIC_PATH ` . If empty, ` PUBLIC_PATH ` is ` . ` (repo root).
@@ -59,7 +59,7 @@ its output. Pause and ask for confirmation only when explicitly noted.
5959
6060---
6161
62- ### Step 1 — Ensure main is up to date
62+ ### Step 1 - Ensure main is up to date
6363
6464``` bash
6565git checkout main
@@ -71,7 +71,7 @@ is confirmed.
7171
7272---
7373
74- ### Step 2 — Grab the latest version tag
74+ ### Step 2 - Grab the latest version tag
7575
7676> ** Why not ` gh release list ` ?** GitHub Releases are an optional layer on top of Git
7777> tags. Many repos tag releases with ` git tag ` without ever creating a GitHub Release,
@@ -114,7 +114,7 @@ git ls-remote --tags origin | grep "refs/tags/$PREV_TAG$"
114114```
115115
116116If the remote check returns nothing, warn the user that the tag appears to be local-only
117- and hasn't been pushed — they may want to push it before continuing.
117+ and hasn't been pushed - they may want to push it before continuing.
118118
119119- ` PREV_TAG ` is the tag name exactly as found (e.g. ` v1.4.2 ` ). Strip any leading ` v `
120120 when doing arithmetic; preserve it when naming things.
@@ -130,12 +130,12 @@ PREV_SHA=$(git rev-list -n 1 "$PREV_TAG" 2>/dev/null || git rev-list --max-paren
130130
131131---
132132
133- ### Step 3 — Analyse what changed since the last release
133+ ### Step 3 - Analyse what changed since the last release
134134
135135This step uses ** two complementary signals** . The code diff is the primary source of
136136truth; commit messages provide supporting context about intent.
137137
138- #### 3a — Code diff (primary signal)
138+ #### 3a - Code diff (primary signal)
139139
140140``` bash
141141# Focused diff on the public source path, excluding noise
@@ -155,15 +155,15 @@ git diff "$($prevSha)..HEAD" -- $publicPath `
155155
156156Read the full diff output. For each changed file, identify:
157157
158- 1 . ** Removed symbols** — functions, classes, methods, constants, exported names that
158+ 1 . ** Removed symbols** - functions, classes, methods, constants, exported names that
159159 existed before and are now gone. ? Strong signal for MAJOR.
160- 2 . ** Changed signatures** — functions that exist in both versions but with different
160+ 2 . ** Changed signatures** - functions that exist in both versions but with different
161161 parameters, return types, or thrown errors. ? Strong signal for MAJOR.
162- 3 . ** New exported symbols** — public functions, classes, constants that didn't exist
162+ 3 . ** New exported symbols** - public functions, classes, constants that didn't exist
163163 before. ? Signal for MINOR.
164- 4 . ** Internal-only changes** — modifications that don't touch any public interface
164+ 4 . ** Internal-only changes** - modifications that don't touch any public interface
165165 (private helpers, unexported functions, algorithm internals). ? PATCH.
166- 5 . ** Bug fixes** — corrections to logic that was provably wrong (e.g. off-by-one,
166+ 5 . ** Bug fixes** - corrections to logic that was provably wrong (e.g. off-by-one,
167167 null check, wrong condition), without changing the public API. ? PATCH.
168168
169169If the diff is very large (thousands of lines), first run the stat summary to
@@ -177,7 +177,7 @@ Focus your detailed reading on files with the most changes and files whose names
177177suggest they define public interfaces (e.g. ` index.* ` , ` api.* ` , ` exports.* ` ,
178178` public.* ` , ` mod.* ` , ` __init__.* ` ).
179179
180- #### 3b — Commit log (secondary signal)
180+ #### 3b - Commit log (secondary signal)
181181
182182``` bash
183183git log " $PREV_SHA " ..HEAD --oneline --no-merges
@@ -193,7 +193,7 @@ Use this to:
193193
194194See ` references/commit-classification.md ` for mapping message patterns to change types.
195195
196- #### 3c — Reconcile the two signals
196+ #### 3c - Reconcile the two signals
197197
198198When signals agree ? use that classification with confidence.
199199
@@ -202,12 +202,12 @@ When signals conflict ? **prefer the code diff**. Examples:
202202- Commit says ` feat: new API ` but the diff only touches private internals ? treat as PATCH.
203203- Commit says ` chore: refactor ` but the diff adds new exported symbols ? treat as MINOR.
204204
205- Document any conflicts you notice — flag them to the user during the changelog review
205+ Document any conflicts you notice - flag them to the user during the changelog review
206206in Step 6.
207207
208208---
209209
210- ### Step 4 — Determine the next SemVer version
210+ ### Step 4 - Determine the next SemVer version
211211
212212Apply these rules to your analysis from Step 3 (full rules in ` references/semver-rules.md ` ):
213213
@@ -237,7 +237,7 @@ Wait for confirmation before proceeding.
237237
238238---
239239
240- ### Step 5 — Create the release branch
240+ ### Step 5 - Create the release branch
241241
242242Now that the version is confirmed, create the branch with the correct name from the start:
243243
@@ -248,7 +248,7 @@ git push -u origin release/vX.Y.Z
248248
249249---
250250
251- ### Step 6 — Update CHANGELOG.md
251+ ### Step 6 - Update CHANGELOG.md
252252
253253Read the existing ` CHANGELOG.md ` (or create it if absent). Follow the
254254[ Keep a Changelog] ( https://keepachangelog.com/en/1.1.0/ ) format strictly.
@@ -279,7 +279,7 @@ Read the existing `CHANGELOG.md` (or create it if absent). Follow the
279279
280280Rules:
281281- Use today's date in ` YYYY-MM-DD ` format.
282- - Omit sections that have no entries — don't leave empty headings.
282+ - Omit sections that have no entries - don't leave empty headings.
283283- Write entries in ** plain English from a user's perspective** , derived primarily
284284 from what the code diff shows, supplemented by commit message context.
285285 Good: * "Added ` WithTimeout ` option to HTTP client constructor."*
@@ -306,7 +306,7 @@ Incorporate feedback, then write to disk.
306306
307307---
308308
309- ### Step 7 — Commit and push
309+ ### Step 7 - Commit and push
310310
311311``` bash
312312git add CHANGELOG.md
@@ -318,7 +318,7 @@ Confirm the push succeeded before moving on.
318318
319319---
320320
321- ### Step 8 — Open a Pull Request
321+ ### Step 8 - Open a Pull Request
322322
323323** ?? IMPORTANT:** Always use ` --body-file ` to pass PR body text, never ` --body ` with inline text.
324324Inline escape sequences like ` \n ` are not interpreted as newlines by PowerShell and will appear
@@ -383,7 +383,7 @@ Paste the changelog section into the PR body's "What's included" block (or leave
383383
384384---
385385
386- ### Step 9 — Hand off to the user
386+ ### Step 9 - Hand off to the user
387387
388388Tell the user:
389389
@@ -422,7 +422,7 @@ Tell the user:
422422## Troubleshooting in PowerShell
423423
424424- If a command that works locally prints gh usage or treats a subcommand as separate token, ensure you' re
425- invoking the gh.exe on PATH (Get-Command gh) and avoid passing unexpanded nested substitutions; use the PowerShell
425+ invoking the gh.exe on PATH (Get-Command gh) and avoid passing unexpanded nested substitutions; use the PowerShell
426426 patterns above.
427427- Recommend tests: gh --version; git fetch --tags; run the PowerShell snippet to set $prevTag and run git diff --name-only $prevSha ..HEAD -- src/
428428
@@ -437,5 +437,5 @@ Tell the user:
437437
438438# # Reference files
439439
440- - ` references/semver-rules.md` — Extended SemVer decision rules and edge cases
441- - ` references/commit-classification.md` — Heuristics for classifying commit messages into change types
440+ - ` references/semver-rules.md` - Extended SemVer decision rules and edge cases
441+ - ` references/commit-classification.md` - Heuristics for classifying commit messages into change types
0 commit comments