Draft Pr Description Agent Skill

PR Description Generator

Writes a GitHub PR title and description from the diff between two local git branches, focused on what reviewers need: purpose, key decisions/assumptions, behavioral or conceptual changes, and a brief testing note if relevant. Uses only standard git commands, so any agent can follow it.

Arguments

Two optional positional arguments — base branch, then target branch:

• Base: $base
• Target: $target

An empty value means "not provided" — default it per the resolution below (a missing argument is defaulted, not guessed). A target cannot be given without a base.

1. Resolve branches

• Both named → use as given.
• Only one named → it's the base; target defaults to current branch.
• None named → base defaults to main, then master if main doesn't exist (git branch --list). Only check these two names — no scanning other branches, no guessing. If neither exists, stop and ask. Target defaults to current branch (git branch --show-current).

State the resolved base/target before proceeding.

2. Diff

• Confirm both branches exist (git branch --list <name>); stop if not.
• git diff <base>...<target> and git log <base>..<target> --oneline
• Empty diff → stop and say so, don't fabricate a description.

3. Analyze

From the diff/log, identify: purpose of the change; key decisions and trade-offs; assumptions the code relies on; behavioral changes (concrete: "X now rejects Y" not "changed validation"); conceptual/contract changes; breaking changes, new config/env vars, migrations; test changes (what new tests cover conceptually, why existing ones were adapted — not test-by-test).

Skip routine stuff (formatting, trivial renames). No file/line enumeration — write like explaining to a teammate, not a changelog.

4. Output structure

Write to prDescription.md (repo root, overwrite if exists):

# <Title — imperative, <70 chars>

## Summary
<2-3 sentences>

## Key Decisions & Assumptions
<bullets — omit if none>

## Behavioral / Conceptual Changes
<bullets, concrete — omit if none>

## Testing
<2-3 sentences, only if diff touches tests — omit otherwise, don't write "no tests">

## Notes
<breaking changes, follow-ups — omit if none>

Keep it brief (readable in under a minute, ~150-200 words total unless the change is genuinely large). Omit empty sections rather than padding them. Never fabricate testing details, tickets, or names not evidenced in the diff — flag uncertainty in Notes instead.

5. Confirm

After writing, give a short confirmation (don't reprint the file) and offer to run gh pr create --title "..." --body-file prDescription.md if gh is available. Include the provided/resolved base and target branch names into the suggested command as part of the suggestion. At the end, ask if the user wants to open the PR now and wait for confirmation before proceeding. If the user declines, stop and say the PR description is ready in prDescription.md.