How to use the Ship a Pull Request agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. This skill is for work that is finished and needs to ship as a pull request, or for maintaining an existing PR. Its description says it covers creating, syncing, updating metadata, checking status, monitoring CI, and addressing review comments on a PR.

It is explicitly not for reviewing a pull request you are not shipping. The skill is scoped to your own work. Unfinished work that still needs design or implementation belongs to other workflows first.

• Creates the PR once the work is committed and checked
• Brings the PR up to date with its base branch and resolves conflicts
• Edits the PR title and body, using the repository's PULL_REQUEST_TEMPLATE.md when present
• Adds or refreshes screenshots
• Reports checks and merge status, and handles review comments
• The agent re-checks repository state before each push or PR edit
• It only reports a PR as merge-ready when GitHub confirms it; otherwise it reports the status as observed

Install the shipping-a-pr skill

Download the skill ZIP from this page and unzip it. Then place the skill folder in one of two locations. Use ~/.claude/skills/ to make it available across your projects, or use a project's .claude/skills/ folder to make it available only in that repository.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: upload under Settings → Capabilities → Skills

What you need before you start

The skill drives git and the GitHub CLI, so both must be available. The repository must be hosted on GitHub, and the GitHub CLI must be authenticated to that repository. The skill also runs scripts and uses the network, because it pushes branches and calls GitHub.

• git installed and working in the repository
• GitHub CLI (gh) installed and authenticated to the repository
• A repository hosted on GitHub
• Finished work on a branch, committed to git

How to trigger the skill with natural requests

You do not need special syntax. Describe what you want in plain language, and the agent matches the request to the right phase of the skill. The skill's phase table maps asks to phase docs. Creating a PR, syncing with the base, updating the title or body, refreshing screenshots, reporting checks once, monitoring CI, and addressing review comments each route to their own document.

A compound request such as rebasing, verifying and creating a PR is treated as one flow that starts at the earliest phase you name.

• Create a PR for this branch, the work is finished
• Bring this PR up to date with main and resolve conflicts
• Update the PR title and body to describe the new behaviour
• Show me the current checks and merge state for this PR
• Monitor CI on this PR and fix failing checks until it is green
• Address the review comments on this PR

Snapshot mode and wait mode

Snapshot mode is the default. The agent takes one fresh snapshot of checks and merge state, reports pending, failing or indeterminate state as observed, and stops. A push does not switch the skill into monitoring on its own.

Wait mode runs only when you explicitly ask for remote completion, such as watching checks, waiting until green, or making the PR merge-ready. In wait mode, done means every configured check is green, the head is current with its base, and GitHub reports an affirmative merge state. A repository with no CI is reported as exactly that, never as silently green.

• Snapshot: default for creating, syncing, updating and one-time status requests
• Wait: only when you explicitly ask the agent to monitor, wait, or make the PR merge-ready
• A requested draft is reported as draft, never as merge-ready

Safety notes: scripts, network and irreversible actions

This skill runs scripts and uses the network. It performs irreversible actions, including git push, gh pr create and gh pr edit. The skill re-checks the exact state before each of these steps, but you should still decide whether an agent may run them unsupervised. Do not use it in repositories where you do not want an agent pushing or opening PRs without oversight.

Working files are kept under the workspace's gitignored .thinkrail/context/ folder, including pr-body.md and pr-shots/. These are deleted when the phase that made them completes, except that screenshots stay while you upload them by hand.

• Review the branch and the PR body before asking the agent to ship
• Keep the skill out of repositories where unsupervised pushes are not acceptable
• Expect .thinkrail/context/ to hold temporary files during a phase

Tips for getting reliable results

Commit everything that should ship before you ask, because the skill checks that the worktree is clean and ignores work git does not hold. Give the agent a clear mode in your request, so it knows whether you want a snapshot or a watch. When you ask for PR body changes, the skill fetches the current body before editing so it does not overwrite concurrent edits.

• Commit first: uncommitted and untracked files will not reach the PR
• Say whether you want a status snapshot or for the agent to wait for CI
• Let the skill fetch the current title and body before it edits them