Make pull requests easier to review
A pull request is usually the last place the work still makes sense. The branch knows what I tried, what broke, and which check finally passed. Once it merges, most of that is gone, unless the commits and the PR description kept it.The diff never says why
I want someone to understand the change before they open the diff. What changed, why, and how do I know it works. That speeds up the review, sure. The bigger payoff comes months later, when that PR is the only record of why the code looks the way it does.
So I wrote it down as a skill, review-ready-prs. It reads the repo's own instructions first. Then it helps the agent split the commits, write the description, and put screenshots and test results where a reviewer will see them.
npx skills add rafaelmedian/skills@review-ready-prsThree ways to use it
For a visual fix, try: Use review-ready-prs to prepare this mobile toolbar fix for review. Capture the same viewport before and after, explain the alignment change, and report the checks that actually ran. You should be able to compare the two screenshots and get it without pulling the branch.
For a refactor, try: Use review-ready-prs to separate this data-loading refactor from the behavior change. Explain the old and new request paths, and keep each commit independently reviewable. Here a tiny flow diagram beats a screenshot of a page that looks the same.
For a branch that is already finished, try: Use review-ready-prs to audit this branch and draft its PR description. Match the summary to the commits, identify missing evidence, and do not push or rewrite history. I use this one at the end, as a last check before I ask anyone to look.
A small fix on GitHub
The Back-button fix in the notes reader is a small one. The description says what looked wrong, keeps the layout fix and the regression test as separate changes, and reports the targeted test passing next to the failures in the full suite. I'd rather the reviewer see those failures than find them.
These are real PRs from this site. They show the format. The skill didn't write them; it came after.
A larger change on GitHub
The photo-wall PR is bigger. It opens with what the finished interaction does, then lists the changes in the order they landed: framing, layout, gestures, tests. You can review each one on its own instead of digging through one long summary.
Today I'd also ask for a short recording of opening, panning, and closing the wall. You can't tell from a commit list whether a gesture feels right.
The story starts in the commits
If I can't name a commit in one line, it's probably two commits. The title says what it does. The body says what was wrong, and if a measurement or a failing test forced the change, that goes in too. Fix styles tells you nothing.
Order matters too. The refactor that makes room for a feature lands before the feature. Generated files go in with the change that generated them. And every commit should make sense on its own, without the reader needing half of the next one to follow it.
Get that right and the PR description mostly writes itself. It walks through the commits in order and explains each one.
Put the proof next to the explanation
If the change is visual, show it. Before and after screenshots at the same size, or a short recording when timing, focus, or scrolling is the point. Nobody should have to check out a branch to find out whether the card moved.
Changes you can't see still get a picture. A rough ASCII sketch of where a request goes now, or which file generates which, is enough. It doesn't need to be pretty. It needs to use the same names as the code.
And it goes in the PR, not on my laptop. “Screenshots coming” doesn't count. If the agent can't upload them, the skill leaves the PR as a draft with the files ready for me to drop in.
A checklist should still sound like a person
A template can make every PR sound the same, and I don't want fifty descriptions that open with “This PR improves the experience of.” Use the actual names from the work. Say what the tradeoff was. List the checks that really ran, and if one failed, say so. That's worth more than a clean “all verified.”
It also won't rewrite history, push, open a PR, or mark a draft ready unless you asked for that. A nice description isn't worth much if the agent did something else while writing it.
It's the first thing in a small public library, and the wording will keep changing as I use it. That's why it's a skill and not a paragraph I paste into every repo. I fix it once, and each project still keeps its own rules.Its first real test was this PR
Acknowledgements
The skill came out of how I write commits and PRs on this site. The examples are generic on purpose, so your repo can keep its own voice.