Shape pull requests a reviewer can actually hold in their head, through small size, a why-first description, and a self-review pass. Use when opening a pull request or preparing a change for review.
Installs into .claude/skills of the current project.
Are you the author of Pr Authoring?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/amey-thakur-pr-authoring)
---
name: pr-authoring
description: Shape pull requests a reviewer can actually hold in their head, through small size, a why-first description, and a self-review pass. Use when opening a pull request or preparing a change for review.
---
# PR authoring
A pull request is a request for someone else's attention and judgment. A
reviewer holds a small change well and skims a large one, so a 1000-line PR
collects a rubber stamp exactly where it most needs scrutiny. Shape the PR
so a careful reader can keep the whole change in their head.
## Method
1. **Keep it under 400 lines of diff.** Defect detection falls off a cliff
past a few hundred changed lines. If the work is bigger, split it: a
refactor PR, then the feature PR stacked on top. Two readable PRs beat one
boulder.
2. **Lead the description with why, then what.** First paragraph: the problem
and the approach. Then the notable decisions and trade-offs. Link the
issue for backstory rather than making the reviewer reconstruct intent
from the diff.
3. **Do the first review yourself.** Before requesting anyone, read your own
diff top to bottom in the PR view. That is where you catch the stray
`console.log`, the commented-out block, the file you did not mean to
touch. Fix them so the reviewer spends on logic.
4. **Annotate the non-obvious inline.** Leave author comments where a choice
looks odd: "kept the loop instead of `map` because it short-circuits."
Steer the reviewer past questions you can already answer.
5. **Separate mechanical commits from meaningful ones.** A pure rename or
format pass in its own commit lets the reviewer skim it and focus on the
behavior commit. A mixed commit forces line-by-line reading of noise.
6. **Green the checks before requesting review.** CI passing, tests added,
lint clean. A red PR says "not ready" and burns a review cycle.
Requesting review is a claim that you believe it is mergeable.
## Checks
- Is the diff small enough that a reviewer can read every line in one
sitting?
- Does the description answer why before what?
- Did your own pass catch anything the reviewer should not have had to?
## Boundaries
Large mechanical migrations (a codemod, a dependency bump touching many
files) are legitimately big: flag them as such and point reviewers at the
few files that need real eyes. Defer to the team's PR template and merge
policy where one exists.
