Claude Skill

PR Description Writer

Generates a PR description from a diff — what changed, why, how to test, risks.

Download skill (.zip)Or download whole pack

What it does

Takes a diff (or `git diff main...HEAD`) and produces a PR description that a reviewer can actually act on: what changed, why, the test plan, and the risk surface. Forces you to articulate the "why" so the reviewer doesn't have to reverse-engineer it from the patch.

When to use

✓You're opening a PR and want a description reviewers will actually read
✓The diff is non-trivial and the title alone doesn't carry the context
✓You need to link tickets and call out risk for an on-call team

When not to use

✗Trivial one-line fixes — the title is enough
✗You don't actually understand the change yet — write the code first, then describe it

Install

Download the .zip, then unzip into your Claude skills folder.

mkdir -p ~/.claude/skills
unzip ~/Downloads/pr-description-writer.zip -d ~/.claude/skills/

# Restart Claude Code session.
# Skill is now available — Claude will use it when relevant.

SKILL.md

---
name: pr-description-writer
description: Use when writing a pull request description. Triggers on "PR description", "write a PR", "describe this diff", or pasted `git diff` output.
---

# PR Description Writer

Most PR descriptions are useless because they restate the diff. A reviewer can read the diff. They need the context the diff can't carry: why this change, what was considered and rejected, what to watch for in production.

## Required inputs

Before drafting, confirm you have:

1. **The diff** (or branch name + base — `main...HEAD`)
2. **Linked ticket / issue** if one exists (Jira, Linear, GitHub issue)
3. **The "why"** — what user/system problem this solves
4. **Risk surface** — which services, jobs, or user flows this touches

If the diff is large and the user hasn't told you what they're trying to do, ask before drafting. Don't infer intent from a 2,000-line diff.

## Structure

```
## What

1-3 bullets. Each one a concrete change in plain language.
NOT "Refactored auth" — "Replaced JWT verification middleware with a shared
`requireAuth` helper used by all routes under /api/v2."

## Why

1-2 sentences. The user-visible or system-level reason. Link the ticket.

## How to test

A reviewer should be able to verify locally in <5 min.
- Specific commands (`pnpm test path/to/file`, curl examples)
- Specific UI paths if relevant ("log in as admin → /settings → toggle X")
- What to look for, not just "test it"

## Risk / blast radius

- Which services / endpoints / jobs this touches
- What breaks if this is wrong
- Whether it's behind a feature flag, gradual rollout, etc.
- On-call should know about: [yes/no + why]

## Out of scope

What you intentionally did NOT do, so reviewers don't ask.

## Screenshots / logs (if UI or output)
```

## Anti-patterns

Strip these on sight:
- "Self-explanatory" / "Refactor" / "Misc fixes" as the entire description
- Restating the diff in prose ("This PR changes X to Y") — useless
- "No risk" claims without justification — there's always risk
- Skipping the test plan because "tests pass in CI" — CI doesn't catch UX regressions

## Tone

- Imperative and precise. "Drops the legacy `UserCacheV1` path" beats "Some changes to user caching."
- Reviewers' time is the scarce resource. If your description saves them 2 minutes of reading the diff, you've earned it.
- If something is genuinely subtle ("this changes the order of side effects in the request lifecycle"), say so loudly.

## Output

Markdown. If the diff was large or the user gave thin context, end with a "Reviewer questions" section listing 1-3 specific things to flag for the reviewer's attention.

Example prompts

Once installed, try these prompts in Claude:

Write a PR description for this diff. Ticket is PROJ-1234, and the change swaps our Redis client for ioredis. [paste git diff]
PR description for refactoring the auth middleware to use async context. Risk: every authenticated route. [paste diff]