Pull Request

Pull Request

Pushes the current branch and creates a GitHub Pull Request via gh pr create, auto-filling any detected PR template from commit context and linked Issues.

Modes

Check first: does docs/agents/pull-requests.md exist?

• No → Init: run the interview (see [INTERVIEW.md](INTERVIEW.md)), write config, then proceed to pre-flight.
• Yes → Proceed: load config, run pre-flight.

Pre-flight checks

Run all four in parallel:

• git remote get-url origin — remote URL (fails if no remote)
• git log --oneline -1 — confirms at least one commit exists
• git status --short — uncommitted changes
• git status -sb — remote tracking state and branch name

Then, in order — abort early if any check fails:

1. No remote — if git remote get-url origin fails: abort. "No remote named origin is configured. Add one with git remote add origin then re-run."

1. No commits — if git log returns empty: abort. "No commits found. Make at least one commit before opening a Pull Request."

1. Uncommitted changes — if dirty and the user has not already indicated what to do: ask. Suggest /commit if available, otherwise suggest committing manually. Do not proceed until the working tree is clean.

1. Current branch — if on the configured target branch and allow-direct-push is false: abort with guidance. Example: "You're on main. Create a feature branch first (/create-branch)."

1. Remote tracking state:

• Branch not yet pushed → push in step 1 of the workflow.
• Branch already pushed, no PR open → skip to PR creation.
• Branch already pushed, PR already open → report the existing PR URL and stop.

Workflow

1. Push branch (if not yet pushed) — run git push -u origin . Never force-push.

1. Load PR template — read the template value from config:

• none: check for newly added templates (.github/PULL_REQUEST_TEMPLATE.md, .github/PULL_REQUEST_TEMPLATE/*.md; org-level via gh api repos//.github/contents/.github/PULL_REQUEST_TEMPLATE.md). If found, ask the user whether to use one and update config. Otherwise skip to step 4b.
• Repo-level (Level: repo): read the file at the stored Path from the working tree. If the file is missing, warn ("PR template at `` not found — proceed without template, or fix config first?") and act on the user's choice.
• Org-level (Level: org): fetch with gh api repos//contents/ — decode the content field from base64. If the response is not 200, warn ("PR template fetch failed — gh api repos//contents/ returned ``. Proceed without template, or fix config first?") and act on the user's choice.

1. Build PR title — infer from commit subjects:

• Single commit → use its subject line directly.
• Multiple commits → derive a one-line summary that captures the shared intent.

1. Build PR body:

Treat commit messages and the diff as source material for understanding what changed — not as text to copy into the PR body. Synthesize a description of the changes in your own words.

• Template found (4a): synthesize content for each section of the template from the commit messages and diff context. Shape the language to fit the intent of each section — a "Summary" section gets a prose overview, a "Test plan" section gets a checklist of what to verify, and so on. Extract the Issue Number from the branch name (/-). If the template contains a section for issue references (e.g. "Closes", "Fixes", "Related issues"), inject Closes # there. Do not append it outside the template.
• No template (4b): synthesize a short prose description of the changes. Append Closes # on its own line at the end if an Issue Number is present in the branch name.

1. Validate and fix body — run [validate.sh](validate.sh):

• If exit 0: body is valid, continue.
• If exit 1: read the VIOLATION: lines from stderr. Apply fixes using your own judgment, then re-run the script on the corrected body. Repeat until exit 0.

Never present a body that has not passed validation.

1. Present and confirm — show the proposed title, body, target branch, and draft status. Allow the user to edit any field. Do not call gh pr create until the user confirms.

1. Create PR — run:

``sh gh pr create \ --title "" \ --body "" \ --base \ [--draft] ``

Report the PR URL when done.

Key rules

• Never force-push.
• Never call gh pr create without explicit user confirmation of title and body. A prior approval from another skill in the same chain does not carry over.
• gh CLI is the only interface for GitHub operations. Do not use the REST API directly.
• If gh is not authenticated, pause and guide the user through gh auth login before continuing.
• allow-direct-push applies only to the configured target branch. Any other branch may be pushed freely.
• Write all generated PR body prose as unwrapped lines — do not insert hard line breaks within paragraphs or list items. Commit message bodies are hard-wrapped at 72 chars for git log; reflow them (collapse single newlines into spaces, preserve double newlines as paragraph breaks) before including them in the PR body.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dnd-mapp
• Source: dnd-mapp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.