name: watch-and-merge
description: This skill should be used when the user asks to "watch and merge", "merge when checks pass", "wait for CI and merge", "auto merge PR", or needs to monitor CI checks and merge a PR when they pass.
version: 1.0.0

Watch and Merge PR

Watch the CI checks for the current PR and merge it when all checks pass.

Usage

Run from a branch with an open PR.

Workflow

1. Get PR info

gh pr view --json number,url,state,mergeable,mergeStateStatus

Verify:
- PR exists and is open
- PR is in a mergeable state

2. Watch checks

Use gh pr checks with --watch to monitor CI status:

gh pr checks --watch

This will block until all checks complete, showing live status updates.

3. Verify all checks passed

After --watch returns, verify the exit code. A non-zero exit means checks failed.

Alternatively, check explicitly:

gh pr checks --json name,state,conclusion --jq 'all(.conclusion == "success" or .conclusion == "skipped")'

4. Merge the PR

If all checks pass, merge:

gh pr merge --squash

Important: Do not use --delete-branch flag in worktrees. It tries to switch to the base branch locally, which fails if that branch is checked out in another worktree.

5. Clean up the worktree

After successful merge, use the cleanup-worktree skill to:
- Remove Docker containers and volumes (if applicable)
- Remove the worktree
- Delete the local branch

6. Handle failures

If checks fail:
- Report which checks failed: gh pr checks --json name,conclusion --jq '.[] | select(.conclusion == "failure")'
- Do NOT merge
- Inform the user which checks failed

Notes

• Always use gh pr checks --watch - do not write custom polling/watcher scripts
• The --watch flag provides real-time updates in the terminal
• If the PR has merge conflicts, it cannot be merged even if checks pass
• Use --auto flag with gh pr merge if you want GitHub to auto-merge when checks pass (alternative to watching)