Guide · Agent skill
How to use the PR Gardening agent skill (pr-gardening)
Updated · written with AI from the project's own documentation and checked against our catalogue data
PR Gardening is an agent skill for Paperclip deployments. It finds the pull requests your Paperclip instance opened, checks each one's current head for readiness, and can drive non-ready PRs toward green using the separate /prepare-paperclip-pr skill. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before you run it. It never merges, approves, or closes anything.
PR Gardeningpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download the ZIP. Download the pr-gardening skill ZIP from this page.
- 2Install the skill. Unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Set up credentials and tools. Install Node.js 20 or later, log in to gh with read access, and set PAPERCLIP_API_URL, PAPERCLIP_API_KEY and PAPERCLIP_COMPANY_ID.
- 4Ask for a dry run. Make a plain request for a readiness sweep and make sure the run is a dry run.
- 5Review candidates and verdicts. Read candidates.json and readiness.json to see ready, needs_gardening and report_only entries.
- 6Decide what to merge yourself. Use the report to decide what to merge. The skill itself will not merge, approve or close anything.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md instruction file and optional scripts that an AI agent can load when a task matches its description. The skill's SKILL.md tells the agent the workflow to follow.
PR Gardening finds pull requests opened by your own Paperclip instance that are referenced by Paperclip issues active in a recent window (14 days by default). Candidate discovery and readiness checks are done by scripts, not by the model. For each PR, the readiness check looks at open or draft state, mergeability and conflicts, status checks, a Greptile check-run on the exact head, review decision, and commits behind the base branch. Each PR gets a verdict of ready, needs_gardening, or report_only for drafts.
- Community contributions and dependabot PRs are excluded by author login.
- Draft PRs are report-only; no gardening comments are posted on them.
- Non-ready PRs can be handed to /prepare-paperclip-pr, a separate skill, for gardening.
- The skill is forbidden from merging, approving, or closing pull requests.
Install the PR Gardening skill
Download the ZIP for the skill from this page. You can install it in one of three places, depending on how you use the agent.
For a personal setup, unzip the download into ~/.claude/skills/ so the pr-gardening folder sits inside it. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/pr-gardening/
- Project: .claude/skills/pr-gardening/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Prepare your environment before running it
The skill depends on Paperclip's API and issue data, so it only works inside a Paperclip deployment. Make sure the following are in place before you ask the agent to run it.
The source lists Node.js 20 or later, GitHub CLI (gh) authenticated with read access to the repository, and Paperclip API credentials. The credentials are PAPERCLIP_API_URL, PAPERCLIP_API_KEY and PAPERCLIP_COMPANY_ID. The gardening stage also needs the /prepare-paperclip-pr skill, and curl is listed among the allowed tools.
- Node.js 20 or later
- GitHub CLI (gh) logged in with read access to the repository
- PAPERCLIP_API_URL, PAPERCLIP_API_KEY and PAPERCLIP_COMPANY_ID set in the run environment
- The /prepare-paperclip-pr skill, needed only for the gardening stage
- curl, which is in the allowed tools list
Trigger the skill with a natural request
You do not need to type a script name. Ask the agent in plain language, and the skill's description should match. Good requests name the goal: a readiness sweep of your open PRs, or a check on PRs tied to recent issues.
Because unattended runs can post comments and create tasks, start with a dry run. A dry run discovers and verifies PRs and produces a report without posting comments, creating prepare tasks, or archiving inbox entries.
- "Run a PR gardening dry run and tell me which of our open PRs are merge-ready."
- "Check readiness of the pull requests our Paperclip issues mention from the last 14 days."
- "Sweep our PRs from the last week and show me the verdict for each one. Don't post anything."
Understand the options and dry-run mode
The skill accepts a small set of inputs. You can pass them in your request or let the defaults apply. Generated files go in a run-owned directory such as $PAPERCLIP_RUN_SCRATCH_DIR/pr-gardening.
--dry-run discovers, verifies and reports without posting comments, creating prepare tasks, or archiving inbox entries. Discovery and GitHub inspection stay read-only in every mode.
- --days <N>: activity window, default 14
- --authors <logins>: GitHub logins whose PRs are in scope; default is the gh authenticated user
- --repo <owner/repo>: repository, default detected by gh repo view
- --dry-run: report only, no Paperclip mutations
- --archive-inbox: archive the originating issue from the responsible user's inbox after GitHub confirms the PR is merged at its current head
- --cooldown-hours <N>: default 48
- --max-rounds <N>: default 3
node .agents/skills/pr-gardening/scripts/find-candidates.mjs \n --days 14 \n --dry-run \n --output "$RUN_DIR/candidates.json"Read the output and know the safety limits
Discovery writes candidates.json, and the readiness check writes readiness.json. Readiness should be rerun after any claim that a PR was fixed, because issue comments are not treated as proof of readiness.
The skill's guardrails are strict. It never merges, approves or closes a PR, and it never instructs another person or agent to do so. It does not garden community PRs. The scripts only use gh pr view and read-only gh api GET requests. The source notes that runs without a dry-run can post comments, create follow-up issues and archive inbox entries, and it notes that scripts run and the network is used.
- Scripts run and the skill uses the network, so review the scripts before installing.
- Community PRs are excluded by design; widening scope needs an explicit --authors or --include-community.
- Do not run unattended without a dry-run first.
- The skill stops after three rounds per PR and recommends a human decision rather than closing it.
What people use it for
- A maintainer runs a weekly dry-run sweep of the PRs their Paperclip instance opened.
- A team tracking PR work through Paperclip issues checks which linked PRs have failing checks or conflicts.
- A developer gets a scripted, read-only readiness report before deciding what to merge.
- A team sends non-ready PRs to /prepare-paperclip-pr so a coder agent can push them toward green.
Frequently asked questions
Is the PR Gardening skill free and what is its licence?
The source lists the licence as MIT. The source does not mention pricing, so check the repository for any cost details.
What do I need to install and run the pr-gardening skill?
You need Node.js 20 or later, GitHub CLI (gh) authenticated with read access to the repository, and Paperclip API credentials (PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID). The gardening stage also needs the /prepare-paperclip-pr skill.
Where do I put the pr-gardening skill folder?
Unzip the download into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Will the skill merge or approve my pull requests?
No. The skill is forbidden from merging, approving or closing any pull request, and it never tells another person or agent to do so. Its GitHub access is read-only.
Can it review community or external contributors' PRs?
No. Community contributions and dependabot PRs are excluded by author login, and the skill is forbidden from touching them. Widening scope requires an explicit --authors or --include-community request.
Does it work outside Paperclip, or is it a general PR tool?
It is not a general PR tool. It depends on Paperclip's API and issue data, so it only works inside a Paperclip deployment.
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
PR Gardening suits maintainers of a Paperclip instance who want a regular, scripted, read-only readiness sweep of their own open PRs, especially when those PRs are tracked through Paperclip issues. It is a poor fit for reviewing outside contributions, for anyone not running Paperclip, or for unattended runs that skip the dry-run step.
Download the skill