When to use this
- Opening a pull request for a branch with one or more commits.
- A PR description is stale after new commits were pushed to an existing branch.
- Not for single-commit micro-changes where the commit message already says everything a PR description would -- don't pad for the sake of it.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: pr-description-writer description: Write a pull request description summarizing the full commit range on a branch (not just the latest commit) -- what changed, why, and a concrete test plan for the reviewer. Use when opening or updating a PR. --- # PR Description Writer ## Gather the full picture 1. `git log <base-branch>..HEAD` and `git diff <base-branch>...HEAD` -- review every commit in the range, not just the most recent one. 2. Identify the overall intent: is this one feature, a bundle of related fixes, or a refactor? State that framing up front. ## Structure - **Summary**: 1-3 bullets, what changed and why -- the "why" is what a reviewer actually needs; the diff already shows the "what." - **Test plan**: concrete, checkable items -- what was tested and how (unit tests added, manually verified in X scenario, ran the existing suite). Not "tested it," an actual checklist. - Call out anything risky or non-obvious explicitly: a migration, a behavior change, a dependency bump -- don't make the reviewer discover it by reading every line. ## What to avoid - A description that only reflects the latest commit when the branch has several -- read the whole range. - Padding with obvious restatement of the diff. - Claiming testing that wasn't actually done. ## Output Title (under ~70 characters) and body in the format above, ready to paste into the PR.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /pr-description-writer.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Only summarizing the most recent commit on a multi-commit branch.
- Writing a test plan that's aspirational rather than reflecting what was actually verified.
- Omitting a risky change (migration, breaking API change) that a reviewer needs flagged up front, not discovered mid-review.