Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mralexivy/AutoMode --skill ship-change -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/ship-change/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ship-change/

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

Similar skills

All skills for Git and GitHub →

From the same set10

The whole set →
explorer The explorer subagent for Claude Code gathers repository facts for a planner. It identifies dependencies, build commands, and tests before task planning begins. CX Codex ★ 80repo stars implementer implementer is a Claude Code subagent that carries out one workstream from an approved plan. It edits its assigned files, adds tests, and runs validation. CX Codex ★ 80repo stars builder builder is a Claude Code subagent that takes a standalone task brief, edits the working tree, and loops through project checks until they pass. Runs for rescue attempts and dedicated build tasks. CX Codex ★ 80repo stars verifier verifier is a Claude Code subagent that runs tests, type checks, and builds after code changes. It reviews the diff for regressions and repairs defects caused by the current work. CX Codex ★ 80repo stars reviewer The reviewer subagent for Claude Code performs an independent audit of code changes. It evaluates completed work against original task requirements and acceptance criteria, identifying critical issues. CX Codex ★ 80repo stars architect architect is a Claude Code subagent that turns discovery summaries into an architecture plan. It assigns file ownership and defines acceptance checks. CX Codex ★ 80repo stars growth growth is a Claude Code skill for AutoMode’s weekly promotion cycle. Ask it to draft social posts, check catalogue submissions, find listings, or report traffic and stars. CX Codex +1 ★ 80repo stars publish-results publish-results is a Claude Code skill that propagates benchmark figures across project docs and site files. Runs before merging release PRs or after altering public metrics. CX Codex +1 ★ 80repo stars

Project sponsors

Companies that keep this analytics open