Guide · Agent skill
How to use the PR Merge Assistant agent skill (pr-merge)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The pr-merge skill is a set of written instructions that teaches an AI agent how to merge outside contributors' pull requests into a GitHub repository while keeping the contributor credited as the commit author. It is aimed at maintainers of open-source projects who regularly receive external PRs. After following this guide you will know what the skill does, how to install it, how to phrase a request that triggers it, and what to check before anything is pushed.
PR Merge AssistantHKUDS/OpenHarness · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the pr-merge ZIP from this page and unzip it so the pr-merge folder contains SKILL.md and references/merge-scenarios.md.
- 2Place it in a skills folder. Move the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check the prerequisites. Confirm git is installed, gh is authenticated with write access to the target repository, and Python has ruff and pytest available.
- 4Ask for a merge in plain language. Describe the task, for example merging the open PRs on a named repository while keeping contributors credited.
- 5Review the triage plan. Let the agent list open PRs and classify each one before any merge command runs.
- 6Run post-merge checks. Confirm ruff and pytest pass locally before the agent pushes to main.
- 7Verify the attribution checklist. Check that the original author appears in git log and that merged PRs reference their numbers.
What is an agent skill and what does pr-merge make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This one lives at .claude/skills/pr-merge in the HKUDS/OpenHarness project and is licensed MIT.
Once loaded, the agent follows a fixed workflow for outside pull requests: it triages open PRs, prefers GitHub's squash merge so the contributor stays credited, fetches and merges a PR branch locally when there are conflicts, can exclude specific files in a partial merge, closes duplicate PRs with a thank-you comment, and runs lint and tests before pushing.
- Triage open PRs and classify each as merge directly, merge with conflict resolution, selective merge, or close
- Merge clean PRs with gh pr merge --squash
- Handle conflicting PRs by fetching the PR branch and merging it
- Skip files already implemented locally using --exclude
- Close duplicate or superseded PRs with a comment
- Run ruff and pytest before pushing
How do you install the pr-merge skill?
Download the ZIP of the skill from this page and unzip it. For a personal setup, place the pr-merge folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
What does the pr-merge skill need before you start?
The skill expects several tools to be available. It calls git, and it calls the GitHub CLI (gh), which must be authenticated with write access to the target repository. The post-merge checks use Python with ruff and pytest. The final end-to-end check refers to a separate harness-eval skill.
- Git command-line tool
- GitHub CLI (gh), authenticated with write access to the target repository
- Python with ruff and pytest for post-merge checks
- The harness-eval skill, referenced for end-to-end verification
How do you trigger the skill with a natural request?
The skill loads when your request matches its description. The description lists example phrases: "merge a PR", "review and merge pull requests", "integrate external contributions", "handle PR conflicts", "cherry-pick from a PR", or asking to merge GitHub PRs while maximizing contributor attribution. Plain wording close to these works well.
Name the repository and the PR numbers when you can, since the commands in the skill take OWNER/REPO and NUMBER placeholders.
- "Review and merge the open pull requests on OWNER/REPO, keeping the contributors credited."
- "Handle the conflicts in PR 14 and merge it."
- "Cherry-pick everything from PR 17 except CHANGELOG.md."
- "Close PR 21 as a duplicate of PR 19 and thank the author."
What do typical merges look like?
For a clean PR, the skill prefers a squash merge through GitHub so authorship is preserved automatically. The reference file gives this example, where the subject is set to a conventional-commit style message:
- Clean PR: squash merge keeps the author visible in git log
- Conflicting PR: fetch the branch, merge it, resolve conflicts keeping both sides where possible, then commit
- CHANGELOG.md conflicts are almost universal, so the skill excludes that file and merges its sections by hand
gh pr merge 17 --repo HKUDS/OpenHarness --squash \
--subject "feat(skills): add diagnose skill (#17)"What safety rules and risks should you know about?
The skill runs scripts and uses the network, because it calls GitHub through gh and pushes with git. Its own workflow includes commands that push to main and close PRs, so only run it against a repository you maintain or have permission to push to.
The skill warns against two habits. Applying a diff and committing it yourself loses the original author. Force-pushing main after a merge may remove contributor commits. Avoid both. Also note that the attribution checklist asks you to confirm the author in git log, reference the PR number, explain any exclusions, and thank contributors on closed PRs before pushing.
- Only use it on repositories you maintain or can push to
- Never run git apply followed by a self-commit
- Do not force-push main
- Check the attribution checklist before pushing
- Run lint and tests even when the merge is clean
What tips make the skill work better?
Treat the skill as a checklist-driven workflow and review each step the agent proposes, especially the push. Keep the reference file next to SKILL.md, since it contains worked examples for clean, CHANGELOG-only, conflicting UI file and duplicate scenarios.
When you exclude files, ask the agent to record what was skipped in the commit body. This is what the checklist expects.
- Review the agent's commands before the push step
- Use the reference examples for the scenario closest to yours
- Ask for exclusions to be documented in the commit message
- Confirm the original author appears in git log afterwards
What people use it for
- Merging a clean feature PR from an outside contributor with a squash merge that keeps their name in git log
- Resolving a conflicting PR by fetching its branch and merging it, then fixing conflicts in a separate commit
- Taking part of a PR while excluding files already implemented locally, and documenting the exclusions
- Closing a duplicate PR with a comment that thanks the contributor for their investigation
Frequently asked questions
How do I install the pr-merge agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Is the pr-merge skill free to use?
The skill is licensed under MIT, as stated on this page. The skill itself does not state a price, and it requires your own git and GitHub CLI setup.
What do I need to run pr-merge?
You need the git command-line tool, the GitHub CLI (gh) authenticated with write access to the repository, and Python with ruff and pytest. The final verification step refers to the harness-eval skill.
Will the merge keep the contributor's name on their commits?
The skill prefers gh pr merge --squash for clean PRs, which keeps the author visible in git log. For manual merges it uses --author with the contributor's name and email, and it warns that applying a diff and committing it yourself loses the author.
Can the agent merge only part of a pull request?
Yes. The selective merge workflow uses --exclude to skip files that are already implemented locally, and the commit body should record what was excluded. The skill also says CHANGELOG.md should always be excluded and handled manually.
Should I use pr-merge on a repository I do not maintain?
No. The skill includes commands that push to main and close PRs, so it should only be used on repositories you maintain or have permission to push to. It is also not suited to solo or private projects with no outside contributors.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
The pr-merge skill suits maintainers of open-source repositories who regularly receive outside pull requests and want a consistent, contributor-credited merge process an AI agent can follow. Skip it for solo or private projects without outside contributors, for repositories you do not have push rights to, or for workflows that depend on force-pushes or rebasing shared branches.
Download the skill