good-pr

good-pr


An Agent Skill that helps you craft pull requests maintainers actually want to merge.

Origin

This project was inspired by a tweet from @lukeparkerdev about the reality of community PRs in open source:

> the bottom line with community PRs are they are 99% of the time slop. even in the case that it looks like a good PR, there's suspicious things. this takes the team's time. we have to exactly repro the bug (because there's no steps in the issue/PR), there's a UI change with no before/after screenshots/video, there's terrible code, there's tests that don't test anything...

Rather than complain about bad PRs, we inverted every frustration into actionable guidance. The result is a skill that walks you through exactly what maintainers wish contributors would do.

What It Does

The skill helps you prepare PRs by checking your work against the things that actually matter to reviewers:

1. Reproduction steps — Can a maintainer reproduce the bug from your description alone? 2. Visual evidence — Before/after screenshots or recordings for UI changes 3. Code fit — Does your code match the project's existing patterns? 4. Meaningful tests — Do your tests actually fail when the bug is reintroduced? 5. Focused scope — Is the diff minimal and limited to one concern? 6. Standalone description — Can a reviewer understand the change without pulling the code? 7. Contributor trust — Are you building a track record, or dropping a drive-by PR?

Installation

Install with npx:

npx skills add adewale/good-pr

Skills appear on skills.sh automatically after users install the repo with the skills CLI. Install counts and leaderboard rankings come from anonymous CLI telemetry; opt out with DISABLE_TELEMETRY=1. The repo page customization in skills.sh.json is picked up after the repository is seen by telemetry and the cache refreshes.

Agent compatibility

The installable skill directory is skills/good-pr. It uses the Agent Skills SKILL.md format and is configured for Codex, OpenCode, Pi, Gemini CLI, and Claude Code.

| Agent/client | Install or use | |---|---| | Codex | cp -R skills/good-pr ~/.codex/skills/good-pr | | OpenCode | cp -R skills/good-pr ~/.config/opencode/skills/good-pr or use .opencode/skills/good-pr in a project | | Pi | pi install https://github.com/adewale/good-pr or pi --skill skills/good-pr | | Gemini CLI | gemini skills install https://github.com/adewale/good-pr --path skills/good-pr or copy to .gemini/skills/good-pr | | Claude Code | npx skills add adewale/good-pr or copy to .claude/skills/good-pr |

Or install manually by copying the skill directory:

cp -r skills/good-pr ~/.claude/skills/good-pr

You can also reference it directly in your project's .claude/settings.json.

Structure

skills/good-pr/
├── SKILL.md                      # Main skill instructions
├── references/
│   ├── pr-template.md            # Fill-in PR description template
│   ├── pr-example.md             # Filled-in PR description example
│   ├── review-checklist.md       # Self-review checklist before submitting
│   └── visual-evidence.md        # Screenshot policy, pitfalls, and examples
└── scripts/
    ├── check-pr-readiness.py     # Automated PR hygiene checks
    └── check-visual-evidence.py  # Mechanical PR Markdown lint

Repository-only evidence lives outside the installable skill: evidence/ contains the dated PR-corpus receipt, while evals/results/ contains the post-run source-annotated model-eval proof bundle and sanitized outputs. The current Harness metadata does not attest the skill-tree bytes used at execution.

Usage

Once installed, the skill activates when you ask your coding agent for help with pull requests:

• "Review my PR before I submit it"
• "Help me write a PR description for this diff"
• "I'm contributing to an open source project, check my changes"
• "Why do my PRs keep getting rejected?"

You can also run the readiness check script directly:

python3 skills/good-pr/scripts/check-pr-readiness.py main

Pass a drafted PR body as the second argument. Use the optional third argument to choose generated when programmatic output changes, or none after you have documented why the change has no visible impact:

python3 skills/good-pr/scripts/check-pr-readiness.py main /tmp/pr-body.md
python3 skills/good-pr/scripts/check-pr-readiness.py main /tmp/pr-body.md generated
python3 skills/good-pr/scripts/check-pr-readiness.py main /tmp/pr-body.md none

Or run the evidence lint directly. It checks only mechanical properties such as section/media presence, Markdown mistakes, alt/link text, immutable repository URLs, and labelled base/head SHAs. The skill text—not this script—asks the agent and reviewer to judge the visible claim, same input, reproduction path, correctness check, limitation, and proportionality. Direct generated mode validates SHA shape; the readiness wrapper additionally binds those labels to the checked-out merge-base and HEAD.

python3 skills/good-pr/scripts/check-visual-evidence.py --kind ui /tmp/pr-body.md
python3 skills/good-pr/scripts/check-visual-evidence.py --kind generated /tmp/pr-body.md

Warnings remain advisory by default. Add --strict only when the target repository explicitly treats every mechanical warning as blocking.

Credits

• Original insight: @lukeparkerdev — tweet
• Skill implementation: Agent Skills-compatible instructions, tested across the shared skill eval harness

License

MIT