open-pr

name

open-pr

description

(Team 3M) Open a new GitHub pull request from the current branch, using the repo's pull_request_template.md and a Conventional Commits title. Use this skill whenever the user asks to "open a PR", "create a pull request", "ship this branch", "PR this", "open the PR", or any phrasing about turning the current branch into a GitHub pull request. Also trigger on casual phrasing like "raise a PR", "make a PR", or after a sequence of commits when the user says "let's get this reviewed". The skill uses the `gh` CLI to push the branch (if needed), generate a Conventional Commits title via the `conventional-commit` skill, fill in the team's PR template, and create the PR against `main`.

Open PR Skill

This skill turns the current branch into a GitHub pull request against main. It always uses the repo's .github/pull_request_template.md and a Conventional Commits title. The title is generated by delegating to the [[conventional-commit]] skill — never hand-rolled — so the team's commit style stays consistent between commits and PR titles.

Preconditions

Before doing anything destructive (push, gh pr create), verify the environment:

1. The working directory is a git repository on a branch other than main. If on main, stop and ask the user which branch should become the PR.

2. There are commits ahead of origin/main. Run git rev-list --count origin/main..HEAD. If zero, stop — there is nothing to open a PR for.

3. The working tree is clean. If git status --short shows uncommitted changes, stop and ask the user whether to commit, stash, or abandon them. Never silently include unrelated edits in the PR push.

4. gh auth status succeeds. If not, ask the user to run ! gh auth login themselves.

5. No open PR already exists for this branch. Check with:

   gh pr view --json number,state 2>/dev/null
   

   If one exists and is OPEN, stop and surface the existing URL. If it is CLOSED/MERGED, confirm with the user before opening a new one.

Step 1: Push the Branch

If the branch has no remote tracking ref, push with -u:

git push -u origin HEAD

If it already tracks a remote, just git push. Surface any non-zero exit from this step before continuing — never attempt to open a PR for a branch the remote does not know about.

Step 2: Resolve the Issue Reference

The team's template reads Closes # — a missing issue number leaves a dangling reference in the description, which is worse than no reference. Resolve it like this:

1. If the branch name starts with <number>-... (e.g. 20-import-financial-transactions-from-csv), use that number. This is the dominant convention in this repo.
2. Otherwise, search recent commits on the branch (git log origin/main..HEAD --pretty=%B) for any #NN reference and ask the user to confirm.
3. If neither yields a number, ask the user for the issue number explicitly. Accept "none" as an answer — in that case, remove the Closes # line from the body entirely rather than leaving a broken Closes #.

Verify the issue exists with gh issue view <N> --json number,title,state -q '{number, title, state}'. If the state is CLOSED, flag it to the user before proceeding.

Step 3: Generate the Title

Title format must be Conventional Commits: <type>(<optional scope>): <description>, lowercase type, lowercase description, no trailing period, under 70 characters.

Delegate the title to the [[conventional-commit]] skill — do not write it manually. Feed the skill the diff and commit log so it can pick a type and scope consistent with the repo's history:

git log origin/main..HEAD --pretty='%s%n%n%b'
git diff origin/main...HEAD --stat

If multiple commits are in the branch, the title should describe the net change of the PR, not echo any single commit. The skill is good at this when given the log + diff stat. Pass the result to the user for one-line confirmation before using it — title typos are visible in every notification, so the brief approval check is worth it.

Examples of acceptable PR titles for this repo:

• feat: import financial transactions from CSV
• fix: tighten csv import validation and error responses
• chore: add agent skills for PR review and PR creation
• docs: rewrite README with project description, setup, structure, and UML models

If a ! breaking-change marker belongs in the title, include it (feat!: drop /v1 endpoint). The [[conventional-commit]] skill handles that judgment.

Step 4: Fill In the Template

Read .github/pull_request_template.md from the repo root. Fill each section based on the diff and commit history. Preserve the template's structure exactly — do not reorder, rename, or remove sections.

Two constraints:

• If no issue was resolved in step 2, remove the Closes # line entirely rather than leaving Closes # with no number.
• Leave the checklist boxes unchecked — the author ticks them in the GitHub UI.

If the diff contains UI changes, add a <!-- attach screenshot --> comment as a reminder.

Step 5: Create the PR

Use gh pr create with the title from step 3, the body from step 4, --base main, and --head defaulting to the current branch. Pass the body via a heredoc so newlines and # characters survive shell expansion:

gh pr create --base main --title "<title>" --body "$(cat <<'EOF'
<rendered template body>
EOF
)"

Capture the returned URL and return it to the user as the final line of the response — the user will click it.

Do not add --draft unless the user asked for a draft, do not assign reviewers (the team has CODEOWNERS for that), do not add labels.

Step 6: Summarize

End the turn with:

• The PR number and URL.
• The title that was used.
• The issue it closes (or a note that none was linked).
• A one-line reminder of any UI screenshots or manual checklist items the author still needs to complete in the GitHub UI.

Nothing else. The PR description carries the rest.

Failure Modes to Watch For

• Branch already has an open PR: never silently overwrite or amend an existing PR via this skill. Surface the URL and let the user decide whether to update the description manually.
• Pre-commit hooks reject the push: if git push fails because of a hook, do not retry with --no-verify — fix the underlying issue (formatter, secret scanner) and push again.
• No issue number derivable: better to omit Closes # than to leave a malformed reference. The template will still render fine.
• Heredoc shell escaping: backticks and $() inside the body must be escaped or the heredoc tag (<<'EOF') must be quoted, otherwise the shell will execute them. Always use the quoted heredoc form above.
• Empty diff against main: if the branch is fully merged or rebased away, gh pr create will fail with "No commits between main and ..." — stop and tell the user; do not invent commits.