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

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 <prefix>/<slug>. 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/<slug>/ 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.