How to use the Prepare Paperclip PR agent skill

What the skill makes the agent do

A skill is a folder containing a SKILL.md file with instructions that an agent reads when a task matches the skill's description. This one turns a branch of work into a reviewed, green pull request against the master branch of paperclipai/paperclip. It is meant to be run once per PR, so if one branch is split into several PRs, the full procedure is repeated for each.

• Works in a separate git worktree on a dedicated branch, so the main ~/paperclip checkout (which typically runs the live Paperclip server) is never switched to another branch.
• Makes logical commits of all uncommitted changes and ends each commit message with the Co-Authored-By: Paperclip line from the source.
• Rebases the branch onto the latest target master so the PR has no merge conflicts.
• Avoids committing pnpm-lock.yaml and changes to .github/workflows/* unless the task calls for them.
• Keeps each PR under 100 changed files, and makes database migrations idempotent and correctly numbered.
• Opens the PR following the project's CONTRIBUTING.md and pushes with gh.
• Runs the /greploop and /prcheckloop company skills until Greptile reaches 5/5 and checks pass.
• Reports the PR URLs, worktree path, Greptile score and check status back to the task.

Install the skill

Option 1: download the ZIP of the skill from this page and unzip it into your personal skills folder, ~/.claude/skills/. To make it available only inside one project, unzip it into that project's .claude/skills/ folder instead.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

Trigger the skill with a natural request

You do not need a special command. Ask the agent in plain language to get work ready for a Paperclip PR, and the agent should match the request to the skill's description. The skill's description is: prepare a Paperclip branch for PR with commits, template body, and checks.

Name the situation clearly: that the work is for paperclipai/paperclip, and whether the branch should become one PR or several.

• Prepare this branch for a Paperclip PR and run the review loops until Greptile is 5/5.
• Get my changes ready as a PR to paperclipai/paperclip master, then report the PR URL and worktree path.
• This branch covers two features. Split it into two PRs and prepare each one.

What you need before you start

The skill assumes a working setup for the Paperclip repository. Check these before you trigger it.

• git with worktree support.
• GitHub CLI (gh) with access to the target repository.
• pnpm, since the lockfile rule implies a pnpm project.
• Access to the Greptile review integration and the Paperclip company skills /greploop and /prcheckloop.
• Network access to GitHub and to the paperclipai/paperclip CONTRIBUTING.md file.

Safety notes: scripts and network

This skill does not run scripts of its own. It does use the network: the agent fetches the remote, pushes the branch, opens pull requests with gh, and reads CONTRIBUTING.md from GitHub. It also tells the agent to push and to keep repeating review loops until Greptile reports 5/5, with a maximum of 20 turns in the greploop step.

Because of that, review the agent's work before it pushes or opens a PR if you are not sure about the changes. The skill's own hard rules say to never lose work and never force-push in a way that discards commits.

• The skill hard-codes paperclipai/paperclip rules, remotes and tooling. Do not use it on other projects.
• Check the worktree path and branch before the agent starts, so it does not work in your main checkout.

Tips for good results

The skill is strict about its checklist, so most of the value comes from giving the agent a clear task. Tell it which remote to target if it is not master on paperclipai/paperclip, since the skill says the task may name a remote such as origin or public-gh.

If a single branch holds several unrelated changes, say so up front so the agent splits it into separate PRs and runs the whole procedure for each.

• Name the target remote and branch explicitly.
• Ask for a report at the end so you have the PR URLs, worktree path and Greptile score in one place.
• Keep each PR focused; the skill will split a PR over 100 changed files.