---
name: pr-description-writer
description: "Generate PR descriptions reviewers actually read — summary, test plan, screenshots, breaking changes. Reads the diff + commit history, drafts a PR description with the structure that reviewers want: 1-paragraph summary, bulleted test plan, breaking-change callout, before/after screenshots, related-issue links."
license: MIT
---

# PR Description Writer

PR Description Writer drafts a complete pull-request description from your actual changes — the diff, the commit messages, and the branch's relationship to its base. It's for engineers who open several PRs a week and want reviewers to grasp the change in thirty seconds instead of reverse-engineering it from a code dump. The output follows the structure reviewers consistently ask for: a tight summary, a real test plan, an explicit breaking-change callout, screenshot placeholders, and linked issues.

## When to use it

- You've finished a feature branch and `git log` reads like "wip", "fix", "more fix".
- A refactor touches 30 files and the diff alone won't tell a reviewer *why*.
- Your team enforces a PR template and you keep leaving the test-plan section empty.
- You're filing several stacked PRs and want each description scoped to just its own commits.

## How it works

The skill runs against your current branch. It computes the diff with `git diff <base>...HEAD` (defaulting `<base>` to the repo's default branch, or whatever you pass), pulls commit subjects and bodies via `git log`, and reads changed-file paths to infer the surface area. From that it produces Markdown with these sections:

- **Summary** — one paragraph, what changed and the motivation, not a file list.
- **Test plan** — bulleted, derived from touched test files and changed behavior; flags untested paths.
- **Breaking changes** — only emitted when the diff touches public signatures, configs, migrations, or removed exports.
- **Screenshots** — before/after placeholders inserted when UI files (`.tsx`, `.vue`, CSS, etc.) changed.
- **Related issues** — scrapes `#123` / `JIRA-456` / `Closes ...` references from commits and branch name.

It emits to stdout, or with `gh` present, opens the PR directly.

## Usage

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/pr-description-writer/SKILL.md https://claudeskil.com/skills/pr-description-writer/SKILL.md

# draft against the default base branch
pr-desc

# explicit base, write to file, then open the PR
pr-desc --base main --out PR.md
gh pr create --body-file PR.md

# stacked PR: only this branch's own commits
pr-desc --base feature/parent
```

## Tips & gotchas

- **Write decent commit subjects.** The summary leans on commit messages; a wall of "fix" commits yields a vaguer summary. Squash-and-clean before running for the best result.
- **Screenshots are placeholders, not captures.** It inserts the Markdown image scaffold and an upload reminder — it can't render your UI. Drag images into the GitHub editor afterward.
- **The base matters for stacked PRs.** Without `--base`, a stacked branch will include the parent's commits in the summary. Always set `--base` to the immediate parent.
- **Breaking-change detection is conservative.** It triggers on signature/export/migration changes, so a behavior change behind an unchanged signature may not be flagged — review that section.

## FAQ

**Does it push or open a PR by itself?**
No. It prints Markdown by default. Opening a PR only happens if you pipe the output to `gh pr create` yourself.

**Will it leak secrets from the diff?**
It reads tracked changes only; anything in `.gitignore` never enters the diff. Still skim the summary before posting.

**Can I enforce my team's template?**
Yes — point it at a template file and it fills your sections rather than its defaults.