ship-release-skill 0.0.0-stage → 0.1.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "ship-release",
+  "owner": { "name": "joezhuo2" },
+  "plugins": [
+    {
+      "name": "ship-release",
+      "source": "./",
+      "description": "Ships a release end to end: bump manifests, changelog, README badges, tag, GitHub release, npm publish and check."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "ship-release",
+  "version": "0.1.2",
+  "description": "Ships a release end to end: bump manifests, changelog, README badges, tag, GitHub release, npm publish and check.",
+  "author": { "name": "joezhuo2" },
+  "repository": "https://github.com/joezhuo2/ship-release-skill",
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joezhuo2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+<h1 align="center">ship-release</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/ship-release-skill"><img src="https://img.shields.io/npm/v/ship-release-skill?logo=npm&color=orange" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/ship-release-skill"><img src="https://img.shields.io/npm/dt/ship-release-skill?logo=npm&color=blue" alt="npm downloads"></a>
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="platform: Windows | macOS | Linux">
+  <a href="https://code.claude.com/docs/en/plugins"><img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757?logo=claude&logoColor=white" alt="Claude Code plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-18%2B-5FA04E?logo=nodedotjs&logoColor=white" alt="Node 18+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/joezhuo2/ship-release-skill?color=green" alt="license"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#what-it-does">What it does</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#files">Files</a> •
+  <a href="#development">Development</a> •
+  <a href="#license">License</a>
+</p>
+
+> ship-release is a Claude Code skill that ships a release of the project you
+> are in, the same way every time: bump every version manifest, write the
+> changelog, fix README badges, commit, tag, create the GitHub release, then
+> publish to npm and check the registry.
+
+## Install
+
+Pick one. All of them install the same plugin.
+
+- **npx:** nothing stays installed besides the plugin.
+
+  ```bash
+  npx ship-release-skill
+  ```
+
+- **npm, global:** installs the `ship-release-skill` command, which you then run once.
+
+  ```bash
+  npm i -g ship-release-skill
+  ```
+
+  ```bash
+  ship-release-skill
+  ```
+
+- **Claude Code plugin marketplace:** run these inside Claude Code.
+
+  ```
+  /plugin marketplace add joezhuo2/ship-release-skill
+  /plugin install ship-release@ship-release
+  ```
+
+Restart Claude Code afterwards. The skill needs `git` and the
+[GitHub CLI](https://cli.github.com) (`gh`), and `npm` for npm packages.
+
+## What it does
+
+| Step | What happens |
+|------|--------------|
+| Pick the version | Uses the one you gave, or proposes patch / minor / major from the commits since the last tag. |
+| Preflight | Clean tree, default branch or a release branch, up to date, tag is free, `gh` and `npm` logged in, version not on npm, tests pass. |
+| Bump manifests | Greps the old version and bumps `package.json`, lockfile, `.claude-plugin/plugin.json`, `marketplace.json`, `pyproject.toml`, `Cargo.toml` and version constants. |
+| Changelog | Adds a dated section in the file's own format, written from the commits. |
+| README | Updates hardcoded version badges and pinned install lines; leaves dynamic badges alone. |
+| Confirm | Shows the version, files and changelog section, and asks once before anything goes public. |
+| Commit, land, tag | Release commit in the repo's style, pushed directly or through a pull request, then an annotated tag. Never `--force`. |
+| Pull request route | On a branch, in a worktree or with a protected default branch: pre-PR check, open the PR, fix conflicts, wait for checks, merge, then remove the worktree and branch. |
+| GitHub release | Waits for a tag-triggered release workflow if the repo has one, otherwise `gh release create` with the changelog section. |
+| npm | Publishes unless a workflow does or the package is private, then checks the registry shows the new version. |
+| Report | Version, tag, release URL, npm URL, and anything skipped or failed. |
+
+After a push it only fixes forward: no moved tags, no force-push, no `npm unpublish`.
+
+## Usage
+
+Ask in plain words, in the project you want to release:
+
+```
+ship a patch release
+```
+
+```
+release v0.3.0
+```
+
+Or call the skill directly:
+
+```
+/ship-release:ship-release minor
+```
+
+## Files
+
+| Path | Purpose |
+|------|---------|
+| `skills/ship-release/SKILL.md` | The release procedure Claude follows. |
+| `.claude-plugin/` | Plugin manifest and marketplace entry. |
+| `bin/install.js` | The `npx ship-release-skill` installer. |
+| `test.js` | Self-test: versions agree and the skill is well formed. |
+
+## Development
+
+```bash
+npm test
+```
+
+## License
+
+[MIT](LICENSE)

package/bin/install.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+
+for (const cmd of [
+  'claude plugin marketplace add joezhuo2/ship-release-skill',
+  'claude plugin install ship-release@ship-release',
+]) {
+  console.log(`> ${cmd}`);
+  try {
+    execSync(cmd, { stdio: 'inherit' });
+  } catch {
+    console.error(`Failed: ${cmd}. Is the Claude Code CLI installed and on PATH?`);
+    process.exit(1);
+  }
+}
+console.log('ship-release is installed. Restart Claude Code, then ask Claude to "ship a release".');

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "ship-release-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Claude Code skill that ships a release: bump manifests, changelog, README badges, tag, GitHub release, npm publish and check.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joezhuo2/ship-release-skill.git"
+  },
+  "bin": {
+    "ship-release-skill": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".claude-plugin"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-plugin",
+    "skill",
+    "release"
+  ]
+}

package/skills/ship-release/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ship-release
+description: Use when the user asks to release, ship, publish, cut or tag a version of a project ("release v0.2.0", "ship a patch", "bump and publish"). Bumps every version manifest, updates CHANGELOG and README badges, commits, lands it directly or through a pull request (pre-PR check, conflict fixes, merge, worktree cleanup), tags, creates the GitHub release, and publishes to or verifies npm.
+argument-hint: "[version | patch | minor | major]"
+---
+
+# ship-release
+
+Release the current project end to end. Requested version or bump: $ARGUMENTS
+
+Run the steps in order. Stop and report as soon as a step fails; never skip ahead.
+
+## 1. Pick the version
+
+- Last release: `git describe --tags --abbrev=0` (no tag yet means this is the first release; use the manifest version).
+- If the user gave a version or `patch` / `minor` / `major`, use it.
+- Otherwise propose one from `git log <last-tag>..HEAD --oneline`: breaking change is major (minor while on 0.x), new feature is minor, anything else is patch. Ask once.
+- Keep the repo's tag style (`v1.2.3` or `1.2.3`), taken from the existing tags. Default `v`.
+
+## 2. Preflight
+
+All of these must pass before any file changes:
+
+- `git status --porcelain` is clean, or holds only changes meant for this release. Ask about anything else.
+- After `git fetch`, you are on the default branch and not behind its upstream. On any other branch, or in a linked worktree (`git worktree list`), the release goes through the PR route in step 7.
+- The tag does not exist: `git tag -l <tag>` and `git ls-remote --tags origin <tag>` are both empty.
+- `gh auth status` succeeds.
+- If `package.json` exists and is not `"private": true`: `npm whoami` succeeds and `npm view <name>@<version> version` finds nothing.
+- The project's tests pass (`npm test`, or whatever the README or CI uses).
+
+## 3. Bump every manifest
+
+Find every place the old version lives:
+
+```bash
+git grep -nF "<old-version>" -- . ':!CHANGELOG.md' ':!*lock*'
+```
+
+Usual places:
+
+| File | How |
+|------|-----|
+| `package.json`, `package-lock.json` | `npm version <new> --no-git-tag-version` |
+| `.claude-plugin/plugin.json` | `version` |
+| `.claude-plugin/marketplace.json` | `version` of each plugin entry, if present |
+| `pyproject.toml`, `setup.py`, `__version__` | edit |
+| `Cargo.toml` | edit, then `cargo check` to refresh `Cargo.lock` |
+| `manifest.json`, version constants in source | edit |
+
+Read each grep hit before changing it: bump the project's own version, not a dependency that happens to share the number. Run the grep again afterwards; every remaining hit needs a reason.
+
+## 4. Changelog
+
+- Follow the format the file already uses. If there is no `CHANGELOG.md`, create one in Keep a Changelog format.
+- Add `## [<new>] - <YYYY-MM-DD>` above the previous release, built from `git log <last-tag>..HEAD`.
+- Group as Added / Changed / Fixed. Write what changed for the user, not commit subjects. Leave out version bumps and merge commits.
+- If there is an `[Unreleased]` section, move its entries into the new section and leave the heading empty.
+- Update the compare links at the bottom if the file has them.
+
+## 5. README
+
+- Dynamic badges (`img.shields.io/npm/v/...`, `github/v/release/...`) update themselves. Leave them.
+- Update hardcoded versions: static badges (`badge/version-1.2.3-...`), install lines pinned to `@1.2.3` or `#v1.2.3`, "current version" text.
+- If the release adds a command, option or install step the README does not mention, add it.
+
+## 6. Check, then confirm
+
+- Run the tests again.
+- npm package: `npm pack --dry-run` and read the file list. No secrets, no missing files.
+- `git diff --stat` and read the diff for secrets (tokens, `.env`, keys).
+- Show the user the version, the changed files and the new changelog section. Ask once before step 7, unless they already told you to release without asking. Everything after this point is public and cannot be undone.
+
+## 7. Commit, land, tag
+
+Stage only the release files. Use the message style of earlier release commits (`git log --oneline -20`); default `Release v<new>`.
+
+Pick one route to get the commit onto the default branch:
+
+- **Direct:** you are on the default branch, it is not protected and the repo does not release through PRs. `git push origin <branch>`.
+- **PR:** anything else. Follow the PR route below.
+
+Then tag the commit that is on the default branch: `git tag -a <tag> -m "<tag>"` and `git push origin <tag>`. Never `--tags`, never `--force`.
+
+### PR route
+
+1. **Branch.** If you are on the default branch, `git switch -c release/v<new>` before committing. Otherwise keep the branch you are on.
+2. **Pre-PR check.** All must pass before the push:
+   - `git fetch origin`, then `git merge origin/<default>`. Resolve conflicts as in step 4 below.
+   - `git diff origin/<default>...HEAD --stat` lists only files meant for this release. Read the diff for secrets and leftover debug code.
+   - The tests pass on the merged result.
+   - `gh pr list --head <branch>` shows no open PR for this branch. If one exists, reuse it.
+3. **Open the PR.** `git push -u origin <branch>`, then `gh pr create --base <default> --title "Release v<new>" --body-file <file>` with the new changelog section as the body.
+4. **Fix conflicts.** `gh pr view --json mergeable,mergeStateStatus`. If it reports `CONFLICTING`:
+   - `git fetch origin && git merge origin/<default>`. Never rebase or force-push a pushed branch.
+   - Version manifests take the new version. In the changelog, keep the entries from both sides, the new section on top.
+   - In code, keep the intent of both sides. If you cannot tell what the other side meant, stop and ask.
+   - Run the tests, commit the merge, push.
+5. **Checks.** `gh pr checks --watch`. If one fails, read `gh run view --log-failed`, fix, push, and watch again.
+6. **Merge.** Use the method earlier PRs used (`gh pr list --state merged --limit 5 --json mergeCommit,title`); default `gh pr merge --squash --delete-branch`. In a linked worktree leave out `--delete-branch` and run `git push origin --delete <branch>` afterwards. If a review is required, stop and ask the user for it. Never `--admin`.
+7. **Sync.** In the main checkout: `git switch <default>` and `git pull --ff-only`. This is the commit to tag.
+8. **Delete the worktree, if the branch lived in one.** From the main checkout:
+   - `git worktree remove <path>`. No `--force`: if git refuses, show the user the files left in it and ask.
+   - `git branch -d <branch>`. After a squash merge git refuses; confirm `gh pr view <number> --json state` says `MERGED`, then use `-D`.
+   - `git worktree prune`.
+
+## 8. GitHub release
+
+Read `.github/workflows/` first.
+
+- A workflow that runs on tag push and creates the release: do not create one yourself. `gh run watch` it, then `gh release view <tag>`.
+- Otherwise: write the new changelog section to a temp file and run `gh release create <tag> --title <tag> --notes-file <file> --verify-tag`. Add `--prerelease` for `-rc`, `-beta` or `-alpha` versions.
+
+## 9. npm
+
+Skip if there is no `package.json` or it is private.
+
+- A workflow that runs `npm publish`: wait for it instead of publishing yourself.
+- Otherwise `npm publish` from the tagged commit. Add `--access public` for a scoped package's first publish and `--tag next` for prereleases.
+- If npm asks for a one-time password or browser login, stop and ask the user to run `npm publish` themselves. Never ask for or type their password or token.
+- Verify: `npm view <name>@<new> version` prints the version. The registry can lag; retry for up to a minute. Then check `npm view <name> dist-tags.latest`.
+
+## 10. Report
+
+Give the version, the tag, the release URL, the npm URL, and anything skipped, failed or not verified.
+
+## When something goes wrong
+
+- Before the push: fix it and amend freely.
+- After the push: never move or delete a pushed tag, never force-push, never `npm unpublish`. Fix forward with a patch release.
+- PR merged but not tagged: tag the merge commit on the default branch and carry on from there. Do not open a second PR.
+- Tag pushed but `npm publish` failed: fix the cause and publish again from the tagged commit. Do not retag.
+- Release workflow failed: read `gh run view --log-failed`, fix forward, and tell the user what state the tag, the release and the registry are in.