Ship Pr

Ship PR

A repo-agnostic worktree -> branch -> PR -> squash-merge -> cleanup workflow. Works in any git repo with an origin remote and gh configured; the scripts detect the package manager and default branch rather than assuming pnpm/Turborepo/main.

This is the atomic unit of the ship stack: parallel-ship and epic-ship both call this skill internally (per fanned-out agent and per phase respectively). Invoke it directly for anything that is one PR-sized change.

> Naming note: if a repo you work in defines its own project-level ship-pr skill (tuned to that repo's quirks), rename this personal-level copy (e.g. ship-pr-global) - in Claude Code's skill resolution, a personal-level skill overrides a project-level one of the same name, so an identical name would silently shadow the tuned version.

Step 1: Pick the branch type

| Change scope | Prefix | | ---------------------------------------- | ---------- | | Docs only (markdown, docs/**) | docs/ | | New behavior | feat/ | | Bug correction (behavior existed, broke) | fix/ | | Tooling/refactor, no behavior change | chore/ | | Production is broken right now | hotfix/ |

If unsure between feat/ and fix/: did this behavior exist and work correctly before? Correcting it is fix/. Adding something new is feat/.

Step 2: Worktree -> implement -> verify -> ship -> merge -> cleanup

1. Worktree: bash ${CLAUDE_SKILL_DIR}/scripts/worktree-new.sh /. Run from anywhere inside the target repo. It fetches the remote default branch (detected locally via refs/remotes/origin/HEAD, falling back to a git remote show origin network call only if that's unset, then to main), creates .worktrees// at the repo root (added to .gitignore automatically if missing), installs dependencies with whatever package manager the repo's lockfile indicates, and copies untracked .env* files from the repo root if present.
2. Implement: do the actual work. Implement directly rather than just writing a plan, unless the user asked for a plan. For large files (200+ lines), make incremental targeted edits rather than rewriting the whole file in one shot.
3. Verify - do not skip, do not just document it: check package.json (or the repo's equivalent - Makefile, Cargo.toml, etc.) for what's actually available and run it:

• A build script (build, compile) if present.
• A typecheck script (typecheck, tsc, or tsc --noEmit directly) if the repo is TypeScript.
• The test suite (test).
• Lint (lint) if configured.
• UI/visual change: run the app, take a screenshot, and actually look at it (use a screenshot-verification skill if you have one).
• Deps added/updated: install with --frozen-lockfile/ci (not a plain install) to catch a drifted lockfile the way CI would.
• Markdown touched: the skill-scoped hook on this skill greps added lines in every touched .md file for em-dashes before git push/gh pr create and blocks if it finds any. Note this checks the diff, not the whole file - if this repo's CI whole-file-scans touched markdown (verify by checking the CI config), pre-existing em-dashes you didn't write can still fail CI even though this hook passed.
• If the repo has branch protection requiring CI to pass, wait for it. If it doesn't (check repo settings or just try merging), CI is a second-opinion signal - don't sit and wait on a slow/queued run when the manual checks above already cover it.

Recommended CI job naming, if this repo is setting up checks from scratch: docs-check for doc-only PRs (link/em-dash checks), code-quality for lint, unit-tests for the test suite - scoped by changed-path so doc-only PRs skip the code checks.

1. Ship: commit, push, gh pr create --fill.
2. Merge: note that on private repos under GitHub's free plan there is no branch protection at all - nothing platform-side stands between a green PR and the default branch, so this skill's rules are the actual merge gate. The policy:

| Change | Merge behavior | Why | | --- | --- | --- | | Docs-only | Self-merge immediately | Trivial verification, nothing platform-side to wait for | | feat / fix / chore | Self-merge after verification | Same default; step 3 just has more to clear first | | Payments, auth, data-integrity | Leave PR open for human review | The one exception - never self-merge, even on green CI |

Glance at gh pr checks . Still running/queued and not required to merge -> proceed, don't block on it. Red for something step 3 already predicted and fixed -> proceed. Red for something unpredicted -> stop and investigate before merging, don't merge blind. Otherwise: gh pr merge --squash --delete-branch, then bash ${CLAUDE_SKILL_DIR}/scripts/worktree-close.sh immediately, not "later" - don't batch cleanup.

Hard rules

• Never push directly to the default branch. Every change is its own PR.
• Fork fresh from the remote default branch (worktree-new.sh does this automatically) - never build on top of another unmerged branch.
• Close the worktree immediately after merge.
• One PR-sized change per invocation. If what you're doing is several independently shippable PRs from one analysis pass, use parallel-ship instead. If it's sequential dependent phases (PR N+1 builds on PR N), use epic-ship - it calls this skill once per phase in order.
• High-risk changes (payments, auth, data-integrity, anything a human should eyeball before it goes live) should not self-merge on green CI - leave the PR open for human review instead of completing step 5 automatically.

Enforcement

The skill-scoped hook (scripts/check-em-dashes.sh) fires on every git push/gh pr create while this skill is active and blocks on em-dashes added to touched markdown. It cannot catch everything CI might check (lockfile drift, lint, types, whole-file em-dash scans) - the manual verify step above still matters.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidtheproduct
• Source: davidtheproduct/claude-ship-skills
• License: MIT

Install and usage instructions live in the source repository linked above.