PR workflow skill: reviewer-focused PR body format with What / How to Verify / Breaking Changes — keeps PRs concise and scannable for humans

SKILL.md

name	pr-workflow
description	Full PR procedure: upstream vs origin detection, PR_BODY.md flow, gh pr create invocation. Loaded on PR intent ('open a PR', 'open the PR', 'create the PR').

PR Workflow

Loaded skill: pr-workflow

Procedure

1. Detect fork vs own repo

Run git remote -v to identify upstream vs origin. Derive <origin-owner> by parsing the origin remote URL (e.g., git remote get-url origin — extract the owner/org segment from the URL).

• If upstream remote exists → fork repo: use --repo <upstream-owner/repo> and --head <origin-owner>:<branch>
• If no upstream → own repo: use --repo from origin, omit --head

2. Handle stale artifacts

If a leftover PR_BODY.md from a prior interrupted run exists, overwrite it with the current PR body. Do not stage it into any commit.

3. Write PR body

Write PR body to PR_BODY.md at repo root. This file is excluded by the commit-workflow suspicious-pattern list; do not stage it.

4. Create PR

• Fork layout: gh pr create --title "<title>" --body-file PR_BODY.md --draft --head <origin-owner>:<branch> --repo <upstream-owner/repo>
• Own repo: gh pr create --title "<title>" --body-file PR_BODY.md --draft --repo <origin-owner/repo>

Omit --base to let gh default to the target repo's default branch (handles repos using master, main, or other defaults).

Default to --draft for all new PRs.

5. Cleanup

Delete PR_BODY.md after the PR is created successfully.

PR Body Format

## What
<1-3 sentence summary of what this PR introduces and why>

## How to Verify
<!-- Concrete, executable steps a human can follow to confirm the changes work. -->
<!-- This is the most important section. Be specific. -->
1. ...
2. ...

## Breaking Changes
<!-- List any breaking changes and migration steps, or write "None" -->

No Co-Authored-By: line by default. Same rationale as commit messages. If a repo's local convention prescribes Co-Authored-By:, follow the local convention.

Failure-Path Cleanup

If the skill exits non-successfully after writing PR_BODY.md (e.g., gh pr create returns non-zero, authentication error, remote not configured, user cancel), delete PR_BODY.md before exiting so no stale workflow artifact persists.

Rules

• The skill defaults to --draft for new PRs.
• The skill SHALL NOT invoke gh pr merge or any merge operation. Merge is out of scope; the user or a separate flow handles merging.
• Repo-local conventions (project-level AGENTS.md) take precedence over the defaults in this skill when they conflict.
• The PR body is for human reviewers, not a status dashboard. Do NOT include:
  • Checklists ("- [x] Task 1")
  • "Tasks completed" or "Review findings" sections
  • Internal references (spec names, worktree paths, agent names)
  • Walls of AI-generated text. Keep it concise — the reviewer also reads the diff.
• The "How to Verify" section is mandatory. Give reviewers concrete, executable steps.
• When updating an existing PR (e.g., stacked work), append new changes rather than overwriting the original description. Use gh pr edit <number> --body-file PR_BODY.md with the combined old + new body.