| name | ship-it |
| description | Push the current branch to GitHub and create a pull request. Use this skill when the user says "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review", "get this reviewed", or wants to push their work and open a PR. Also use when the user says "/ship-it". This skill handles prerequisites, branching, pushing, and PR creation — it does not commit or run quality checks (use checkpoint for that first).
|
Ship It
Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
This skill complements checkpoint. Use checkpoint to commit locally (with quality gates), then ship-it to get the code to GitHub for review.
Instructions
Step 0: Prerequisites
Verify tooling before doing anything else.
-
GitHub CLI installed?
gh --version
If the command fails (not found):
- Detect the platform and attempt to install:
- Windows:
winget install --id GitHub.cli
- macOS:
brew install gh
- Linux (Debian/Ubuntu): follow the official apt instructions
- If auto-install fails, tell the user what to install and stop.
-
GitHub CLI authenticated?
gh auth status
If not authenticated, tell the user:
GitHub CLI is not logged in. Please run this in the prompt:
! gh auth login
Then re-run /ship-it.
Stop here — do not proceed until auth is confirmed.
-
Git remote exists?
git remote -v
If no remote named origin exists, stop and tell the user:
No git remote found. Add one with:
git remote add origin https://github.com/{user}/{repo}.git
Step 1: Detect the Environment
Run these commands to understand the current state:
git branch --show-current — get the current branch name- Detect the default branch:
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
git status --porcelain — check for uncommitted changes
If there are uncommitted changes, stop and tell the user:
You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.
Store the default branch name for use throughout the remaining steps.
Step 2: Check for Unpushed Commits
Determine if there are commits that haven't been pushed yet.
If on a feature branch with a remote tracking branch:
git log @{upstream}..HEAD --oneline
If on a feature branch with no remote tracking branch, or on the default branch:
git log origin/{default_branch}..HEAD --oneline
If there are no unpushed commits, stop and tell the user:
Nothing to ship — all commits are already pushed.
Save the list of unpushed commit messages for use in later steps.
Step 3: Handle Branching
If already on a feature branch (not the default branch):
- Stay on it. No branching needed.
- Skip to Step 4.
If on the default branch:
Step 4: Push to Origin
git push -u origin {branch_name}
If the branch already has a remote tracking branch, a regular git push is fine.
Step 5: Check for Existing PR
Before creating a new PR, check if one already exists for this branch:
gh pr view --json number,url,title,state 2>/dev/null
If a PR already exists and is open:
- Do NOT create a new one
- Skip to Step 7 and report the existing PR with a note that new commits were pushed.
If no PR exists (or it is closed/merged), proceed to Step 6.
Step 6: Create the Pull Request
Generate the PR title and body from the unpushed commits:
- Title: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
- Body: TL;DR of the changes in 2-4 bullet points max.
gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
## Summary
{2-4 bullet points}
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
Step 7: Report
Display the result clearly:
Shipped to GitHub:
Branch: {branch_name}
PR: #{number} — {title}
URL: {url}
Important
- Do NOT run lint, type-check, or build — that is checkpoint's job
- Do NOT commit anything — only push existing commits and create a PR
- If the user has uncommitted changes, tell them to run /checkpoint first
- Keep the PR body short — a TL;DR, not an essay
- Always check for an existing open PR before creating a new one to avoid duplicates
- Detect the default branch dynamically — do not hardcode
main or master
- When creating a branch from the default branch, use conventional prefixes (
feat/, fix/, etc.) with kebab-case names
- Never run destructive git operations (no
--force, no reset --hard)
- If
gh is not installed or authenticated, help the user get set up before proceeding
