# Claude Code PR Description Skill: Free SKILL.md + Template

> Free Claude Code PR description skill: reads the branch diff and fills a template with why, what changed, tests actually run, risks and rollback steps.

URL: https://www.matthewswong.com/en/toolkit/claude-skill-pr-description/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Updated: 13 November 2026
- Checked against: Claude Code 2.1.323 docs

> **Key takeaway:** Drop this folder into your skills directory and Claude writes the pull request description from the branch itself. It reads the commits and the diff against the base branch, then fills a fixed template: summary, why, what changed, how it was tested, risks and rollback, and notes for the reviewer. It lists only tests that were actually run, and it does not push or open the pull request unless you ask.

- Type: Claude skill
- Works with: Claude Code, Git
- Download: [claude-skill-pr-description.zip](https://www.matthewswong.com/downloads/toolkit/claude-skill-pr-description.zip) (5.8 KB)
- License: Free to use, change and share, at work too.

## The files

Exactly what the download contains. Read it first, then copy or download.

### pr-description/SKILL.md

```markdown
---
name: pr-description
description: Writes a pull request description from the branch diff, covering summary, why, what changed, how it was tested, risks and rollback, and notes for the reviewer. Use when the user asks to write a PR description, describe this branch, summarize changes for review, or prepare a pull request or merge request.
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git log *)
---

# Pull request description

Write the description for a pull request from this branch into its base
branch. Every statement must trace to the diff, the commit log or something
the user said in this conversation.

## Steps

1. Find the base branch. Use the one the user named. Otherwise check
   `git branch --list main master develop` and ask if more than one could
   be the target.
2. Run `git status --short`. If there are uncommitted changes, tell the
   user they are not part of the pull request.
3. Run `git log --oneline <base>..HEAD` to list the commits on the branch.
4. Run `git diff --stat <base>...HEAD`, then `git diff <base>...HEAD`, and
   read the diff. For a large diff, read it file by file, most changed
   first.
5. If the branch has no commits ahead of the base, say so and stop.
6. Read [template.md](template.md) and fill every section, following the
   rules below.
7. Show the finished description in one Markdown code block, with a
   suggested title above it.

## Rules for each section

- **Title**: imperative mood, 72 characters or fewer, names the outcome.
- **Summary**: two or three sentences a reviewer can read in ten seconds.
- **Why**: the problem or the request behind the change. Use only reasons
  found in the commits, the code comments, a linked issue or the user's
  words. If the reason is not known, write `[reason needed]` and ask.
- **What changed**: grouped by area or behavior, not a list of files. Call
  out schema changes, new dependencies, config or environment changes and
  anything removed.
- **How it was tested**: list only checks that were actually run in this
  conversation, each with its command and its result. If you ran nothing
  and the user reported nothing, write "Not tested yet" and list what
  should be run. Never write that tests pass without the output.
- **Risks and rollback**: what could break, who is affected, and how to
  undo it (revert the merge, run a down migration, turn off a flag). Say
  so plainly when a rollback is not clean, such as after a data migration.
- **For the reviewer**: the two or three places that deserve the closest
  read, decisions you are unsure about and anything left out on purpose.

## Rules

- Describe only what `git diff <base>...HEAD` contains. Do not describe
  planned work as done.
- Do not invent issue numbers, ticket links, benchmark figures or
  screenshots. Leave a bracketed placeholder for anything the user must
  supply.
- Do not run `git push`, open the pull request or change any file unless
  the user asks for that action in plain words. Writing the description is
  the whole job.
- If the diff contains something that looks like a secret, a key or a
  password, stop and tell the user first.
- Plain words. No praise for the change and no filler such as "this PR
  aims to".

## What to report

1. A suggested title.
2. The description, in a Markdown code block, ready to paste.
3. A short list of open items: placeholders to fill, checks not run, and
   uncommitted changes that were left out.
```

### pr-description/template.md

````markdown
# Pull request body template

Fill every section. Keep the headings. Replace each bracketed part, and
delete a bullet that does not apply instead of leaving it empty.

```markdown
## Summary

[Two or three sentences: what this pull request does and the result for
the user or the system.]

## Why

[The problem or request behind the change. Link the issue if the user gave
one. Write "[reason needed]" if it is not known.]

## What changed

- [Area or behavior]: [what is different now]
- [Area or behavior]: [what is different now]
- Schema, config or dependencies: [changes, or "none"]

## How it was tested

- `[command that was run]`: [result, with the numbers from the output]
- Manual check: [steps taken and what was seen]
- Not run: [checks that still need to be run, or "none"]

## Risks and rollback

- Risk: [what could break and who would notice]
- Rollback: [how to undo it, and anything that makes the undo unclean]

## For the reviewer

- Look closely at: [file or function, and why]
- Unsure about: [a decision that needs a second opinion]
- Left out on purpose: [related work that is not in this pull request]
```

## A filled example

```markdown
## Summary

Adds a CSV export to the orders table. The export respects the active
filters and streams rows, so large result sets do not load into memory.

## Why

Support staff copy orders into spreadsheets by hand. Requested in the
linked issue.

## What changed

- Orders API: new `GET /orders/export` endpoint that streams CSV
- Orders page: an Export button that passes the current filters
- Schema, config or dependencies: none

## How it was tested

- `npm test -- orders-export`: 6 passed, 0 failed
- Manual check: exported 3 filtered orders and opened the file in a
  spreadsheet; columns and totals matched the table
- Not run: the full end-to-end suite

## Risks and rollback

- Risk: an export with no filters reads the whole table; the endpoint is
  limited to signed-in staff
- Rollback: revert the merge commit; no data changes to undo

## For the reviewer

- Look closely at: the stream handling in `export-orders.ts`
- Unsure about: whether the row cap should be configurable
- Left out on purpose: Excel format, tracked separately
```
````

## Use it when

- Your branch is ready for review and the description field is still empty.
- Reviewers keep asking how a change was tested or how to roll it back.
- You want every pull request in the repository to have the same sections.
- An AI-written description once claimed passing tests that nobody ran, and you want that ruled out.

## From download to working

1. **Unzip into your skills folder.** The archive holds one folder, pr-description. Unzip it into .claude/skills/ in your project so the file sits at .claude/skills/pr-description/SKILL.md, or into ~/.claude/skills/ to use it in every project on your machine.
2. **Check that it is listed.** In Claude Code, ask What skills are available? or open /skills and look for pr-description. If the skills folder did not exist when the session started, run /reload-skills first.
3. **Commit your work, then ask.** Commit everything that belongs in the pull request, because uncommitted changes are left out. Then type /pr-description, or ask Claude to write a PR description, and name the base branch if it is not obvious.
4. **Run the tests in the same session.** The testing section holds only checks whose output is in the conversation. Run your test command there, or paste the result, before asking. Otherwise the section reads Not tested yet, with a list of what to run.
5. **Fill the placeholders and paste.** You get a suggested title, the description in a Markdown block, and a list of open items such as a missing reason or an issue link. Fill those in, then paste the result into your pull request.
6. **Make the template yours.** Edit template.md to match the sections your team reviews by. The skill fills whatever headings it finds there, so you change the output without touching the instructions.

## Why it is written this way

- **It reads the branch, not the conversation.** The steps run git log and git diff against the base branch and read the result before writing. Every statement has to trace to the diff, the commit log or something you said.
- **Tests are listed only with their output.** The testing section takes a command and its result, or the words Not tested yet. This is the rule that keeps a description from saying all tests pass when nothing was run.
- **Risks and rollback are required.** The template asks what could break, who would notice and how to undo the change. It also asks the skill to say plainly when an undo is not clean, such as after a data migration.
- **The template is a separate file.** SKILL.md holds the procedure and template.md holds the body, with a filled example. Claude reads the template when it reaches that step, and you can change the sections without rewriting the rules.
- **Placeholders instead of guesses.** A reason, an issue link or a screenshot the skill cannot find becomes a bracketed placeholder and an item in the open list. You see what is missing instead of reading an invented answer.

## What goes wrong

- Uncommitted changes are not in the branch diff. The skill warns about them, but it will not describe them.
- A wrong base branch gives a wrong description. Name the target when your repository has more than one long-lived branch.
- On a very large diff the description gets general. Smaller pull requests get better descriptions and better reviews.
- A skill is guidance, not a lock. To block pushes outright, use a permission deny rule or a hook.

## FAQ

### Does the skill open the pull request for me?

No. Its instructions tell Claude not to push, open the pull request or change files unless you ask for that in plain words. It returns a title and a description for you to paste, and its allowed-tools line pre-approves only git status, git diff and git log.

### How does it know which tests were run?

It only counts checks whose command and output appear in the current conversation, or results you report there. If there are none, it writes Not tested yet and lists what should be run. It is told never to write that tests pass without the output.

### Does it work with GitLab or Bitbucket?

Yes. The skill uses only git commands on your local branch and returns Markdown text, so it does not depend on any hosting service. Paste the result into a pull request or a merge request wherever your repository lives.

### Can I use my team's own pull request template?

Yes. Replace the Markdown block in template.md with your team's headings. The skill reads that file and fills the sections it finds. If you rename the testing or rollback section, update the matching rule in SKILL.md so the two files agree.

## Learn what this file packages

- Free lesson: [Claude Code Skills Examples: Write One That Actually Triggers](https://www.matthewswong.com/en/learn/claude-code-tips/claude-code-skills-examples/)
- Free lesson: [Claude Code Git Workflow: Safe Commits, PRs and Push Rules](https://www.matthewswong.com/en/learn/claude-code-tips/claude-code-git-workflow-safe-commits/)
- [Claude Code Skills: Author On-Demand Procedures](https://www.matthewswong.com/en/blog/claude-code-skills-authoring-guide/)
- [Code Review That Actually Works: A Developer's Process Guide](https://www.matthewswong.com/en/blog/code-review-process-developer/)
- [AI Code Review as a CI Merge Gate: What Should Block](https://www.matthewswong.com/en/blog/ai-code-review-merge-gate-ci/)

## Sources

- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Claude Code docs: skill frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference)

[All toolkit items](https://www.matthewswong.com/en/toolkit/)

---

- HTML version: https://www.matthewswong.com/en/toolkit/claude-skill-pr-description/
- Bahasa Indonesia: https://www.matthewswong.com/id/toolkit/claude-skill-pr-description/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
