PR Description Writer
Reviewable pull request descriptions generated from the actual diff.
An agent skill that writes pull request descriptions from the real diff: a summary of what changed and why, test evidence, risk assessment, and reviewer guidance on where to focus. Makes agent-authored PRs as reviewable as your best colleague's.
SKILL.md
--- name: pr-description description: Write pull request titles and descriptions. Use when creating or updating a PR. --- # PR Description Writer When creating a pull request, generate the description from the ACTUAL diff (`git diff main...HEAD`), never from memory of the conversation. ## Title - Imperative, under 70 chars, describes the outcome: "Add rate limiting to public API" - Prefix with the ticket ID if the branch name contains one ## Description structure ```markdown ## What & why 2-4 sentences: the problem, the approach chosen, and why this approach over the obvious alternative (if any). ## Changes - Bullet per logical change, grouped by area - Call out anything surprising a reviewer would pause on ## How it was tested - Actual commands run and their results — never claim untested things - If untested, say "Not yet tested: X" explicitly ## Risk & rollout - What could break, blast radius, and how to roll back - Migrations, feature flags, config changes highlighted ## Reviewer notes - The 1-2 files to review most carefully and why - Anything intentionally NOT done in this PR ``` ## Rules - Keep the whole description under 400 words - Never pad sections — write "None" over inventing content - If the diff includes changes unrelated to the goal, list them under "Also included" so reviewers aren't surprised
Try it out
Open in Playground →Run this skill on a real model without leaving the page. Every run is saved to your history for this skill.
How to use
- 1Save as .claude/skills/pr-description/SKILL.md in your repo.
- 2The agent applies it whenever it opens a PR; works with gh CLI and GitHub MCP flows.
- 3Keep your repo's PULL_REQUEST_TEMPLATE.md aligned so human and agent PRs match.
- 4Review the 'How it was tested' section critically — it's the honesty anchor of the whole description.
Examples
Agent opening a PR for a rate-limiter
Input
Agent implemented API rate limiting and opens a PR.
Output
## What & why Public API endpoints had no rate limiting, letting a single client exhaust database connections... chose token-bucket over fixed-window to avoid boundary bursts. ## How it was tested - `pnpm test rate-limit` — 14 passing - Manual: 429 verified after 100 req/min with curl loop ## Reviewer notes - `middleware/rateLimit.ts` holds all the logic — review the Redis fallback path carefully...
Pro tips
- Add a 'Screenshots' section to the structure if your project is UI-heavy.
Frequently asked questions
Why generate from the diff instead of the conversation?+
Long agent sessions drift: the conversation includes abandoned approaches and half-done ideas. The diff is ground truth — generating from it prevents descriptions that describe work that didn't ship.