Make pull requests easier to review
A pull request is often the last place where the work is still easy to understand. The branch has the decisions, the failed attempts, and the checks that finally passed. After it merges, most of that context disappears unless the commits and the pull request carry it forward.The diff says what. I still need the why.
I want the review to explain itself before someone opens the diff. A reviewer should be able to see what changed, why it changed, how the work was divided, and what proof belongs beside it. That makes the review faster now, but the larger benefit arrives months later when the same page becomes the history of the decision.
I turned those preferences into a small skill called review-ready-prs. It reads the repository's own instructions first, then helps an agent shape the commits, write the pull request, and put the evidence where the reviewer will actually find it.
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. The result should let someone compare the UI and understand the reason for the change without running 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. A small flow diagram is more useful here than a screenshot of an unchanged page.
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. This makes the skill useful as a final review pass as well as a guide while building.
A small fix on GitHub
The notes Back-button fix is a compact example of these conventions. Its description names the visible problem, separates the layout correction from the regression test, and reports both the targeted pass and the failures in the wider suite. That last detail lets the reviewer distinguish what was verified from what still needs attention.
These screenshots show real pull requests from this site. They illustrate the review format; they are not a claim that the skill generated those earlier descriptions.
A larger change on GitHub
The photo-wall PR needs more room. Its opening describes the finished interaction, then the ordered list traces the changes that made it possible. A reviewer can follow framing, layout, gestures, and tests as separate decisions instead of unpacking one large implementation summary.
For a change like this, I would also ask the skill for a short recording of selecting, panning, and closing the wall. The commit list explains the work; a recording shows whether the interaction holds together.
The story starts in the commits
A useful commit is small enough to name. Its title says what it does in the present tense, and its body records the thing that was missing or wrong. If a measurement, constraint, or failure made the change necessary, that belongs there too. Fix styles cannot carry any of that weight.
The order matters as much as the wording. A refactor that makes room for a feature should land before the feature. Generated output should be tied to the source change that produced it, or separated clearly when it deserves its own checkpoint. Each commit should leave the project in a state another person can inspect without mentally borrowing half of the next one.
That history gives the pull request its natural outline. Instead of inventing a summary after the work is done, the PR can walk through the same changes in the order they landed and explain each one in plain language.
Put the proof next to the explanation
Visual changes need visual evidence. I want matched before-and-after screenshots for a static interface, and a short recording when timing, focus, scrolling, or another interaction is the point. The reviewer should not have to check out a branch just to learn whether the card moved or the transition still makes sense.
Changes without a visible surface still need a picture of the idea. A small ASCII map can show a request moving through a new boundary, a file becoming the source of generated output, or a data field reaching the component that renders it. It does not have to look formal. It has to use the names that a person reading the repository will recognize.
The evidence belongs in the pull request itself. A path on one person's computer is not part of the record, and a note that says screenshots are coming is not finished review material. When an agent cannot upload the media, the skill keeps the PR as a draft and leaves the prepared files ready for that last handoff.
A checklist should still sound like a person
Structure helps, but it can also flatten the writing. I do not want every pull request to begin with the same sentence about improving an experience. The description should use the nouns from the work, mention the actual tradeoff, and say exactly which checks ran. If a test failed, that is more useful than a polished claim that everything was verified.
The skill does not grant itself permission to rewrite history, push a branch, publish a pull request, or mark a draft ready. It works inside the authority the request already gave it. That boundary is part of making the output trustworthy: a careful description is not useful if it quietly performs a different operation behind it.
This is the first tool in a small public library. I expect the wording to change as I use it on real work. That is another reason to keep it as a skill rather than a paragraph I paste into every repository: the habit can improve in one place while each project keeps its own local rules.The first user of the skill is this PR
Acknowledgements
The skill grew from the commit and pull-request conventions used on this site. Its examples are generic so another repository can keep its own voice.