ship-release
Cut a new semver release for this project — analyze commits since the last tag, recommend a major/minor/patch bump, draft English release notes with AI, get user confirmation, then bump `package.json`, commit, create the GitHub release with `gh release create`, and let the existing `.github/workflows/release.yml` pipeline handle Docker + npm publishing. Use this skill whenever the user says "发个 release", "发新版本", "ship a release", "bump version", "cut v1.2.0", "tag a release", "/ship-release", or otherwise asks to publish a new version. Also use to preview what the next release would contain ("what's in the next release?", "show release diff since last tag").
camtrik · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add camtrik/agent-trail --skill ship-release技能说明
name: ship-release
description: Cut a new semver release for this project — analyze commits since the last tag, recommend a major/minor/patch bump, draft English release notes with AI, get user confirmation, then bump package.json, commit, create the GitHub release with gh release create, and let the existing .github/workflows/release.yml pipeline handle Docker + npm publishing. Use this skill whenever the user says "发个 release", "发新版本", "ship a release", "bump version", "cut v1.2.0", "tag a release", "/ship-release", or otherwise asks to publish a new version. Also use to preview what the next release would contain ("what's in the next release?", "show release diff since last tag").
Release Workflow
This project publishes via tag-triggered GitHub Actions. When a tag v* is pushed (or a release is created with gh release create), .github/workflows/release.yml runs Docker build → npm publish in parallel. Release notes are written by AI (this skill), not auto-generated by GitHub.
What this skill does and doesn't do
Does:
- Reads commits since last tag, recommends semver bump per conventional commits
- Drafts English release notes, grouped by type, with the user able to edit before publishing
- Bumps
package.jsonversion, commits aschore(release): vX.Y.Z - Creates the GitHub Release via
gh release createwith the AI-written notes (this also creates and pushes the tag) - Reports the workflow run URL for the user to monitor
Doesn't:
- Publish to npm directly — the GitHub Actions workflow does that on tag push
- Build Docker images — same, workflow handles it
- Create release notes by hand without AI input — the whole point is AI drafts them
Two modes
- Preview — just analyze and report; no writes. Use when the user asks "what's in the next release?" or "show me what would go into a release". No version bump, no commit, no tag.
- Publish — the full flow below. Default when the user asks to release / ship / bump version.
If unclear, ask: "Preview only, or actually publish?"
Pre-flight checks (always, both modes)
Run in parallel:
git rev-parse --show-toplevel # confirm we're in the repo
git branch --show-current # must be main
git status --porcelain # must be empty (for publish mode)
git fetch origin main --tags # sync tags and main
git describe --tags --abbrev=0 # find last tag (may fail if no tags)
gh auth status # gh CLI must be authenticated (publish mode)
Failure modes:
- Not on main — in publish mode, refuse. In preview mode, warn but proceed.
- Dirty working tree — in publish mode, refuse and show
git statusoutput. Don't auto-stash. - Behind origin/main — refuse and tell the user to
git pull --ff-only. - No previous tag — that's the initial release case. Start the version at
v1.0.0unlesspackage.jsonsays otherwise; analyze all commits. ghnot installed or not authenticated — in publish mode, refuse with install instructions:brew install gh && gh auth login.
Step 1 — Analyze commits since last tag
git log <last-tag>..HEAD --pretty=format:'%H%x09%s%x09%b%x1e' --no-merges
Parse each commit as conventional-commits:
feat(scope)?: subject→ category Features, signalminorfix(scope)?: subject→ category Bug Fixes, signalpatchrefactor(scope)?: subject→ category Refactor, signalpatchperf(scope)?: subject→ category Performance, signalpatchdocs(scope)?: subject→ category Docs, signalpatchchore(scope)?: subject→ category Chores, signalpatchtest(scope)?: subject→ category Tests, signalpatchbuild|ci(scope)?: subject→ category Build/CI, signalpatch- Non-conforming subject → category Other, signal
patch
Breaking change detection (any of the following → signal major):
- Subject contains
!before the colon, e.g.feat!:orfeat(api)!: - Body or footer contains a line starting with
BREAKING CHANGE:orBREAKING-CHANGE:
Step 2 — Recommend bump
Aggregate signals: major > minor > patch. The highest signal wins.
Compute next version from the last tag (strip leading v):
major—(X+1).0.0minor—X.(Y+1).0patch—X.Y.(Z+1)
If package.json version disagrees with the last tag, mention it; usually the tag is the source of truth.
Step 3 — Collect closed backlog items
Closed items can live in two places by the time you reach this step:
- Pre-archived in
docs/backlog/_done/vX.Y.Z/*.md— the user (or thebacklogskill) may have already moved items into the folder matching the new version before running ship-release. Check this folder first using the recommended next version from Step 2. If it exists and has.mdfiles, those are the canonical "shipped" set for this release. - Still active in
docs/backlog/*.mdwithstatus: done— items finished since the last release but not yet archived.
Read both, then union them (dedupe by slug — pre-archived wins). The combined set is what goes into the "Closed items" section.
For each item, capture: title, type, slug (filename minus .md), and branch (for the compare link). Also remember whether it was pre-archived or still active — Step 7 only needs to move the still-active ones.
If both sources are empty, skip the "Closed items" section entirely.
Why check the version folder first: the user frequently pre-archives items via the
backlogskill (commits likedocs(backlog): reorganize done items into vX.Y.Z archive). If you only scan top-level, you'll publish notes with an empty "Closed items" section even though the work is sitting right there in_done/vX.Y.Z/.
Step 4 — Draft release notes
Backlog items are the primary source of truth for release content. Closed backlog items (from Step 3) map directly into Features / Bug Fixes / Refactor by their type f