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.
Install the skill
Use it in any agent that supports the open skills format.
npx skills add rafaelmedian/skills@review-ready-prsThe 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.