| name | squash-merge-and-push |
| description | Use when the user wants a feature branch squash-merged into its base branch and pushed to the remote GitHub repository. This skill performs a non-interactive GitHub CLI workflow: verify repo state, verify or push the feature branch, locate or create the pull request if needed, squash merge it with an explicit subject/body, and confirm the remote base branch now contains the merged work. |
Squash Merge And Push
Use this skill when the user explicitly wants the branch merged, not when they are only asking for a review or status check.
This skill is for a GitHub-hosted repository with gh available.
Core rules
- Prefer GitHub CLI over manual git merge flows.
- Stay non-interactive.
- Do not use
git reset --hard, git checkout --, or interactive git tools.
- Do not merge unrelated local changes by accident.
- Do not guess the base branch if it can be discovered.
- Do not force-push unless the user explicitly asks for it.
Intended outcome
The feature branch changes land on the remote base branch as one squashed commit, and the remote state is verified afterward.
Required workflow
- Confirm you are inside a git repository.
- Inspect local status and identify the current branch.
- Determine the base branch:
- Prefer existing PR metadata via
gh pr view.
- Otherwise infer from repo default branch or explicit user input.
- Check for uncommitted changes.
- If the worktree is dirty:
- only proceed if the user clearly wants those changes included
- otherwise stop and ask
- Ensure the feature branch commits are present locally.
- Ensure the feature branch is pushed to the remote:
- use a normal
git push -u origin <branch> if needed
- never use
--force unless explicitly requested
- Find the PR for the current branch:
- prefer
gh pr view
- if none exists and the user still wants a squash merge, create one with
gh pr create
- Gather or construct merge metadata:
- Squash merge using
gh pr merge --squash.
- Verify the result:
- confirm the PR is merged
- confirm the remote base branch contains the merge result
- Report the merged PR, base branch, and resulting remote state.
Command strategy
Prefer commands in this shape:
git status --short
git branch --show-current
git remote -v
gh pr view --json number,state,headRefName,baseRefName,title,url
git push -u origin <feature-branch>
gh pr create --base <base> --head <feature-branch> --title "<title>" --body "<body>"
gh pr merge <pr-number> --squash --subject "<subject>" --body "<body>"
gh pr view <pr-number> --json number,state,mergeCommit,url
git fetch origin
git log origin/<base> -n 5 --oneline
If the repo uses merge queues or branch protections, let gh pr merge handle that behavior. Do not bypass protections with --admin unless the user explicitly asks for it.
Merge message guidance
Unless the user provided exact text:
- use the PR title as the squash commit subject
- keep the body short and factual
- do not generate marketing language
Dirty tree handling
If there are unstaged or uncommitted changes:
- determine whether they are intended for this merge
- if they are intended, commit them first with a factual commit message
- if they are unrelated or ambiguous, stop and ask
Do not silently stash, discard, or rewrite user changes.
PR creation guidance
If no PR exists for the feature branch:
- create one only if the user asked to merge/publish the branch
- use a factual title derived from the branch work
- keep the description minimal unless the repo clearly expects a template
Verification standard
A successful run must verify all of:
- the PR is in
MERGED state
- the reported merge commit exists remotely, if GitHub exposes one
- the remote base branch shows the new tip or includes the squash commit
If any verification step fails, say so explicitly.
Output format
Use this section order in the final answer.
Result
One short paragraph saying whether the squash merge and push completed.
Details
- repository
- feature branch
- base branch
- PR number and URL
- merge state
- resulting remote branch
Notes
- any branch protection, queue, or verification caveats
- whether the branch was pushed first
- whether a PR had to be created
Failure handling
Stop and explain the blocker if any of these are true:
- not a git repository
gh is unavailable or unauthenticated- current branch cannot be determined
- worktree has ambiguous unrelated changes
- PR creation or merge is blocked by missing permissions
- required checks are pending and the repo cannot merge immediately
If the merge is blocked only by required checks or queueing, report that the merge request was submitted and specify whether GitHub set auto-merge or merge-queue behavior.
Good skill behavior
- Keep the merge path short and deterministic.
- Prefer
gh pr merge --squash over local git merge --squash.
- Verify remote state after the merge, not just local state.
- Surface blockers instead of improvising around them.
