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

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.