| name | create-pr |
| description | Create a GitHub pull request with gh, target the correct base branch, push only committed work, and bind related issues via Fixes/Closes keywords. Use when asked to create a PR, open a pull request, push and open PR, link/bind/associate an issue to a PR, add Fixes #N, or close issues on merge. |
Create PR and Bind Issues
Open a reviewable PR from the current branch and attach the right GitHub issues so merge auto-closes them.
Preconditions
- Only committed changes go into the PR. Leave uncommitted/WIP files out (or ask before committing).
- Do not update git config, force-push, or skip hooks unless the user explicitly asks.
- Prefer
gh for all GitHub operations.
Resolve base branch
If the user names a base (e.g. dev/0.8.x, main) → use that exactly.
If the user does not name a base → use the latest dev/<version> branch on origin (semver; treat .x as the highest patch for that minor). Do not hardcode a version.
git fetch origin 'refs/heads/dev/*:refs/remotes/origin/dev/*'
python .agents/skills/create-pr/scripts/resolve_dev_base.py
Use the printed name as <base> everywhere below (git log, git diff, gh pr create --base).
Workflow
1. Inspect branch state (parallel)
After resolving <base>:
git status
git diff
git rev-parse --abbrev-ref HEAD
git status -sb
git fetch origin <base>
git log --oneline origin/<base>..HEAD
git diff --stat origin/<base>...HEAD
gh pr list --head <current-branch> --json number,title,url,state,baseRefName
2. Decide branch / PR shape
| Situation | Action |
|---|
| Open PR already exists for this head | Update it (gh pr edit) or push; do not open a duplicate |
| Head branch was merged earlier; new commits remain | New PR from same or cleaner branch is OK; confirm origin/<base>..HEAD is only the intended commits |
| Mixed concerns on one branch | Prefer a clean branch from origin/<base> + cherry-pick (or ask) before opening |
3. Push, then create
git push -u origin HEAD
gh pr create --base <base> --title "<title>" --body "$(cat <<'EOF'
## Summary
- <1-3 bullets: why / user-visible effect>
Fixes #<issue>
## Test plan
- [ ] <concrete checks>
EOF
)"
On Windows PowerShell, use a here-string for --body instead of bash HEREDOC:
gh pr create --base $base --title "..." --body @"
## Summary
- ...
Fixes #1234
## Test plan
- [ ] ...
"@
Title/body style: match recent repo commits (fix(scope): …, feat(scope): …). Include issue number in title only if helpful; always put a closing keyword in the body (see below).
Return the PR URL when done.
4. Bind relevant issues
Always attach issues the PR actually resolves or substantially addresses.
- Infer candidates from: user message, branch name (
fix/1641-…), commit messages ((#1641)), and gh issue list / gh issue view when needed.
- Put closing keywords in the PR body (preferred) or add them via:
gh pr edit <number> --body "$(…updated body with Fixes #N…)"
- Verify link:
gh pr view <number> --json body,closingIssuesReferences (or check the issue sidebar on GitHub).
Keyword details and multi-issue examples: references/issue-linking.md.
5. After create (optional)
- If the user only asked to bind an existing PR: skip create; edit body / confirm closing references.
- Do not push again unless new commits were added.
Quick checks before opening
