ship-change — Claude Code skill: workflow and installation
ship-change is a Claude Code skill that guides repository changes from issue to merged PR. It activates before fixes, features, docs edits, refactors, and release requests.
MIT ★ 80 updated 2026-11-17
npx skills add mralexivy/AutoMode --skill ship-change -a claude-codeWhat ship-change does
ship-change sets a sequence for repository work: one issue, branch, and PR per task. The branch holds the code, tests, benchmark, and results; direct changes to main are forbidden. It also lays out checks with npm run check, claude plugin validate . --strict, and claude plugin test ..
Changes to session behavior need a benchmark on the same branch. The workflow fixes the pass rule first, records expected spend, then runs the experiment and commits its report. Ask the user before a run that consumes usage or money. If published figures change, run publish-results on that branch; documentation edits do not need a benchmark.
What it helps with
- take a repository change from issue to PR
- keep code, tests, and benchmark on one branch
- run checks before opening a PR
- prepare a benchmark and commit its results
- start a release after changes to shipped paths
Example prompts for the agent
- Take this fix from issue to PR using
ship-change. - Set up a branch and benchmark for this behavior change.
- Open a PR for this docs edit and run the required checks.
How to install ship-change
1Skills CLI (Vercel)
npx skills add mralexivy/AutoMode --skill ship-change -a claude-code2Manually: put the files in place
~/.claude/skills/ship-change/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ship-change/
1Skills CLI (Vercel)
npx skills add mralexivy/AutoMode --skill ship-change -a codex2Manually: put the files in place
.agents/skills/ship-change/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mralexivy/AutoMode --skill ship-change -a cursor2Manually: put the files in place
.cursor/skills/ship-change/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mralexivy/AutoMode .claude/skills/ship-change2Manually: put the files in place
.github/skills/ship-change/SKILL.md1Skills CLI (Vercel)
npx skills add mralexivy/AutoMode --skill ship-change -a gemini-cli2Platform CLI
gemini skills install https://github.com/mralexivy/AutoMode --path .claude/skills/ship-changeManually: put the files in place
.devin/skills/ship-change/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ship-change
How do I install ship-change in Claude Code?
Run npx skills add mralexivy/AutoMode --skill ship-change -a claude-code.
What does ship-change do?
It defines a repository workflow from issue creation and a dedicated branch through checks, a PR, and merge. Behavior changes also get a benchmark on the same branch.
Which tools does ship-change use?
The workflow uses git, gh, npm, claude, and node. A benchmark run that consumes usage or money requires the user's approval.
Source text
SKILL.md · MIT
--- name: ship-change description: The required workflow for any change to this repository, from issue to merged PR. Use it before you start a fix, feature, docs change or refactor here, and when asked to create an issue, a branch, a PR or a release. It keeps the release flow correct. --- # Ship a change Every task gets one issue, one branch and one PR. The branch holds the whole task: code, tests, benchmark and results. A task merges only when its evidence is on its branch. Nothing writes to `main` directly. CI enforces the branch and PR rules, so a shortcut fails in the `guard` job. ## 1. Sync ```bash git status --short # stop if tracked files are changed, and ask git switch main git pull --ff-only ``` ## 2. Issue Search first, so you do not open a duplicate: ```bash gh issue list --state all --search "<words>" ``` If none fits, create one. Use the fields of the matching template in `.github/ISSUE_TEMPLATE/`: `bug_report`, `feature_request`, `benchmark_task` or `judge_case`. ```bash gh issue create --title "<short title>" --label <bug|enhancement> --body-file <file> ``` ## 3. Branch Make one branch per task, not one per step. A task is one entity, even when its plan has phases, milestones or numbered parts. Those parts are commits on the task's branch and sections of its one PR. Never open a branch, issue or PR per phase, and never split a task so that its code lands first and its tests or benchmark follow. When you plan a task, write the plan as one branch and one PR with ordered commits. Do not write it as "PR 1, PR 2, ...". Use `<type>/<short-name>`. The type is `feature`, `fix`, `docs`, `chore`, `refactor`, `test` or `bench`. Keep the name to two or three words, in lowercase, with hyphens. ```bash gh issue develop <N> --name feature/release-flow --base main --checkout ``` Always pass `--name`. Without it, the branch takes the whole issue title, and `guard` rejects it. This command also links the branch to the issue. ## 4. Work - Keep to one task, and keep all of it here. Commit each phase of the plan on this branch as it is done. - Add or update a test for each behavior change. - Put the benchmark for the task on this branch, with the code it measures. - If you change a shipped path, add a line under `[Unreleased]` in `CHANGELOG.md`. Shipped paths are `agents/`, `commands/`, `hooks/`, `output-styles/`, `scripts/`, `types/`, `workflows/`, `config.json` and `.claude-plugin/plugin.json`. - Put the line under the right heading, because the heading sets the next version. `Fixed` and `Security` give a patch. `Added`, `Changed`, `Removed` and `Deprecated` give a minor. - Never change `version` in `plugin.json`. The release PR does it. - Never commit on `main`. ## 5. Check ```bash npm run check claude plugin validate . --strict claude plugin test . ``` Fix every failure before you go on. ## 6. Benchmark A change to what a session does needs a benchmark on its branch. That covers routing, model calls, tool gates, agents, the workflow and the guardian. A docs change does not need one, and neither does a fix that a test proves. Say so in the PR when you skip it. 1. Fix the pass rule before any result exists. Add the experiment to `bench/experiments/`, add its arm to `bench/arms.mts` if it needs one, write the veto rules in `bench/experiments/CANARIES.md`, and commit them. 2. State the expected spend. Ask the user before a run that spends usage or money. CI never runs a live benchmark, so this run happens here. 3. Run it on the branch's final code. A run id hashes the plugin code, so a later code change starts new runs. 4. Commit the rows and the report to the branch. 5. If the run changes a number you publish, follow the `publish-results` skill on the same branch. It updates the README, the docs, the comparison and the website together, and `tests/claims.test.mts` blocks the merge until they agree. ```bash node bench/run.mts --experiment <id> --dry-run node bench/run.mts --experiment <id> --out bench/results/<id>.jsonl node bench/grade.mts bench/results/<id>.jsonl --budget-usd <n> node bench/report.mts --manifest bench/results/<id>.manifest.json bench/results/<id>.jsonl ``` - A vetoed result blocks the merge. Fix the code and run again, or close the task. - Never change a pass rule after results exist. - A default of `off` or `shadow` does not replace this step. - Under 30 tasks, a run is a pilot. It can veto a change, and it cannot prove a saving. See `bench/README.md`. ## 7. Pull request ```bash git push -u origin HEAD gh pr create --base main --title "<what changed>" --body-file <file> gh pr checks --watch ``` - Fill in the template in `.github/PULL_REQUEST_TEMPLATE.md`. - The body must contain `Closes #<N>`. - Link the benchmark report, or say why the task needs none. - Write the title as a plain sentence. A squash merge makes it the commit subject on `main`. - Fix any failing check before you report the PR as ready. If a change truly needs no changelog line, add the `no-changelog` label. ## 8. Merge Merge only when the checks and the benchmark pass and the user asks: ```bash gh pr merge <PR> --squash ``` Then go back to step 1 for the next change. Before you merge a release PR, run the `publish-results` skill if any public number or promise changed since the last release. ## What happens next - A merge that changes a shipped path makes the bot open or update the `Release x.y.z` PR from branch `release/next`. - Merging that PR ships. It runs the gate on Linux and macOS, builds and attests the bundle, publishes the GitHub Release, and moves `stable` last. - Users install from `stable`, so `main` can hold unreleased work. - Docs-only merges start no release. Their changelog lines wait for the next one. - To choose the version: `gh workflow run release.yml -f bump=major`. - To test the release path and publish nothing: `gh workflow run release.yml -f dry_run=true`. ## Do not - Push to `main`, or merge with `--admin`. - Merge a task while its benchmark is pending. - Edit `release/next` by hand. The bot force-pushes it. - Create tags, or move `stable`, by hand. - Name a commit `Release x.y.z`. That subject starts a release.
© mralexivy · MIT · mralexivy/AutoMode