---
name: ship
description: Takes a finished change to an open pull or merge request, then stops so the user merges and releases. Runs self-review and a done gate, scans the diff for a lowered bar (new suppressions, skipped or deleted tests, removed assertions, stubs), commits in logical pieces, then interviews the user about the feature and checks each answer against the code before anything is pushed; on branches the deliver skill marked, a global git pre-push hook blocks any push without the interview and a prove receipt. Use when the user says ship it, ready to ship, wrap this up, we're done, push this, open a PR or MR, create a merge request, or asks for a rollback plan, a deploy or release checklist, a version bump, a tag or a changelog, or to clean up after a merge. Not for reviewing someone else's PR - use `review`; not for adding telemetry or alerts - use observability.
title: ship
canonical_url: https://skilld.dev/gh/avik-creator/agent-skills/ship
last_updated: 2026-11-17T15:45:41.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/deploy.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/deploy.md), [references/done.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/done.md), [references/hook.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/hook.md), [references/interview.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/interview.md), [references/release.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/release.md), [scripts/bar-guard](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/scripts/bar-guard), [scripts/pre-push](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/scripts/pre-push).
>
> If the user asked to install this Skill, run `npx skilld install avik-creator/agent-skills/ship`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ship`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/avik-creator/agent-skills/ship) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ship`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ship --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ship --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Ship

Nothing leaves this machine until the change is checked, the bar is intact, and the user can explain what is going out. The agent prepares and pushes the branch; the user merges, deploys and tags.

## Quick start

1. Check the state, and turn on the global hooks.
2. Self-review with `review`, then the done gate and `scripts/bar-guard`.
3. Show the commit plan; commit after a yes.
4. Interview the user ([interview.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/interview.md)) and write the record.
5. Show the push and the PR or MR; run them after a yes. Stop.

## Workflow

### 1. Check the state
- On the default branch: propose a branch name and create it after a yes. Why: nothing is ever pushed to the default branch.
- Find the host from `git remote -v`: GitHub uses `gh`, GitLab uses `glab`. Say "PR" or "MR" to match.
- Run `<skill dir>/../_hooks/install`, then `install check`, without asking, as [hook.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/hook.md) says. Tell the user in one line if it turned the hooks on, or why they can't run in this repo. They check only branches `deliver` marked. Why: the user wants the push checks for deliver work only.

### 2. Self-review and the done gate
- Run `review` on the change if it has not run since the last edit. Fix its Blockers and Fixes as it says.
- Walk the done gate in [done.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/done.md). Report each item as done, not applicable (with the reason), or missing.
- Run `scripts/bar-guard`. Each hit is shown to the user with a reason or fixed; none is dropped quietly. Why: a red check turned green by silencing it is the cheapest way to lower the bar.

### 3. Commit
- Group the changes into commits, one logical change each, with refactors apart from behaviour. Show the plan: files and message per commit.
- After a yes, commit. Stage only that commit's files by name, never `git add -A` or `git add .`. Why: a stray file rides along unseen. A hedged answer ("I guess", "probably") is not a yes. Before each commit, run `git diff --cached -i -G'password|secret|api_key|token' --name-only`; any output is read before going on.
- Messages: a short subject, and a body saying why. No AI attribution trailer. Never `--no-verify`. Why: it skips every hook, the linters too.

### 4. Interview
Run [interview.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/interview.md) on the committed change. When it ends, write the record so the hook knows:
```sh
rec="$(git rev-parse --git-common-dir)/ship/<branch>"
mkdir -p "$(dirname "$rec")" && printf 'head %s\n' "$(git rev-parse HEAD)" > "$rec"
```
The record is a file. A branch name with `/` (`feat/x`) makes folders above it, so create only its parent folder. Why: `mkdir -p` on the record's own path makes a folder the hook can't read.
A fix made during the interview is committed before the record is written.
The user may skip the interview: write the record and say in the reply that it was skipped. A skip covers that interview only; after new commits, ask again about the short re-interview. Never skip it unasked, and never call it compulsory. Why: it teaches and never blocks, but the choice is the user's.

### 5. Push and open the PR or MR
- The commit being pushed needs a passing `prove` receipt. Run `prove` if it has none, and again after any commit made in steps 2 to 4. Why: the hook blocks a push whose exact commit wasn't proved.
- Show the exact commands and the description; run them after a yes:
  - GitHub: `git push -u origin <branch>`, then `gh pr create --base <default> --title "<title>" --body-file <file>`
  - GitLab: `git push -u origin <branch>`, then `glab mr create --target-branch <default> --title "<title>" --description "<text>" --yes`. Never `--fill` or `--push`. Why: both push without the shown command.
- Write the title and description with the `writing-pr` skill. The verification results go in chat, not in the description.
- Stop. Never merge, approve, or push to the default branch.

### 6. When the hook blocks a push
New commits since the interview: run a short interview on only those commits, then update the record and push again. A `prove:` block: run `prove` on that commit and push again. `SHIP_SKIP=1` and `PROVE_SKIP=1` are the user's call for one push; never suggest them yourself.

### 7. After the merge
When the user says it is merged, list what to clean up: the local branch, worktrees and review copies for it, `.prototype/` folders for it, `.git/ship/<branch>`, and the deliver mark `.git/deliver/<branch>`. Show each before deleting; delete after a yes. Why: a worktree can hold uncommitted work.

## Example

User: "Ship it." Branch `fix/retry-dupes`, 3 files changed.
1. `review`: clean. Done gate: all done; docs not applicable (no visible change). `bar-guard`: one hit, `t.Skip` in `retry_test.go`. Asked; the user says remove it; removed, tests pass.
2. Commit plan: 1 commit, "fix: make webhook retries idempotent". Yes, committed.
3. Interview: 7 questions, 5 right, 1 partly, 1 wrong (the retry cap is 3 in `retry.go:41`, not 5). Record written.
4. No prove receipt for the commit: ran `prove`. Retry flow PROVED by a subagent.
5. Showed `git push -u origin fix/retry-dupes` and the PR text. Yes: pushed, PR opened. Stopped.

## Replies

Talk to the user in simple English: short sentences, everyday words, and a technical term only where it is needed, explained the first time it appears.

## References

- [references/interview.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/interview.md) - read before the interview, and for a short re-interview after new commits.
- [references/done.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/done.md) - the done gate, and what to do with bar-guard hits.
- [references/hook.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/hook.md) - read at step 1, or when the hook blocks.
- [references/deploy.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/deploy.md) - read only when the user says the change is being deployed.
- [references/release.md](https://skilld.dev/api/skills-raw/avik-creator/agent-skills/ship/references/release.md) - read only for a version bump, a tag or a changelog.
