PR Description Writer
Claude CodeSKILL.mdProductivity
Turn a branch diff into a reviewable pull request description: what changed, why, how it was tested, with risks and review guidance called out.
Use when: Use when opening a pull request or when an existing PR description leaves reviewers to reverse-engineer intent from the diff.
Get this skill
Add the skill file with the CLI, by hand, or over MCP.Save this to your project or home directory so Claude Code can load it.
npx goodprompts add pr-description-writerSaves to
~/.claude/skills/pr-description-writer/SKILL.mdnpx goodprompts add pr-description-writerSaves to
~/.claude/skills/pr-description-writer/SKILL.mdSkill file
SKILL.md3,052 characters# PR Description Writer
The description's job is to let a reviewer approve confidently in one pass. Write it from the diff, not from memory.
## Process
1. Read the actual diff first: `git diff main...HEAD --stat`, then the full diff. Also read the commit messages — they often contain "why" that belongs in the description.
2. Identify the one-sentence purpose. If you need "and" twice, the PR should probably be split — say so before polishing prose.
3. Fill the template below. Every claim about behavior must be something you verified, not something you intended.
## Template
```markdown
## What
One short paragraph: the user-visible or system-visible change.
Bullet the noteworthy implementation points (3-6 bullets max) —
the decisions a reviewer can't infer from the diff alone.
## Why
The problem or requirement, with a link (issue, incident, thread).
If you chose between approaches, one line on the rejected
alternative and why.
## How tested
- [ ] Unit/integration tests added or updated: name the key cases.
- [ ] Manual verification: exact steps you ran and what you observed.
- [ ] Not tested: anything you knowingly didn't cover, and why.
## Risk & rollout
- Blast radius: what breaks if this is wrong.
- Migrations/flags/config: ordering requirements, default states.
- Rollback: revert-safe, or does it need steps? Spell them out.
## Review guide
- Start with <file> — it's the core change; the rest follows from it.
- <file/dir> is mechanical (rename/generated/formatting), skim it.
- Open question for reviewer, if any.
```
Delete sections that genuinely don't apply (a docs-only PR needs no rollout plan) — but "How tested" never gets deleted, even if its content is "rendered the page locally".
## Rules
- **Screenshots/recordings for anything visual.** Before/after side by side for changes; one shot for new UI, including empty and error states if they changed. For CLI changes, paste terminal output in a code block.
- **The "Not tested" line is mandatory honesty.** Reviewers calibrate their attention on it; an empty risk section reads as "didn't think about it", not "no risk".
- **Call out the scary part yourself.** If there's a tricky concurrency change or a query rewrite, point the reviewer at it. Hiding it in mechanical noise is how bugs get approved.
- **Size guidance for the reviewer beats apologies for size.** If the PR is large, the Review guide section ("90% is the codegen in /gen; the real change is 60 lines in router.ts") is what makes it reviewable.
- Title follows the repo's commit convention (`feat(auth): magic-link expiry`), since it usually becomes the squash commit.
- No fabricated checkboxes. An unchecked box with a reason is fine; a checked box that didn't happen is not.
## Final pass
- [ ] A reviewer with no context could state the purpose after the first paragraph.
- [ ] Every test claim corresponds to something that actually ran.
- [ ] Visual change → image attached; behavior change → test named; risky change → risk named.
- [ ] Links resolve (issue, design doc, incident).